@vaubaan/harness 2.0.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/README.md +25 -21
  2. package/dist/cli/index.js +543 -76
  3. package/dist/cli/index.js.map +1 -1
  4. package/dist/commands/doc-audit.cmd.md +1 -1
  5. package/dist/commands/handbook.cmd.md +4 -3
  6. package/dist/commands/journey.cmd.md +22 -0
  7. package/dist/commands/story.cmd.md +24 -0
  8. package/dist/commands/test-plan.cmd.md +4 -4
  9. package/dist/index.d.ts +2 -2
  10. package/dist/index.js +304 -56
  11. package/dist/index.js.map +1 -1
  12. package/dist/init.d.ts +2 -3
  13. package/dist/init.js +301 -53
  14. package/dist/init.js.map +1 -1
  15. package/dist/linters/index.js +523 -56
  16. package/dist/linters/index.js.map +1 -1
  17. package/dist/parser/index.d.ts +110 -1
  18. package/dist/parser/index.js +229 -2
  19. package/dist/parser/index.js.map +1 -1
  20. package/dist/{render-C-FWmUfX.d.ts → render-BzrBb_l4.d.ts} +3 -1
  21. package/dist/render.d.ts +1 -1
  22. package/dist/render.js +89 -10
  23. package/dist/render.js.map +1 -1
  24. package/dist/skills/decision-record-writer.skill.md +93 -130
  25. package/dist/skills/doc-audit.skill.md +37 -7
  26. package/dist/skills/drift-detector.skill.md +41 -11
  27. package/dist/skills/handbook-writer.skill.md +71 -159
  28. package/dist/skills/journey-writer.skill.md +159 -0
  29. package/dist/skills/spec-writer.skill.md +25 -3
  30. package/dist/skills/test-plan-writer.skill.md +46 -53
  31. package/dist/skills/workflow-writer.skill.md +20 -3
  32. package/dist/templates/decision.md.tmpl +20 -47
  33. package/dist/templates/e2e-tests.md.tmpl +16 -45
  34. package/dist/templates/handbook.md.tmpl +20 -38
  35. package/dist/templates/integration-tests.md.tmpl +16 -34
  36. package/dist/templates/journey.md.tmpl +45 -0
  37. package/package.json +1 -1
@@ -37,7 +37,9 @@ the doc content still matches reality.
37
37
  move on to the semantic analysis.
38
38
  1. **Inventory of targets**: all files under `docs/handbook/`,
39
39
  `docs/tests/`, `docs/workflow/` that declare a non-empty
40
- `tracks: [...]` in their frontmatter.
40
+ `tracks: [...]` in their frontmatter, and the files under
41
+ `docs/journeys/` whose nodes declare `anchors:` (`README.md` there is
42
+ generated: skip it).
41
43
  - **Explicit skip**: `docs/decisions/` is *never* scanned. ADRs
42
44
  document decisions frozen in time — their drift is semantically
43
45
  different (is the decision still valid?), not a question of doc
@@ -59,15 +61,25 @@ the doc content still matches reality.
59
61
  exists → drift.
60
62
  - The handbook describes a 3-step flow, the code now has 5 →
61
63
  drift.
62
- - The test plan lists 12 scenarios, the test file contains 8 →
63
- drift.
64
+ - The test plan describes a fixture / setup that no longer
65
+ exists in the test infrastructure → drift.
64
66
  - The workflow doc says "the `lint` job runs on PR", `ci.yml`
65
67
  no longer contains this job → drift.
68
+ - A journey leaf anchors a file that no longer exists, or
69
+ `requires:` an entity the spec vocabulary no longer defines →
70
+ hard drift.
71
+ - A journey leaf whose anchored code gained a branch (a new
72
+ guard, a new step the user sees) with no node for it → soft
73
+ drift; a `proposed` leaf whose code already exists → soft
74
+ drift, suggest passing it `implemented`.
66
75
  - **Syntactic consistency**: do the mentioned signatures /
