Эх сурвалжийг харах

feat(memory): introduce .claude/{tasks,memory,audits}/ governance layout

Move tasks/ into .claude/tasks/ and create .claude/memory/ with 5
persistent registries (decisions/learnings/blockers/journal/evals) plus
.claude/audits/ for audit reports. Also seed templates/memory/ for
onboarder to copy into user projects.

- tasks/TODO.md, tasks/rtk-upstream-issue.md → .claude/tasks/
- tasks/LESSONS.md deleted (empty template; superseded by learnings.md)
- .claude/memory/: 5 append-only registries with YAML schema + seed entries
- templates/memory/: 5 empty-index templates for new projects

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
bastien 3 долоо хоног өмнө
parent
commit
892de288fe

+ 36 - 0
.claude/memory/blockers.md

@@ -0,0 +1,36 @@
+---
+type: blockers_registry
+entry_prefix: BLK
+schema:
+  id: BLK-XXX
+  date: YYYY-MM-DD
+  friction: string (what was blocked)
+  real_cause: string (root cause, not symptom)
+  solution: string (workaround or fix)
+  status: [open | resolved | upstream]
+rules:
+  - Open a blocker as soon as friction > 15 min wasted. Close it with a real cause, not "moved on".
+  - Link to upstream issue / PR / commit when applicable.
+  - If cause is a bug in a dependency, set status upstream with a pointer to the tracker.
+---
+
+# Blockers registry (BLK)
+
+## Index
+
+| ID | Date | Friction | Status |
+|----|------|---------|--------|
+| BLK-001 | 2026-04-22 | `rtk curl` breaks JSON pipelines | upstream |
+
+---
+
+## BLK-001 — `rtk curl` returns compressed schema in pipes
+
+- **Date** : 2026-04-22
+- **Friction** : toute pipeline `rtk curl ... | python -c "json.load(sys.stdin)"` (ou `jq`, `awk`) échoue sans message clair.
+- **Cause réelle** : `rtk curl` auto-compresse stdout indépendamment du TTY — documenté dans `.claude/tasks/rtk-upstream-issue.md`.
+- **Solution** :
+  - Workaround court terme : `exclude_commands=["curl"]` dans `~/.config/rtk/config.toml`.
+  - Workaround alternatif : utiliser `rtk proxy`.
+  - Fix upstream : issue reportée, voir `.claude/tasks/rtk-upstream-issue.md`.
+- **Statut** : upstream (bug chez `rtk`, workaround appliqué).

+ 51 - 0
.claude/memory/decisions.md

