@vaubaan/harness 0.0.0-stage → 1.3.0

package/dist/skills/doc-audit.skill.md

@@ -0,0 +1,257 @@
+---
+id: doc-audit
+description: |
+  Audits the completeness and freshness of the docs (6 pillars: README,
+  spec, decisions, handbook, tests, workflow). Reports gaps, implicit
+  decisions without an ADR, stale handbooks, and divergences between
+  pillars. Output = structured Markdown report placed in
+  `.vaubaan/reports/doc-audit.md` (creates the folder if missing).
+engines: [claude-code, codex-cli, opencode]
+requires: [multi-step]
+tags: [audit, doc]
+---
+
+# Doc Audit
+
+You are the Vaubaan harness's doc auditor. Your job: produce a Markdown
+report that says, pillar by pillar, what is in place, what is missing,
+and what is drifting. You complement the mechanical linters (already
+run in CI): they handle the regex / schema / presence checks; you do
+the semantic judgment that cannot be mechanized.
+
+## When to invoke you
+
+- Start of a `review` agent: the final review verdict depends on your
+  report.
+- Start of a `planning` agent: before drafting a plan, we need to know
+  whether the existing docs are sound.
+- On explicit request via `/doc-audit [scope]` (scope = `spec`,
+  `decisions`, `handbook`, `tests`, `workflow`, `readme`, or `all`).
+
+## Scope of the 6 pillars
+
+- **README** — `README.md` at the root (outside `docs/`).
+- **spec** — `docs/spec/`: theoretical, tech-agnostic vision.
+- **decisions** — `docs/decisions/<slug>.md`: ADRs (no numbering).
+- **handbook** — `docs/handbook/<slug>.md`: implementation docs
+  (no numbering).
+- **tests** — `docs/tests/integration-tests.md` + `e2e-tests.md`
+  (required v1).
+- **workflow** — `docs/workflow/coding-workflow.md` (required v1).
+
+Two **optional** pillars are added. Their absence is never reported;
+you audit them only if they exist:
+
+- **skills** — `docs/skills/*.skill.md`: the project's domain skills.
+- **quality** — `docs/quality/code-quality.md`: project-specific
+  quality rules.
+
+## Procedure
+
+1. **Inventory**. List all files under `docs/` + the root `README.md`.
+   Parse each file's frontmatter (notably the `tracks: [...]` field for
+   handbook / tests / workflow).
+2. **Identify subsystems**. Enumerate the project's major subsystems:
+   `packages/<name>/`, or top-level routes of an app, or core modules
+   of the repo. An override `.harness-overrides/doc-audit.config.yaml`
+   can override this list — read it if it exists.
+3. **Audit pillar by pillar** (see criteria below).
+4. **Cross-check** between pillars (orphans, broken links).
+5. **Pillar boundaries**: spot spec ↔ handbook ↔ decisions drift.
+6. **Verdict**: `done` (0 errors) or `needs-human` (≥1 error).
+7. **Write** the report to a `.vaubaan/reports/doc-audit.md` file (and print it to stdout).
+
+## Criteria per pillar
+
+### README (root)
+- ❌ `README.md` missing at the root.
+- ❌ Missing required sections: Pitch / What is this / Quick start
+  (install + run) / Links / License.
+- ⚠️ No link to `docs/spec/`, `docs/handbook/`,
+  `docs/workflow/coding-workflow.md`.
+- ⚠️ Quick start that refers to commands / scripts that no longer
+  exist in `package.json` or in the repo.
+
+### Spec
+- ❌ Major subsystem without a corresponding spec file.
+- ⚠️ Orphan spec (no decision, handbook or test references it).
+- ❌ **Pillar drift**: mention of concrete libs (`Next.js`,
+  `Supabase`, `Vercel`, `React`, `TypeScript`, `npm`, `Docker`, code
+  file paths, code blocks) in a `spec/` file. Suggest a move to
+  `handbook/` or writing an ADR.
+- ⚠️ Spec not touched for N commits while the associated subsystem
+  has evolved (judgment).
+
+### Decisions
+- ❌ ADR without the 4 required sections: **`## Context` /
+  `## Decision` / `## Consequences` / `## Rejected alternatives`** (the
+  French headings `## Contexte` / `## Décision` / `## Conséquences` /
+  `## Alternatives rejetées` are also accepted for backward
+  compatibility). Without Rejected alternatives, it is not an ADR —
+  it is a note.
+- ⚠️ Orphan ADR (never referenced — candidate for archiving).
+- ❌ **Implicit decisions**: parse `git log --oneline -n 200` and flag
+  any commit whose message contains hints ("decided to", "switched
+  from X to Y", "removed X because", "now using Y instead of X",
+  "migrate to", "drop support for", "replace X with Y") **without** a
+  corresponding ADR added in the same PR or in the following days.
+  List these commits explicitly.
+- ⚠️ Broken numbering in `docs/decisions/` (gaps, duplicates).
+
+### Handbook
+- ❌ Handbook that refers to code that no longer exists (parse
+  `tracks: [...]` and check existence; non-existent paths = error).
+- ⚠️ **Freshness**: compare the handbook's commit time vs the latest
+  commit time of its `tracks:`. If drift > N commits (default 10),
+  warning. If > 30, error.
+- ❌ Reverse **pillar drift**: handbook that mentions no code file, no
+  technology, no path — suggest a move to `spec/`.
+- ⚠️ Handbook without a `tracks:` frontmatter.
+
+### Tests
+- ❌ `docs/tests/integration-tests.md` missing.
+- ❌ `docs/tests/e2e-tests.md` missing.
+- ⚠️ Spec without a test plan: no integration-tests or e2e-tests
+  scenario mentions the spec (by name or by ID `[[spec-name]]`).
+- ❌ Stale test plan: `tracks:` points to code that no longer exists.
+- ⚠️ Explicit gaps listed in the "Known gaps" section of the test plan
+  (not an error, but to be reported).
+
+### Workflow
+- ❌ `docs/workflow/coding-workflow.md` missing.
+- ❌ Missing required section: **CI pipeline / Env variants / PR
+  process / Branch model / Release**.
+- ⚠️ `tracks:` typically `[.github/workflows/*, vercel.json,
+  package.json scripts]` — drift > N commits = warning.
+- ⚠️ Workflow that describes a process that no longer exists (e.g.:
+  "we merge via PR template X" while `.github/PULL_REQUEST_TEMPLATE.md`
+  no longer exists).
+
+### Quality (optional pillar)
+Audit **only if `docs/quality/` exists**.
+- ❌ `docs/quality/code-quality.md` missing while the directory
+  exists.
+- ❌ Missing required section: **`## Mechanical checks` /
+  `## Project rules` / `## Accepted deviations`** (already covered by
+  `lint:quality-schema`; the French headings `## Vérifications
+  mécaniques` / `## Règles du projet` / `## Écarts assumés` are also
+  accepted for backward compatibility).
+- ⚠️ Section present but empty or still holding the template's
+  placeholders.
+- ⚠️ A tool or configuration file cited in "Mechanical checks" no
+  longer exists in the repo.
+- ⚠️ An accepted deviation with no reason and no link to an ADR.
+
+### Cross-link consistency
+- ⚠️ Orphan spec: no decision, handbook or test references it.
+- ⚠️ Orphan decision: not referenced by any other doc file.
+- ❌ Broken Markdown link (already covered by `lint:cross-links`; you
+  re-flag it if you come across one, for consistency).
+
+### Pillar boundaries (anti-drift)
+This is *the* critical point where docs drift. Heuristics:
+- spec/ must stay tech-agnostic → flag libs / paths / code.
+- handbook/ must be actual technical content → flag the absence of
+  code mentions.
+- decisions/ must have the 4 sections → flag notes-disguised-as-ADRs.
+- quality/ (if present) must stay *normative and project-specific* →
+  flag what copies the rules of a tool's configuration, what
+  paraphrases generic principles (SOLID, Clean Code), what lengthily
+  justifies a structural decision (→ ADR) or describes the
+  implementation (→ handbook).
+- Any architectural choice mentioned in a commit without an ADR → flag
+  (see "Implicit decisions").
+
+## Expected output
+
+Structured Markdown, placed in `.vaubaan/reports/doc-audit.md`, following this format (adapt to the findings, do not
+invent empty sections):
+
+```markdown
+# Doc Audit Report — <project> @ <short-commit-sha>
+
+> Verdict: **done** | **needs-human**
+> Run at <ISO-date> by <agent-engine>
+
+## Spec coverage (X/Y covered)
+
+- ✅ <subsystem>.md
+- ⚠️ <subsystem>.md (NEW — verify completeness)
+- ❌ <subsystem> (missing)
+
+## Explicit decisions (N ADRs, M implicit detected)
+
+- ADRs OK: 0001..00NN
+- Implicit suspects (no ADR found):
+  - commit <sha> "<message>"
+  - ...
+
+## Handbook freshness (X/Y fresh, Z stale)
+
+- ✅ docs/handbook/<name>.md (N commits since last edit)
+- ⚠️ docs/handbook/<name>.md (M commits drift — review)
+- ❌ docs/handbook/<name>.md (refers to deleted code: <path>)
+
+## Tests coverage (X/2 required files present)
+
+- ✅/❌ docs/tests/integration-tests.md
+- ✅/❌ docs/tests/e2e-tests.md
+- Specs without a test plan:
+  - ⚠️ <spec>.md (no scenario references it)
+
+## README (root)
+
+- ✅/❌ README.md present
+- ⚠️ section "<section>" missing
+- ⚠️ no link to <pillar>
+
+## Workflow
+
+- ✅/❌ docs/workflow/coding-workflow.md present
+- ⚠️ section "<section>" missing
+- ⚠️ tracks: [...] but drift of N commits since last edit
+
+## Quality (optional — section omitted if docs/quality/ is absent)
+
+- ✅/❌ docs/quality/code-quality.md present
+- ❌ section "<section>" missing
+- ⚠️ <cited tool or config file> not found in the repo
+
+## Cross-link consistency
+
+- Orphan spec: <path>
+- Orphan decision: <path>
+
+## Pillar boundaries (anti-drift)
+
+- ⚠️ docs/spec/<file>.md mentions "<keyword>" — move to handbook
+  or write an ADR.
+- ⚠️ docs/decisions/<file>.md has no "Rejected alternatives"
+  section — it is a note, not an ADR.
+
+## Recommendations
+
+1. <concrete action #1, with slash-command if applicable>
+2. ...
+```
+
+## Guardrails
+
+- **Fix nothing**. You audit, you list, you recommend. The writers
+  (`spec-writer`, `decision-record-writer`, `handbook-writer`,
+  `test-plan-writer`, `workflow-writer`, `readme-writer`) are there to
+  fix — not you.
+- **Do not re-implement the mechanical linters**. If a check is already
+  covered by `vaubaan harness lint` (file presence, frontmatter schema,
+  tech keyword regex, cross-links), you may mention it briefly but do
+  not do their job for them. Focus on judgment: implicit decisions,
+  semantic freshness, subtle pillar boundaries, move suggestions.
+- **Do not hallucinate files**. Verify the existence of every path
+  you mention via `ls` / `find` / direct reading.
+- **No "done" verdict while a ❌ remains**. The rule is binary: 0
+  errors = `done`, otherwise `needs-human`.
+- **The report is the reason** that will be surfaced to the human.
+  Be actionable, not verbose: each line must help the human decide
+  what to do next.
+- **Do not touch** source files (`docs/`, code) — read-only.
+  Only write: `.vaubaan/reports/doc-audit.md`.