67
76
  types / commands match?
68
77
  3. **Reverse cross-check**: for "important" code files (entry point,
69
78
  public types, `package.json` scripts), check that they are tracked
70
- by *at least one* doc. Otherwise → ⚠️ "undocumented code".
79
+ by *at least one* doc (`tracks:`) or anchored by *at least one*
80
+ journey leaf (`anchors:`). Otherwise → ⚠️ "undocumented code". This
81
+ is where unanchored entry points are reported: with judgment, no
82
+ configuration.
71
83
  4. **Report**: structured Markdown in a
72
84
  `.vaubaan/reports/drift-report.md` file (create the folder if missing).
73
85
 
@@ -81,12 +93,15 @@ the doc content still matches reality.
81
93
  - ADR with a non-empty `tracks:` (see `lint:adr-no-tracks`).
82
94
  - Mention in the doc of a function / API / command that is gone.
83
95
  - Test plan that refers to a test that is gone.
96
+ - Journey anchor to a deleted file; entity removed from the spec
97
+ vocabulary.
84
98
  - **Soft drift** (⚠️):
85
99
  - Doc that describes an earlier state (80 % covered by the current
86
100
  code — not wrong, but incomplete).
87
101
  - New undocumented feature (the code evolved, the doc did not
88
102
  follow).
89
103
  - Changed conventions (e.g.: naming, tree structure) not reflected.
104
+ - Code branch without a journey node; `proposed` leaf already coded.
90
105
  - **Not drift**:
91
106
  - Stylistic difference (wording, section order).