@@ -0,0 +1,51 @@
+---
+type: decisions_registry
+entry_prefix: BDR
+schema:
+  id: BDR-XXX
+  date: YYYY-MM-DD
+  title: string (<= 80 chars)
+  decision: string (what was chosen)
+  why: string (motivation, context)
+  alternatives: list of strings (what was rejected + why)
+  status: [proposed | accepted | deprecated | superseded]
+  supersedes: BDR-XXX (optional)
+rules:
+  - Append-only. Never rewrite past entries - add a new one with status superseded if needed.
+  - One entry per non-trivial choice. Trivial = reversible in under 10 min with no cross-file impact.
+  - Capture why more carefully than what - the what rots, the why lasts.
+---
+
+# Decisions registry (BDR)
+
+## Index
+
+| ID | Date | Title | Status |
+|----|------|-------|--------|
+| BDR-001 | 2026-04-22 | --help helper uniforme via hook post-start (option C) | accepted |
+| BDR-002 | 2026-04-23 | Restructurer tasks/ + memory + audits sous .claude/ | accepted |
+
+---
+
+## BDR-001 — --help helper uniforme via hook post-start (option C)
+
+- **Date** : 2026-04-22
+- **Statut** : accepted
+- **Décision** : tous les skills exposent `--help` via un snippet partagé injecté par le session-start hook, plutôt que dupliquer le helper dans chaque SKILL.md.
+- **Pourquoi** : 25+ skills, maintenir le même helper dans chaque fichier = drift garanti. Un point d'injection = une seule source de vérité.
+- **Alternatives rejetées** :
+  - Option A (copier le helper dans chaque SKILL.md) — refusée : entropie de maintenance.
+  - Option B (wrapper externe `/help <skill>`) — refusée : casse l'expérience "une commande = un skill".
+- **Référence** : commit 3968a29.
+
+## BDR-002 — Restructurer tasks/ + memory + audits sous .claude/
+
+- **Date** : 2026-04-23
+- **Statut** : accepted
+- **Décision** : migrer `./tasks/` vers `.claude/tasks/`, créer `.claude/memory/` (5 registres BDR/LRN/BLK/journal/EVAL) et `.claude/audits/` pour les fichiers AUDIT_*. Adapter skills/agents/CLAUDE.md. Intégrer un rituel de capitalisation dans les skills de complétion (ship-feature, feat, bugfix, hotfix, commit-change) + créer un skill `/close` pour le rituel de fin de session.
+- **Pourquoi** : regrouper tout le méta-projet (config IA + tâches + mémoire + audits) sous `.claude/` isole la gouvernance Claude du code réel. Alignement sur la doc officielle Claude Code memory. Sans intégration dans les skills, les registres resteraient vides (aspirational text).
+- **Alternatives rejetées** :
+  - Laisser `./tasks/` à la racine — refusée : encombre le repo, mélange signal code / signal gouvernance.
+  - Utiliser `.claude/agent-memory/` pour tout — refusée : `agent-memory/` a un rôle distinct (déjà utilisé par d'autres outils).
+  - Rituel uniquement en texte aspirationnel dans CLAUDE.md — refusée : zéro garantie d'exécution, les registres resteraient vides.
+  - Hook `Stop` pour poser les 3 questions à chaque tour — refusée : trop bruyant.

+ 34 - 0
.claude/memory/evals.md

@@ -0,0 +1,34 @@
+---
+type: evals_registry
+entry_prefix: EVAL
+schema:
+  id: EVAL-XXX
+  date: YYYY-MM-DD
+  output: string (what was produced)
+  method: string (how it was evaluated - manual read, test, benchmark, user feedback)
+  anomalies: list of strings (what was wrong, missing, surprising)
+  action: [keep | correct | deprecate]
+rules:
+  - Log an eval whenever you validate the quality of something Claude produced (report, audit, plan, generated code).
+  - Action keep - the output is fit for purpose as-is.
+  - Action correct - needs revision; capture what.
+  - Action deprecate - the approach itself is flawed; link to the decision that replaces it.
+---
+
+# Evals registry (EVAL)
+
+## Index
+
+| ID | Date | Output | Action |
+|----|------|--------|--------|
+| EVAL-001 | 2026-04-23 | Plan de restructuration .claude/ (STEP 2 de ship-feature) | keep |
+
+---
+
+## EVAL-001 — Plan de restructuration `.claude/`
+
+- **Date** : 2026-04-23
+- **Output** : plan 21 tâches pour migrer `tasks/` vers `.claude/tasks/` + créer `.claude/memory/` + `.claude/audits/` + intégrer CAPITALIZE dans 5 skills + créer `/close`.
+- **Méthode** : relecture manuelle des 5 skills/agents impactés, vérification que rtk est path-agnostic, symlink `~/.claude/CLAUDE.md` → projet confirmé (un seul fichier à éditer). Radical-honesty check sur le ritual "session-close" : confirmé comme aspirationnel sans intégration dans les skills → scope élargi à Option D.
+- **Anomalies** : aucune bloquante. Note : `tasks/LESSONS.md` était vide (101B, juste un header) — migration vers `learnings.md` symbolique.
+- **Action** : keep — plan validé, prêt pour exécution.

+ 19 - 0
.claude/memory/journal.md

@@ -0,0 +1,19 @@
+---
+type: journal
+schema:
+  entry: one date heading per working session
+  body: 3-5 lines max - what was done, decided, blocked
+rules:
+  - One heading per date (YYYY-MM-DD), not per session.
+  - Append at the end. Never edit past entries.
+  - Keep it terse. Details belong in decisions/learnings/blockers - this is a timeline only.
+---
+
+# Journal
+
+## 2026-04-23
+
+- Restructuré l'arborescence : `tasks/` → `.claude/tasks/`, créé `.claude/memory/` (5 registres) + `.claude/audits/`.
+- Adapté CLAUDE.md + skills `onboard`, `init-project` + agent `onboarder` + `lib/project-archetypes/dotfiles-meta.md`.
+- Ajouté un step CAPITALIZE dans `ship-feature`, `bugfix`, `hotfix`, `feat`, `commit-change` + créé skill `/close` pour rituel de fin de session.
+- Décision BDR-002 actée.

+ 32 - 0
.claude/memory/learnings.md

@@ -0,0 +1,32 @@
+---
+type: learnings_registry
+entry_prefix: LRN
+schema:
+  id: LRN-XXX
+  date: YYYY-MM-DD
+  pattern: string (what was observed, abstracted)
+  context: string (where/when it happened - concrete)
+  future_application: string (when to recall this)
+rules:
+  - Capture learnings that apply beyond the current task.
+  - Abstract from the incident - the pattern is what is reusable, not the one-shot fact.
+  - Link to source (commit, file, PR) when possible.
+  - Replaces the previous LESSONS.md format. Old file was empty - no content to migrate.
+---
+
+# Learnings registry (LRN)
+
+## Index
+
+| ID | Date | Pattern | Applies to |
+|----|------|---------|------------|
+| LRN-001 | 2026-04-22 | `rtk` shape-compression breaks pipes | any pipeline chaining `rtk curl/cat/read` into `jq`, `python -c`, `awk` |
+
+---
+
+## LRN-001 — `rtk` shape-compression breaks downstream parsers
+
+- **Date** : 2026-04-22
+- **Pattern** : quand un outil de tracking (`rtk`) intercepte stdout et retourne une représentation schématisée/compressée au lieu du payload brut, tout parseur en aval casse silencieusement — parce que l'utilisateur (ou le LLM) ne voit jamais la sortie `rtk`, seulement l'erreur du parseur.
+- **Contexte** : `rtk curl` remplace la sortie JSON brute par une version tokenisée, indépendamment du TTY vs pipe. Les hooks Claude Code réécrivent `curl` → `rtk curl` automatiquement, donc impossible à prévoir sans connaître le hook.
+- **Application future** : pour tout outil qui auto-réécrit des commandes standard, vérifier explicitement le comportement en pipe. Workaround documenté : `exclude_commands=["curl"]` dans `~/.config/rtk/config.toml`, ou `rtk proxy`. Voir `BLK-001`.

+ 0 - 0
tasks/TODO.md → .claude/tasks/TODO.md


+ 0 - 0
tasks/rtk-upstream-issue.md → .claude/tasks/rtk-upstream-issue.md


+ 0 - 4
tasks/LESSONS.md

@@ -1,4 +0,0 @@
-# Lessons
-
-| Date | What went wrong | Rule to avoid it |
-|------|----------------|-----------------|

+ 34 - 0
templates/memory/blockers.md

@@ -0,0 +1,34 @@
+---
+type: blockers_registry
+entry_prefix: BLK
+schema:
+  id: BLK-XXX
+  date: YYYY-MM-DD
+  friction: string (what was blocked)
+  real_cause: string (root cause, not symptom)
+  solution: string (workaround or fix)
+  status: [open | resolved | upstream]
+rules:
+  - Open a blocker as soon as friction > 15 min wasted. Close it with a real cause, not "moved on".
+  - Link to upstream issue / PR / commit when applicable.
+  - If cause is a bug in a dependency, set status upstream with a pointer to the tracker.
+---
+
+# Blockers registry (BLK)
+
+## Index
+
+| ID | Date | Friction | Status |
+|----|------|---------|--------|
+
+<!-- Append entries below. Template:
+
+## BLK-XXX - <friction>
+
+- **Date** : YYYY-MM-DD
+- **Friction** : <ce qui était bloqué>
+- **Cause réelle** : <cause racine>
+- **Solution** : <workaround ou fix>
+- **Statut** : open | resolved | upstream
+
+-->

+ 39 - 0
templates/memory/decisions.md

@@ -0,0 +1,39 @@
+---
+type: decisions_registry
+entry_prefix: BDR
+schema:
+  id: BDR-XXX
+  date: YYYY-MM-DD
+  title: string (<= 80 chars)
+  decision: string (what was chosen)
+  why: string (motivation, context)
+  alternatives: list of strings (what was rejected + why)
+  status: [proposed | accepted | deprecated | superseded]
+  supersedes: BDR-XXX (optional)
+rules:
+  - Append-only. Never rewrite past entries - add a new one with status superseded if needed.
+  - One entry per non-trivial choice. Trivial = reversible in under 10 min with no cross-file impact.
+  - Capture why more carefully than what - the what rots, the why lasts.
+---
+
+# Decisions registry (BDR)
+
+## Index
+
+| ID | Date | Title | Status |
+|----|------|-------|--------|
+
+<!-- Append entries below. Template:
+
+## BDR-XXX - <titre>
+
+- **Date** : YYYY-MM-DD
+- **Statut** : proposed | accepted | deprecated | superseded
+- **Décision** : <ce qui a été choisi>
+- **Pourquoi** : <motivation>
+- **Alternatives rejetées** :
+  - Option A - <raison du rejet>
+  - Option B - <raison du rejet>
+- **Référence** : <commit / PR / fichier>
+
+-->

+ 35 - 0
templates/memory/evals.md

@@ -0,0 +1,35 @@
+---
+type: evals_registry
+entry_prefix: EVAL
+schema:
+  id: EVAL-XXX
+  date: YYYY-MM-DD
+  output: string (what was produced)
+  method: string (how it was evaluated - manual read, test, benchmark, user feedback)
+  anomalies: list of strings (what was wrong, missing, surprising)
+  action: [keep | correct | deprecate]
+rules:
+  - Log an eval whenever you validate the quality of something Claude produced (report, audit, plan, generated code).
+  - Action keep - the output is fit for purpose as-is.
+  - Action correct - needs revision; capture what.
+  - Action deprecate - the approach itself is flawed; link to the decision that replaces it.
+---
+
+# Evals registry (EVAL)
+
+## Index
+
+| ID | Date | Output | Action |
+|----|------|--------|--------|
+
+<!-- Append entries below. Template:
+
+## EVAL-XXX - <output>
+
+- **Date** : YYYY-MM-DD
+- **Output** : <ce qui a été produit>
+- **Méthode** : <comment cela a été évalué>
+- **Anomalies** : <ce qui est faux, manquant, surprenant>
+- **Action** : keep | correct | deprecate
+
+-->

+ 22 - 0
templates/memory/journal.md

@@ -0,0 +1,22 @@
+---
+type: journal
+schema:
+  entry: one date heading per working session
+  body: 3-5 lines max - what was done, decided, blocked
+rules:
+  - One heading per date (YYYY-MM-DD), not per session.
+  - Append at the end. Never edit past entries.
+  - Keep it terse. Details belong in decisions/learnings/blockers - this is a timeline only.
+---
+
+# Journal
+
+<!-- Append new date-heading entries below. Template:
+
+## YYYY-MM-DD
+
+- <ligne 1>
+- <ligne 2>
+- <ligne 3-5 max>
+
+-->

+ 32 - 0
templates/memory/learnings.md

@@ -0,0 +1,32 @@
+---
+type: learnings_registry
+entry_prefix: LRN
+schema:
+  id: LRN-XXX
+  date: YYYY-MM-DD
+  pattern: string (what was observed, abstracted)
+  context: string (where/when it happened - concrete)
+  future_application: string (when to recall this)
+rules:
+  - Capture learnings that apply beyond the current task.
+  - Abstract from the incident - the pattern is what is reusable, not the one-shot fact.
+  - Link to source (commit, file, PR) when possible.
+---
+
+# Learnings registry (LRN)
+
+## Index
+
+| ID | Date | Pattern | Applies to |
+|----|------|---------|------------|
+
+<!-- Append entries below. Template:
+
+## LRN-XXX - <pattern abstrait>
+
+- **Date** : YYYY-MM-DD
+- **Pattern** : <ce qui a été observé, formulé de manière réutilisable>
+- **Contexte** : <où et quand, concret>
+- **Application future** : <quand se rappeler de ceci>
+
+-->