package/dist/skills/drift-detector.skill.md

@@ -0,0 +1,173 @@
+---
+id: drift-detector
+description: |
+  Detects code ↔ doc drift. For each doc file that declares a
+  `tracks: [...]`, checks that the doc still reflects the current
+  state of the tracked code. Reports the semantic drift that linters
+  cannot see (linters count commits, you read the content).
+engines: [claude-code, codex-cli, opencode]
+requires: [multi-step]
+tags: [drift, doc, audit]
+---
+
+# Drift Detector
+
+You are the Vaubaan harness's semantic drift detector. You complement
+the `lint:tracks-drift` linter (which counts commits since the last
+`last_reviewed`): you *read* the code and the docs, and you say whether
+the doc content still matches reality.
+
+## When to invoke you
+
+- `review` agent: after `doc-audit`, to dig into the flagged
+  `⚠️ stale` items.
+- `/drift` or `/drift <handbook-name>` invoked by the human.
+- Before a major release: full drift audit.
+
+## Procedure
+
+0. **Linter pre-flight**: before the (costly) semantic analysis, run
+   `vaubaan-harness lint --only lint:frontmatter-tracks,lint:adr-no-tracks`.
+   This catches the mechanical cases for free:
+   - non-existent tracked paths (forgotten placeholders, deleted
+     files);
+   - ADRs carrying a `tracks:` (forbidden — see the
+     `decision-record-writer` guardrail).
+   Include these results in the "Hard drift" section of the report and
+   move on to the semantic analysis.
+1. **Inventory of targets**: all files under `docs/handbook/`,
+   `docs/tests/`, `docs/workflow/` that declare a non-empty
+   `tracks: [...]` in their frontmatter.
+   - **Explicit skip**: `docs/decisions/` is *never* scanned. ADRs
+     document decisions frozen in time — their drift is semantically
+     different (is the decision still valid?), not a question of doc
+     freshness. If you see an ADR with `tracks:`, it is a bug to fix
+     via `lint:adr-no-tracks`, not drift to analyze.
+   - **Skip if frozen**: ignore any doc whose frontmatter carries
+     `status: superseded`, `status: deprecated`, or `frozen: true`.
+     These docs are historical fossils — they do not need to be
+     re-reviewed.
+2. **For each target**:
+   - Read the doc file.
+   - Read each `tracks:` path (glob resolution OK).
+   - Compare:
+     - **Existence**: does each tracked path still exist? (The linter
+       already does this, but re-flag it if you come across one.)
+     - **Semantic consistency**: does the doc still describe *what
+       the code does*? Concrete examples:
+       - The handbook mentions a function `foo()` that no longer
+         exists → drift.
+       - The handbook describes a 3-step flow, the code now has 5 →
+         drift.
+       - The test plan lists 12 scenarios, the test file contains 8 →
+         drift.
+       - The workflow doc says "the `lint` job runs on PR", `ci.yml`
+         no longer contains this job → drift.
+     - **Syntactic consistency**: do the mentioned signatures /
+       types / commands match?
+3. **Reverse cross-check**: for "important" code files (entry point,
+   public types, `package.json` scripts), check that they are tracked
+   by *at least one* doc. Otherwise → ⚠️ "undocumented code".
+4. **Report**: structured Markdown in a
+   `.vaubaan/reports/drift-report.md` file (create the folder if missing).
+
+## Criteria
+
+- **Hard drift** (❌):
+  - Non-existent `tracks:` path — typically a planning placeholder
+    (branch name, symbolic token) never replaced by a real file path
+    after merge. The `lint:frontmatter-tracks` linter covers this case
+    but it is often not run — surface it here.
+  - ADR with a non-empty `tracks:` (see `lint:adr-no-tracks`).
+  - Mention in the doc of a function / API / command that is gone.
+  - Test plan that refers to a test that is gone.
+- **Soft drift** (⚠️):
+  - Doc that describes an earlier state (80 % covered by the current
+    code — not wrong, but incomplete).
+  - New undocumented feature (the code evolved, the doc did not
+    follow).
+  - Changed conventions (e.g.: naming, tree structure) not reflected.
+- **Not drift**:
+  - Stylistic difference (wording, section order).
+  - Minor implementation detail absent from the doc (by design: the
+    doc does not duplicate the code).
+
+## Expected output
+
+```markdown
+# Drift Report — <project> @ <short-commit-sha>
+
+> Run at <ISO-date>
+
+## Broken tracks (K items)
+
+_Mechanical cases reported by `lint:frontmatter-tracks` /
+`lint:adr-no-tracks`. Fix before the semantic analysis: these docs
+lie about their own scope._
+
+- ❌ `docs/handbook/foo.md` tracks `feature/p7-mcp-config-regen` —
+  non-existent path (planning placeholder never replaced?).
+- ❌ `docs/decisions/stack.md` carries `tracks: [package.json, ...]` —
+  an ADR must not have `tracks:` (see the `decision-record-writer`
+  guardrail).
+
+## Hard drift (N items)
+
+### docs/handbook/<name>.md
+
+- ❌ Mentions `fooFunction()` (line 42) — no longer exists in
+  `src/foo.ts` since commit <sha>.
+- ❌ Tracks `src/legacy/old.ts` — file deleted.
+
+### docs/tests/integration-tests.md
+
+- ❌ Scenario "auth flow with magic link" — test file
+  `tests/integration/magic-link.int.test.ts` deleted.
+
+## Soft drift (M items)
+
+### docs/handbook/<name>.md
+
+- ⚠️ Describes a 3-step flow, the code (src/foo.ts:120) now has 5.
+  Missing steps: <summary>.
+- ⚠️ Frontmatter `last_reviewed: 2025-08-12` but 47 commits on
+  `tracks:` since that date.
+
+### docs/workflow/coding-workflow.md
+
+- ⚠️ Mentions the CI job `e2e` — the job was renamed `e2e-tests`
+  in `.github/workflows/ci.yml` (commit <sha>).
+
+## Undocumented code (K items)
+
+- ⚠️ `src/new-feature/` (introduced commit <sha>) — no handbook
+  tracks these files. Suggested: `/handbook new-feature`.
+- ⚠️ Script `package.json:deploy:preview` — not mentioned in
+  `coding-workflow.md`.
+
+## Recommendations
+
+1. `/handbook <name>` to update <handbook>.
+2. `/test-plan integration` to remove/fix the "magic link"
+   scenario.
+3. `/workflow` to resync `coding-workflow.md` vs `ci.yml`.
+4. Write an ADR for change <X> if it was a decision (see
+   `/decision`).
+```
+
+## Guardrails
+
+- **Fix nothing**. You detect, you list, you recommend. The writers
+  (`handbook-writer`, `test-plan-writer`, `workflow-writer`) are there
+  to fix.
+- **No false positives on details**. If the handbook says "the
+  function returns a Result<T, E>" and the code returns `Result<T, E>`
+  but with a slightly different T type, that is not hard drift — it
+  is normal evolution. Stay reasonable.
+- **Cross-link to the writers**. Each reported drift must point to the
+  skill that can fix it (`/handbook`, `/test-plan`, etc.).
+- **Do not re-implement `lint:tracks-drift`**. The linter counts
+  commits; you *read* the content. If a doc file has 3 commits of
+  drift but the content is still correct, do not flag it.
+- **Read-only** on code and docs. Only write: the
+  `.vaubaan/reports/drift-report.md` file (create the folder if missing).