92
107
  - Minor implementation detail absent from the doc (by design: the
@@ -121,8 +136,14 @@ lie about their own scope._
121
136
 
122
137
  ### docs/tests/integration-tests.md
123
138
 
124
- - ❌ Scenario "auth flow with magic link" — test file
125
- `tests/integration/magic-link.int.test.ts` deleted.
139
+ - ❌ Describes a `resetDb()` fixture — `tests/fixtures/db.ts`
140
+ deleted.
141
+
142
+ ### docs/journeys/<slug>.md
143
+
144
+ - ❌ Leaf "<title>" anchors `src/legacy/old.ts` — file deleted.
145
+ - ❌ Leaf "<title>" requires `<entity>` — no longer in the Vocabulary
146
+ of `docs/spec/<subsystem>.md`.
126
147
 
127
148
  ## Soft drift (M items)
128
149
 
@@ -138,28 +159,37 @@ lie about their own scope._
138
159
  - ⚠️ Mentions the CI job `e2e` — the job was renamed `e2e-tests`
139
160
  in `.github/workflows/ci.yml` (commit <sha>).
140
161
 
162
+ ### docs/journeys/<slug>.md
163
+
164
+ - ⚠️ Leaf "<title>": its anchored `src/foo.ts:88` gained a guard the
165
+ user sees, no node for it.
166
+ - ⚠️ Leaf "<title>" is `proposed` but `src/bar.ts` already realizes it
167
+ — pass it `implemented`.
168
+
141
169
  ## Undocumented code (K items)
142
170
 
143
171
  - ⚠️ `src/new-feature/` (introduced commit <sha>) — no handbook
144
- tracks these files. Suggested: `/handbook new-feature`.
172
+ tracks these files and no journey leaf anchors them. Suggested:
173
+ `/handbook new-feature` for the how, `/journey <slug>` for the user
174
+ activity.
145
175
  - ⚠️ Script `package.json:deploy:preview` — not mentioned in
146
176
  `coding-workflow.md`.
147
177
 
148
178
  ## Recommendations
149
179
 
150
180
  1. `/handbook <name>` to update <handbook>.
151
- 2. `/test-plan integration` to remove/fix the "magic link"
152
- scenario.
181
+ 2. `/test-plan integration` to fix the fixture description.
153
182
  3. `/workflow` to resync `coding-workflow.md` vs `ci.yml`.
154
183
  4. Write an ADR for change <X> if it was a decision (see
155
184
  `/decision`).
185
+ 5. `/journey <slug>` to add the missing node or re-anchor the leaf.
156
186
  ```
157
187
 
158
188
  ## Guardrails
159
189
 
160
190
  - **Fix nothing**. You detect, you list, you recommend. The writers
161
- (`handbook-writer`, `test-plan-writer`, `workflow-writer`) are there
162
- to fix.
191
+ (`handbook-writer`, `test-plan-writer`, `workflow-writer`,
192
+ `journey-writer` via `/journey`) are there to fix.
163
193
  - **No false positives on details**. If the handbook says "the
164
194
  function returns a Result<T, E>" and the code returns `Result<T, E>`
165
195
  but with a slightly different T type, that is not hard drift — it
@@ -1,11 +1,10 @@
1
1
  ---
2
2
  id: handbook-writer
3
3
  description: |
4
- Documents the actual implementation of a feature or subsystem under
5
- `docs/handbook/<slug>.md` (no numbering — see README). Reads the
6
- code, sketches the skeleton, proposes it to the human who validates.
7
- Keeps the `tracks: [...]` frontmatter up to date to enable drift
8
- detection.
4
+ Writes or updates `docs/handbook/<slug>.md`: only what an agent cannot
5
+ read quickly in the code (entry points, cross-file invariants, traps,
6
+ config living outside the repo, manual procedures). Never a paraphrase of
7
+ the code. Keeps the `tracks: [...]` frontmatter valid for drift detection.
9
8
  engines: [claude-code, codex-cli, opencode]
10
9
  requires: [multi-step]
11
10
  tags: [handbook, doc, writer]
@@ -13,173 +12,86 @@ tags: [handbook, doc, writer]
13
12
 
14
13
  # Handbook Writer
15
14
 
16
- You are the Vaubaan harness's handbook writing wizard. The handbook
17
- documents *the actual implementation* — how it really works, whereas
18
- the spec describes *what we want*. It is the technical doc of the
19
- *how*: files, data flows, internal APIs, patterns used, extension
20
- points, how to debug.
21
-
22
- ## When to invoke you
23
-
24
- - A feature is finished: create or update its handbook before
25
- committing.
26
- - `/handbook <name>` invoked explicitly.
27
- - `doc-audit` flagged an outdated or missing handbook.
28
- - Major refactor: the existing handbook no longer describes reality.
29
-
30
- ## Procedure
31
-
32
- 1. **Locate** the target: `docs/handbook/<slug>.md`. The `<slug>`
33
- typically follows the name of the subsystem or feature
34
- (kebab-case). **No numbering** — the slug is the durable identity;
35
- no precedence or "ordered chapters" logic is carried by the file
36
- name.
37
- 2. **Read the code**: identify the core files to track. Typically:
38
- - The entry point (`src/index.ts`, `packages/<name>/src/...`).
39
- - The types/schemas/contracts (Zod, TypeScript types).
40
- - The business logic modules.
41
- - The related configs (`vercel.json`, `package.json` scripts, env
42
- vars).
43
- - The tests that describe the expected behavior.
44
- Build the `tracks: [...]` list.
45
- 3. **Read the corresponding spec** under `docs/spec/<name>.md` if it
46
- exists — it is your reference for the *what*. The handbook explains
47
- *how* it was implemented.
48
- 4. **Read neighboring handbooks** for the house style.
49
- 5. **Load the template** `@vaubaan/harness/templates/handbook.md.tmpl`.
50
- 6. **Draft** the minimal sections:
51
- - **Overview**: 1-2 summarizing the implementation (architecture,
52
- tech choices, core dependencies).
53
- - **How it works**: explain the flow, file by file or
54
- responsibility by responsibility. Explicit **cross-links** to code
55
- files (`src/foo.ts:42`).
56
- - **How to use it**: public API, invocation examples, CLI commands
57
- if applicable.
58
- - **How to debug**: logs to look at, troubleshooting env vars,
59
- typical errors + resolution.
60
- - **Extension** (optional): where to add a new variant, how to add
61
- a plugin / handler / adapter.
62
- 7. **Submit** the draft to the human. Iterate. The human remains the
63
- owner of the decision about what is documented vs implicit.
64
- 8. **Validate the `tracks:` before writing.** For each entry:
65
- - Check that the path exists (file or glob matching at least one
66
- file). If not — it is probably a planning placeholder
67
- (`feature/foo-impl`, `<name>-rest`, etc.); ask the human to
68
- provide the real path or remove the entry.
69
- - **No branch names, no symbolic tokens.** If the feature does not
70
- have files in place yet, deliver the handbook later or track
71
- *only* the spec / issue tracker (not a placeholder that will
72
- silently pass the linters).
73
- - The `lint:frontmatter-tracks` linter breaks CI on non-existent
74
- paths — better to find out now.
75
- 9. **Write** `docs/handbook/<name>.md` via `Write`, with a validated
76
- `tracks: [...]` frontmatter and `last_reviewed: <today>`.
77
- 10. **Update the index**: if `docs/handbook/README.md` exists, add a
78
- line for the new handbook.
79
-
80
- ## Criteria
81
-
82
- - **Mention real code**. A handbook that references no file, no
83
- function, no type, no path = pillar drift (it should be a spec). The
84
- `lint:pillar-boundaries` linter flags this case.
85
- - **Cross-link to code**. Conventional format:
86
- `[\`functionName\`](../../src/foo.ts#LXX-LYY)` or
87
- `\`src/foo.ts:42\``. These links must resolve to existing code
88
- (`lint:cross-links` linter).
89
- - **Complete `tracks:` frontmatter**. List all paths whose evolution
90
- must trigger a freshness check. If a tracked file disappears, it is
91
- an error (`lint:frontmatter-tracks` linter).
92
- - **No spec inside**. If you find yourself explaining *why* the
93
- subsystem exists or *what* it is for from a vision standpoint, that
94
- is spec — redirect to `spec-writer`.
95
- - **No decision inside**. If you find yourself explaining *why we
96
- chose X over Y*, that is an ADR — redirect to
97
- `decision-record-writer`.
98
- - **Actionable**. Someone who has to debug or extend the subsystem
99
- must be able to read the handbook alone (+ the code) and manage.
100
-
101
- ## Expected output
15
+ A handbook is read by an agent about to work on a feature. Its job is to
16
+ save that agent time and mistakes, at the smallest size that still does.
17
+ The code is the source of truth for what the code does: the handbook never
18
+ restates it.
19
+
20
+ ## Content test
21
+
22
+ Keep a sentence only if **reading the code would not give it quickly**:
23
+
24
+ - **Entry points**: the 2-5 files to open first, one line each.
25
+ - **Cross-file invariants**: a rule that holds across several files and
26
+ that no single file states (e.g. "only this file imports the vendor SDK").
27
+ - **Traps and non-obvious behaviour**: why the code does something that
28
+ looks wrong or unusual, when the next reader would "fix" it.
29
+ - **What lives outside the repo**: settings in a dashboard, an external
30
+ registration, secrets, integrations, and how to mirror them.
31
+ - **Manual procedures**: checklists, rotations, steps nobody can automate.
32
+ - **Debug**: symptom → cause, when the cause is not visible from the
33
+ symptom.
34
+
35
+ ## Never in a handbook
36
+
37
+ - File-by-file or function-by-function descriptions, route tables,
38
+ component lists, model fields, algorithm steps: read the code and tests.
39
+ - Usage examples of an API whose signature is in the code.
40
+ - Product rules (→ spec), structural choices (→ ADR), test strategy
41
+ (→ `docs/tests/`), CI (→ `docs/workflow/`).
42
+ - Anything an agent would learn by opening the first entry point.
43
+
44
+ ## Format
45
+
46
+ - **Target 30-60 lines**, 80 at most. Bullets, no prose paragraphs.
47
+ - Sections are optional; use only those with content, in this order:
48
+ `Start here`, `Invariants`, `Traps`, `Outside the repo`, `Procedures`,
49
+ `Debug`.
50
+ - Link code files rather than describing them. Links must resolve
51
+ (`lint:cross-links`).
52
+ - First line after the title: one sentence on the scope, and a link to the
53
+ spec if it exists.
54
+ - When a journey leaf anchors the feature (`docs/journeys/`), link it
55
+ too: the journey says what the user does and where, the handbook says
56
+ how. Never restate the journey.
102
57
 
103
58
  ```markdown
104
59
  ---
105
- title: <Feature / Subsystem>
60
+ title: <Feature>
106
61
  tracks:
107
- - src/foo.ts
108
- - src/bar/index.ts
109
- - packages/<name>/src/**/*.ts
110
- - .github/workflows/<name>.yml
111
- - package.json
62
+ - <paths whose change can make this handbook wrong>
112
63
  last_reviewed: YYYY-MM-DD
113
64
  ---
114
65
 
115
- # <Feature / Subsystem> — handbook
116
-
117
- <1 line: what this handbook is for, point to the spec if it
118
- exists.>
119
-
120
- ## Overview
121
-
122
- <2-4 ¶. Architecture, core tech choices, external dependencies.
123
- No justification (that lives in the ADRs) — just a snapshot of the
124
- system's state.>
125
-
126
- ## How it works
127
-
128
- ### <Component / responsibility 1>
66
+ # <Feature> — handbook
129
67
 
130
- <Description + code links. Text diagrams if useful.>
68
+ <One sentence. Spec: [..](../spec/..).>
131
69
 
132
- ### <Component / responsibility 2>
70
+ ## Start here
71
+ - [`file`](../../path) — <what it is the entry to>
133
72
 
134
- ...
135
-
136
- ## How to use it
137
-
138
- <Public API, signatures, copy-paste examples.>
139
-
140
- ```ts
141
- // example
73
+ ## Traps
74
+ - <non-obvious behaviour and why>
142
75
  ```
143
76
 
144
- ## How to debug
145
-
146
- - **Symptom A** → look at `<file>:<line>`, env var `<NAME>`, log
147
- `<key>`.
148
- - ...
149
-
150
- ## Extension (optional)
151
-
152
- <How to add an X.>
153
-
154
- ## References
155
-
156
- - Spec: `../spec/<name>.md`
157
- - Related ADRs: `0007`, `0012`
158
- - Tests: `../tests/integration-tests.md#scenario-foo`
159
- ```
77
+ ## Procedure
160
78
 
161
- Finish by recapping:
162
- - Path of the written file.
163
- - List of the `tracks:` set.
164
- - Suggestions for updating neighboring docs (spec, ADR, tests) if you
165
- detect a gap.
79
+ 1. Read the spec and the code of the feature. Never document a file you
80
+ have not read.
81
+ 2. For each candidate sentence, apply the content test. If an agent would
82
+ learn it by opening the file, drop it.
83
+ 3. When updating, also delete what has become readable in the code or no
84
+ longer true.
85
+ 4. Set `tracks:` to the files whose change can invalidate what the
86
+ handbook says (existing paths or globs only, no placeholders), and
87
+ `last_reviewed` to today.
88
+ 5. Submit the draft, iterate, write the file. Do not commit.
166
89
 
167
90
  ## Guardrails
168
91
 
169
- - **Do not guess the code**. If you have not read the file, do not
170
- document it. Read before writing — otherwise you produce fictional
171
- docs that will be outdated at the first refactor.
172
- - **No disguised ADR**. Any *"we chose X because Y"* justification
173
- must go in a separate ADR and be linked. The handbook describes
174
- *what is*, not *why*.
175
- - **No disguised spec**. If the handbook starts talking in abstract
176
- terms without mentioning code, it is probably spec — switch to
177
- `spec-writer`.
178
- - **Exhaustive but minimal `tracks:`**. Include what *drives changes*
179
- to the handbook (the files whose change means the doc must be
180
- re-edited). Do not include every file in the repo — that would
181
- dilute drift detection.
182
- - **Do not delete the existing version without confirmation**. During
183
- a refactor, propose an explicit diff. For sections that became
184
- outdated but are referenced elsewhere, archive rather than delete.
185
- - **No auto-commit**. Write only.
92
+ - **Smaller is better.** When in doubt, leave it out: a stale line costs
93
+ more than a missing one, because the code answers the missing one.
94
+ - **No disguised ADR or spec.** A one-line *why* next to a trap is fine; a
95
+ debate between options is an ADR.
96
+ - **Do not guess.** Every statement is checked against the code or the
97
+ external system it describes.
@@ -0,0 +1,159 @@
1
+ ---
2
+ id: journey-writer
3
+ description: |
4
+ Writes or updates `docs/journeys/<slug>.md`: the user intentions of
5
+ the project at every scale, anchored to the code. One node at a time.
6
+ Greenfield: three questions. Mature: reads the code's entry points and
7
+ proposes anchored leaves. `/story <intent>` adds a `proposed` leaf
8
+ with its acceptance criteria before any code is written.
9
+ engines: [claude-code, codex-cli, opencode]
10
+ requires: [multi-step]
11
+ tags: [journeys, doc, writer]
12
+ ---
13
+
14
+ # Journey Writer
15
+
16
+ You are the Vaubaan harness's journey wizard. A journey says what the
17
+ user does and wants, from a level-1 intention down to the atomic activity
18
+ a piece of code realizes, and where that code is. It is the entry point
19
+ to a feature: a new behavior is a `proposed` leaf here before it is a
20
+ line of code. Contract: spec §9.1.3 of the harness; the rule of a leaf
21
+ lives in `docs/spec/`, the how in `docs/handbook/`, never here.
22
+
23
+ ## Content test
24
+
25
+ A journey holds only what neither the code nor another pillar says:
26
+
27
+ - **Keep**: the intention (verb + object) at each level, the actors, what
28
+ a leaf needs and produces (`requires:` / `creates:`), where it is
29
+ realized (`anchors:`), what "done" means for a `proposed` leaf
30
+ (`acceptance:`), the spec section that holds the rule (`spec:`).
31
+ - **Drop**: business rules (→ spec), how the code works (→ handbook),
32
+ anything derivable from the code (which components a leaf uses, which
33
+ roles guard it, how deep it is), prose on a leaf (its title and fields
34
+ suffice), a node for every function (a leaf is a user activity, not a
35
+ code unit).
36
+
37
+ Targets: 2 to 9 children per node, 40 to 120 lines per file. Beyond,
38
+ split into two level-1 journeys; never nest a journey in another with a
39
+ `parent:` field, the format has none.
40
+
41
+ ## When to invoke you
42
+
43
+ - `/story <intent>`: a visible change of behavior is about to be built.
44
+ This is the doc-first rule of `AGENTS.md`; nothing is coded before the
45
+ leaf exists.
46
+ - `/journey [name]`: a new journey, or a node to add to an existing one.
47
+ - `doc-audit` reports a spec without journey, or a pending increment.
48
+ - A pull request delivers a `proposed` leaf: pass it `implemented`.
49
+
50
+ ## Format
51
+
52
+ ```markdown
53
+ ---
54
+ title: <Verb + object>
55
+ status: proposed | implemented | deprecated
56
+ actors: [<role>, <role>]
57
+ spec: ../spec/<subsystem>.md
58
+ last_reviewed: YYYY-MM-DD
59
+ ---
60
+
61
+ # <Verb + object>
62
+
63
+ As a <actor>, I want <intention> so that <outcome>.
64
+
65
+ ## <Verb + object> ← internal node: may carry one sentence
66
+
67
+ ### <Verb + object> ← leaf: fields, no prose
68
+
69
+ requires: <entity>, <entity>
70
+ creates: <entity>
71
+ anchors: <path or glob>, <path or glob>
72
+ spec: ../spec/<subsystem>.md#<section>
73
+
74
+ ### <Verb + object>
75
+
76
+ status: proposed
77
+ requires: <entity>
78
+ acceptance:
79
+ - <observable criterion>
80
+ ```
81
+
82
+ Rules the linters enforce (`lint:journey-*`), so apply them as you write:
83
+
84
+ - A leaf is a heading with no sub-heading. Fields sit on the lines right
85
+ under it, one per line, values comma-separated. Leaf fields on an
86
+ internal node, or an unknown field, fail the lint.
87
+ - An `implemented` leaf has `anchors:` that exist; a `proposed` leaf has
88
+ at least one `acceptance:` item.
89
+ - An entity is the kebab-case slug of a bold term opening a bullet in the
90
+ Vocabulary section of a linked spec (`**Generated file**` →
91
+ `generated-file`). Singular, no synonym. A missing word goes into the
92
+ spec first (`/spec`), never into the journey as an invention.
93
+ - `spec:` paths resolve. `docs/journeys/README.md` is generated: never
94
+ edit it; after any change run `npx @vaubaan/harness update .`.
95
+
96
+ ## Procedure
97
+
98
+ 1. **Locate.** `/story <intent>` or `/journey <name>`: find the journey
99
+ the intent belongs to by reading `docs/journeys/README.md` (the
100
+ generated index) and the journey titles. No journey fits → a new
101
+ level-1 file, slug from the verb + object. Ask when two fit.
102
+ 2. **Detect the mode** on the scope of the node:
103
+ - **Greenfield**: no code and no handbook cover it. Ask three
104
+ questions, one at a time: who does it (actor), what they want and
105
+ why (the user story), what it does not cover. Write the file with
106
+ its first `proposed` leaf and stop. The rest comes one node at a
107
+ time, as the project learns.
108
+ - **Mature**: code exists. Do not question the human from a blank
109
+ page. Read the entry points of the code (routes, commands,
110
+ handlers, mutations), the spec and the handbooks. Propose a
111
+ hierarchy top-down from the navigation or the CLI, and a leaf at a
112
+ time with its anchors, `requires:` / `creates:` from the spec
113
+ vocabulary, and the spec section. The human corrects instead of
114
+ answering. One sub-domain first, to stabilize the vocabulary, then
115
+ extend. A code-graph tool (an MCP server the project configured)
116
+ helps if present; read the code if not. The harness installs none.
117
+ 3. **`/story <intent>`** (the typed transaction): write the leaf as
118
+ `proposed`, at the right place in the tree, with 2 to 5 observable
119
+ acceptance criteria and its `requires:` / `creates:`. **Refuse** to
120
+ write an entity that is in no linked spec's Vocabulary: stop and
121
+ redirect to `/spec` so the word is defined first. No `anchors:` yet.
122
+ 4. **Deliver** (`proposed` → `implemented`, in the pull request that
123
+ ships the code): add `anchors:` to the code and the tests, write
124
+ tests whose titles restate the acceptance criteria, remove
125
+ `acceptance:`, set `last_reviewed`. A delivered leaf changes only in
126
+ the PR that delivers the change: a later change of behavior is a
127
+ sibling `proposed` leaf, merged into the leaf when delivered.
128
+ 5. **Withdraw** (`implemented` → `deprecated`): set the status, keep the
129
+ node one release, delete it at the next one. Never back to
130
+ `proposed`.
131
+ 6. **Check**: run `npx @vaubaan/harness lint --pillar journeys`, then
132
+ `npx @vaubaan/harness update .` so the index follows. Submit the
133
+ draft, iterate, write. Do not commit.
134
+
135
+ ## Criteria
136
+
137
+ - **Verb + object** at every level; a category ("Settings", "Admin") is
138
+ not an intention.
139
+ - **A leaf is a user activity** that one handler, route, command or
140
+ mutation realizes. A step the user does not perceive is not a leaf.
141
+ - **The tree reads top-down**: an agent that opens the journey learns in
142
+ one screen what the user does and where to look.
143
+ - **Entities are the spec's words**, in the spec's language.
144
+ - **Acceptance criteria are observable**: a command output, a visible
145
+ state, an exit code, never "works correctly".
146
+
147
+ ## Guardrails
148
+
149
+ - **Decide nothing on the human's behalf.** Propose, let them validate
150
+ leaf by leaf. A doubt on where a node belongs is a question, not a
151
+ guess.
152
+ - **No business rule, no implementation.** If you explain *why* a rule
153
+ holds, redirect to `/spec`; if you explain *how* the code does it,
154
+ redirect to `/handbook`. A one-line `spec:` pointer replaces both.
155
+ - **Do not invent vocabulary.** The spec defines the words; `/story`
156
+ refuses an undefined entity rather than coining one.
157
+ - **Do not commit.** Write the files only; the commit follows the
158
+ project's workflow.
159
+ - **Never edit `docs/journeys/README.md`.** It is rendered.
@@ -23,6 +23,24 @@ it starts minimal, stays `draft` while sections are missing, and grows
23
23
  one section at a time as the project learns. Do not make the human
24
24
  answer ten questions to get a first file.
25
25
 
26
+ ## Content test
27
+
28
+ A spec holds the product rules, for the team and for agents. Keep a
29
+ sentence only if it is a rule someone could disagree with or test, and
30
+ it is said nowhere else:
31
+
32
+ - **Keep**: vocabulary, behaviour the user sees, calculation and data
33
+ rules, what is out of scope that someone might expect, real open
34
+ questions.
35
+ - **Drop**: lineage and dates beyond one status line ("born from #1,
36
+ simplified on…"); a rule repeated in two sections or two specs (say
37
+ it once, where it belongs); visual details a designer would decide
38
+ (chart geometry, examples of rounding); technical choices (→ ADR) or
39
+ implementation status (→ handbook); "open questions" that only point
40
+ to a ticket's existence or to another doc.
41
+
42
+ A spec stays short: target 50-100 lines.
43
+
26
44
  ## When to invoke you
27
45
 
28
46
  - Start of a new subsystem that has no spec yet.
@@ -81,9 +99,13 @@ listing the rest is a valid spec. It passes the linters, and
81
99
  7. **Draft** the section in the style of the neighboring specs.
82
100
  8. **Submit** the draft to the human for validation. Iterate until
83
101
  green light.
84
- 9. **Write** the file via `Write`. Update `status` to `stable` only
85
- when the human says the spec describes the vision in full and the
86
- "Open questions" section is empty. **Do not commit** — it is up
102
+ 9. **Write** the file via `Write`. **Status**: `draft` while the
103
+ feature is refined or being built; `stable` once it is delivered and
104
+ the spec describes what is in production. The PR that delivers the
105
+ feature sets `stable` itself, in the same change as the handbook.
106
+ Open questions may remain in a `stable` spec: they are future
107
+ increments. A later change of the feature keeps the spec `stable`
108
+ and updates it in its own PR. **Do not commit** — it is up
87
109
  to the human or the agent to make the commit in the right
88
110
  workflow.
89
111
  10. **Cross-link**: if the spec mentions other subsystems, add