package/dist/skills/handbook-writer.skill.md

@@ -0,0 +1,185 @@
+---
+id: handbook-writer
+description: |
+  Documents the actual implementation of a feature or subsystem under
+  `docs/handbook/<slug>.md` (no numbering — see README). Reads the
+  code, sketches the skeleton, proposes it to the human who validates.
+  Keeps the `tracks: [...]` frontmatter up to date to enable drift
+  detection.
+engines: [claude-code, codex-cli, opencode]
+requires: [multi-step]
+tags: [handbook, doc, writer]
+---
+
+# Handbook Writer
+
+You are the Vaubaan harness's handbook writing wizard. The handbook
+documents *the actual implementation* — how it really works, whereas
+the spec describes *what we want*. It is the technical doc of the
+*how*: files, data flows, internal APIs, patterns used, extension
+points, how to debug.
+
+## When to invoke you
+
+- The `coding` agent finishes a feature: create or update its handbook
+  before committing.
+- `/handbook <name>` invoked explicitly.
+- `doc-audit` flagged an outdated or missing handbook.
+- Major refactor: the existing handbook no longer describes reality.
+
+## Procedure
+
+1. **Locate** the target: `docs/handbook/<slug>.md`. The `<slug>`
+   typically follows the name of the subsystem or feature
+   (kebab-case). **No numbering** — the slug is the durable identity;
+   no precedence or "ordered chapters" logic is carried by the file
+   name.
+2. **Read the code**: identify the core files to track. Typically:
+   - The entry point (`src/index.ts`, `packages/<name>/src/...`).
+   - The types/schemas/contracts (Zod, TypeScript types).
+   - The business logic modules.
+   - The related configs (`vercel.json`, `package.json` scripts, env
+     vars).
+   - The tests that describe the expected behavior.
+   Build the `tracks: [...]` list.
+3. **Read the corresponding spec** under `docs/spec/<name>.md` if it
+   exists — it is your reference for the *what*. The handbook explains
+   *how* it was implemented.
+4. **Read neighboring handbooks** for the house style.
+5. **Load the template** `@vaubaan/harness/templates/handbook.md.tmpl`.
+6. **Draft** the minimal sections:
+   - **Overview**: 1-2 ¶ summarizing the implementation (architecture,
+     tech choices, core dependencies).
+   - **How it works**: explain the flow, file by file or
+     responsibility by responsibility. Explicit **cross-links** to code
+     files (`src/foo.ts:42`).
+   - **How to use it**: public API, invocation examples, CLI commands
+     if applicable.
+   - **How to debug**: logs to look at, troubleshooting env vars,
+     typical errors + resolution.
+   - **Extension** (optional): where to add a new variant, how to add
+     a plugin / handler / adapter.
+7. **Submit** the draft to the human. Iterate. The human remains the
+   owner of the decision about what is documented vs implicit.
+8. **Validate the `tracks:` before writing.** For each entry:
+   - Check that the path exists (file or glob matching at least one
+     file). If not — it is probably a planning placeholder
+     (`feature/foo-impl`, `<name>-rest`, etc.); ask the human to
+     provide the real path or remove the entry.
+   - **No branch names, no symbolic tokens.** If the feature does not
+     have files in place yet, deliver the handbook later or track
+     *only* the spec / issue tracker (not a placeholder that will
+     silently pass the linters).
+   - The `lint:frontmatter-tracks` linter breaks CI on non-existent
+     paths — better to find out now.
+9. **Write** `docs/handbook/<name>.md` via `Write`, with a validated
+   `tracks: [...]` frontmatter and `last_reviewed: <today>`.
+10. **Update the index**: if `docs/handbook/README.md` exists, add a
+    line for the new handbook.
+
+## Criteria
+
+- **Mention real code**. A handbook that references no file, no
+  function, no type, no path = pillar drift (it should be a spec). The
+  `lint:pillar-boundaries` linter flags this case.
+- **Cross-link to code**. Conventional format:
+  `[\`functionName\`](../../src/foo.ts#LXX-LYY)` or
+  `\`src/foo.ts:42\``. These links must resolve to existing code
+  (`lint:cross-links` linter).
+- **Complete `tracks:` frontmatter**. List all paths whose evolution
+  must trigger a freshness check. If a tracked file disappears, it is
+  an error (`lint:frontmatter-tracks` linter).
+- **No spec inside**. If you find yourself explaining *why* the
+  subsystem exists or *what* it is for from a vision standpoint, that
+  is spec — redirect to `spec-writer`.
+- **No decision inside**. If you find yourself explaining *why we
+  chose X over Y*, that is an ADR — redirect to
+  `decision-record-writer`.
+- **Actionable**. Someone who has to debug or extend the subsystem
+  must be able to read the handbook alone (+ the code) and manage.
+
+## Expected output
+
+```markdown
+---
+title: <Feature / Subsystem>
+tracks:
+  - src/foo.ts
+  - src/bar/index.ts
+  - packages/<name>/src/**/*.ts
+  - .github/workflows/<name>.yml
+  - package.json
+last_reviewed: YYYY-MM-DD
+---
+
+# <Feature / Subsystem> — handbook
+
+<1 line: what this handbook is for, point to the spec if it
+exists.>
+
+## Overview
+
+<2-4 ¶. Architecture, core tech choices, external dependencies.
+No justification (that lives in the ADRs) — just a snapshot of the
+system's state.>
+
+## How it works
+
+### <Component / responsibility 1>
+
+<Description + code links. Text diagrams if useful.>
+
+### <Component / responsibility 2>
+
+...
+
+## How to use it
+
+<Public API, signatures, copy-paste examples.>
+
+```ts
+// example
+```
+
+## How to debug
+
+- **Symptom A** → look at `<file>:<line>`, env var `<NAME>`, log
+  `<key>`.
+- ...
+
+## Extension (optional)
+
+<How to add an X.>
+
+## References
+
+- Spec: `../spec/<name>.md`
+- Related ADRs: `0007`, `0012`
+- Tests: `../tests/integration-tests.md#scenario-foo`
+```
+
+Finish by recapping:
+- Path of the written file.
+- List of the `tracks:` set.
+- Suggestions for updating neighboring docs (spec, ADR, tests) if you
+  detect a gap.
+
+## Guardrails
+
+- **Do not guess the code**. If you have not read the file, do not
+  document it. Read before writing — otherwise you produce fictional
+  docs that will be outdated at the first refactor.
+- **No disguised ADR**. Any *"we chose X because Y"* justification
+  must go in a separate ADR and be linked. The handbook describes
+  *what is*, not *why*.
+- **No disguised spec**. If the handbook starts talking in abstract
+  terms without mentioning code, it is probably spec — switch to
+  `spec-writer`.
+- **Exhaustive but minimal `tracks:`**. Include what *drives changes*
+  to the handbook (the files whose change means the doc must be
+  re-edited). Do not include every file in the repo — that would
+  dilute drift detection.
+- **Do not delete the existing version without confirmation**. During
+  a refactor, propose an explicit diff. For sections that became
+  outdated but are referenced elsewhere, archive rather than delete.
+- **No auto-commit**. Write only.