@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
package/README.md CHANGED
@@ -17,9 +17,9 @@ npx -y @vaubaan/harness init . --engines=claude-code
17
17
 
18
18
  A few Markdown files hold what the code cannot say and point to the code and configs for everything else. The harness renders them into the native layout of Claude Code, Codex or OpenCode, and lints them so context and code never drift apart.
19
19
 
20
- - **One context, every engine.** Eight skills, one per pillar plus an audit and a drift detector, each with a slash command. Written once for Claude Code, Codex and OpenCode.
20
+ - **One context, every engine.** Nine skills, one per pillar plus an audit and a drift detector, each with a slash command. Written once for Claude Code, Codex and OpenCode.
21
21
  - **Pointers that stay true.** Handbooks and test plans declare the files they describe in a `tracks:` field. When that code moves and the doc does not, the linter says so.
22
- - **Checks with zero tokens.** Fifteen mechanical linters run in CI and in your pre-commit hook. No engine hook, no injected turn, no loop. The agent sees a failed command and fixes it.
22
+ - **Checks with zero tokens.** Nineteen mechanical linters run in CI and in your pre-commit hook. No engine hook, no injected turn, no loop. The agent sees a failed command and fixes it.
23
23
 
24
24
  **Contents:**
25
25
  [The problem](#the-problem) · [A context database with pointers](#a-context-database-with-pointers) · [What it looks like](#what-it-looks-like) · [Quick start](#quick-start) ·
@@ -44,12 +44,13 @@ Each pillar stores one kind of information the code cannot carry, and links to t
44
44
  | ----------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
45
45
  | `README.md` | What this is, how to run it. | `package.json` scripts, the quick start. |
46
46
  | `docs/spec/` | What we want, for whom, what we refuse to do. Vocabulary. Tech-agnostic. | The modules and entry points that realize each requirement. A requirement with no pointer is a todo or dead. |
47
- | `docs/decisions/` | Why it is built this way, what was rejected, what changed since. | The config files and commits that embody the decision: `tsconfig.json`, `ci.yml`, a sha. |
47
+ | `docs/decisions/` | The structural choices in force: why, and what was rejected. | The config files and commits that embody the decision: `tsconfig.json`, `ci.yml`, a sha. |
48
48
  | `docs/handbook/` | The map: where to look, the invariants the code assumes, the gotchas. | The files it describes, declared in `tracks:`. A map, not a retelling. |
49
- | `docs/tests/` | Which scenarios matter, what "done" means. | The test that implements each scenario. A scenario with no test is an acceptance criterion still open. |
49
+ | `docs/tests/` | Test scope, stack, conventions, known gaps. Never the covered scenarios. | The test files: their titles say what is covered. A spec with no test is a known gap. |
50
50
  | `docs/workflow/` | What lives outside the repo: approvals, protections, secrets, languages. | `ci.yml`, build scripts, pre-commit hook. |
51
51
  | `docs/quality/` | Optional. The code rules this team holds, and the deviations it accepts. | The linter and formatter configs that enforce the mechanical part. |
52
52
  | `docs/skills/` | Optional. Domain know-how the agent should load. | Whatever the skill needs. |
53
+ | `docs/journeys/` | Optional. What the user does and wants, at every scale, anchored to the code. | Each leaf's `anchors:`; `requires:`/`creates:` name the spec vocabulary. |
53
54
 
54
55
  > [!IMPORTANT]
55
56
  > **One rule.** The only working rule the harness imposes, written into `AGENTS.md` for every engine: **understand the context, fill the gaps, code, update the context, commit.**
@@ -75,6 +76,7 @@ acme-billing/
75
76
  ├── tests/e2e-tests.md
76
77
  ├── workflow/coding-workflow.md
77
78
  ├── quality/code-quality.md # optional
79
+ ├── journeys/ # optional: send-an-invoice.md, README.md (rendered index)
78
80
  └── skills/tax-rules.skill.md # optional
79
81
  ```
80
82
 
@@ -103,7 +105,7 @@ status: draft
103
105
  - Multi-currency: not before a customer asks.
104
106
  ```
105
107
 
106
- **`docs/decisions/postgres-over-sqlite.md`**: the why, the rejected options, the history. Current state, rewritten when you change your mind, with a one-line history per reversal; git holds the rest.
108
+ **`docs/decisions/postgres-over-sqlite.md`**: one structural decision in force, about 40 lines: the why and the rejected options. When you change your mind, a new file replaces it; git holds the rest.
107
109
 
108
110
  ```markdown
109
111
  # Postgres over SQLite for the invoice store
@@ -119,11 +121,8 @@ and `src/db/client.ts`. Introduced in commit `4f1c2ab`.
119
121
  Local setup needs Docker. Migrations live in `db/migrations/`.
120
122
 
121
123
  ## Rejected alternatives
122
- | SQLite | single-writer lock under two workers |
123
-
124
- ## History
125
- - 2026-03-02 `9a0b7e1`: started on SQLite for speed of setup.
126
- - 2026-06-14 `4f1c2ab`: moved to Postgres after the first lost write.
124
+ ### SQLite
125
+ Where it started; its single-writer lock lost a write under two workers.
127
126
  ```
128
127
 
129
128
  **`docs/handbook/invoice-pipeline.md`**: the map, declared with `tracks:` so the linter notices when the code moves.
@@ -147,17 +146,18 @@ Gotcha: `void.ts` keeps the row and flips `status`; reports must filter
147
146
  on it (`src/reports/monthly.ts`).
148
147
  ```
149
148
 
150
- **`docs/tests/integration-tests.md`**: which scenarios matter, and the test that holds each one.
149
+ **`docs/tests/integration-tests.md`**: scope, stack, conventions and known gaps. The covered scenarios are the test titles, never copied here.
151
150
 
152
151
  ```markdown
153
152
  ---
154
- tracks: [tests/integration/**/*.test.ts]
153
+ tracks: [vitest.config.ts, tests/integration/fixtures/*.ts]
155
154
  ---
156
- | Scenario | Test |
157
- |---|---|
158
- | Issuing a draft twice fails the second time | `tests/integration/issue.test.ts` › "is irreversible" |
159
- | Voiding keeps the invoice visible in reports | `tests/integration/void.test.ts` › "stays in monthly report" |
160
- | Two workers issue the same draft | *open*: no test yet |
155
+ ## Scope
156
+ Invoicing modules against a throwaway Postgres; no browser (→ e2e-tests.md).
157
+ ## Conventions
158
+ One database per worker (`fixtures/db.ts`); never share a draft across tests.
159
+ ## Known gaps
160
+ - ⚠️ Two workers issuing the same draft (spec invoicing §3) — not tested yet.
161
161
  ```
162
162
 
163
163
  **`docs/workflow/coding-workflow.md`**: what lives outside the repo, and pointers to what lives in it.
@@ -256,6 +256,7 @@ jobs:
256
256
  /doc-audit # what is missing or stale
257
257
  /spec # write the spec of a subsystem, guided
258
258
  /decision # turn an implicit choice into an ADR
259
+ /story # a proposed leaf with acceptance criteria, before the code
259
260
  ```
260
261
 
261
262
  > [!NOTE]
@@ -274,7 +275,7 @@ jobs:
274
275
  Claude Code · Codex · OpenCode read the same context, write the code
275
276
  │
276
277
  ▼ pre-commit, CI
277
- vaubaan-harness lint 15 linters: shape, links, drift, freshness
278
+ vaubaan-harness lint 19 linters: shape, links, drift, freshness
278
279
  ```
279
280
 
280
281
  1. **Your docs are the context.** A small, fixed layout under `docs/`. Every file has a template and a writer skill, so you rarely start from a blank page.
@@ -285,7 +286,7 @@ jobs:
285
286
 
286
287
  ### Skills
287
288
 
288
- **8 skills**, each with a slash command. A skill never says *when* to do something. It says *how* to write or check one pillar.
289
+ **9 skills**, each with a slash command. A skill never says *when* to do something. It says *how* to write or check one pillar.
289
290
 
290
291
  | Command | Skill | What it does |
291
292
  | ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
@@ -297,10 +298,12 @@ jobs:
297
298
  | `/test-plan` | `test-plan-writer` | Keeps integration and e2e test plans up to date. |
298
299
  | `/workflow` | `workflow-writer` | Documents CI, environments, PR process, branches, release, languages. |
299
300
  | `/readme` | `readme-writer` | Keeps the README in sync with the code. |
301
+ | `/journey` | `journey-writer` | Writes the user journeys, one anchored node at a time; three questions on a greenfield scope, extraction from the code on a mature one. |
302
+ | `/story` | `journey-writer` | Adds a `proposed` leaf with acceptance criteria to the right journey, before any code. |
300
303
 
301
304
  ### Linters
302
305
 
303
- **15 linters**, fast enough to run on every commit.
306
+ **19 linters**, fast enough to run on every commit.
304
307
 
305
308
  <details>
306
309
  <summary>See the list</summary>
@@ -317,6 +320,7 @@ jobs:
317
320
  | `gitignore-harness` | Overrides and reports are ignored; generated files are not. |
318
321
  | `generated-fresh` | Committed generated files match the current render. |
319
322
  | `quality-schema` | `docs/quality/code-quality.md` has its sections, if you use it. |
323
+ | `journey-schema`, `journey-anchors`, `journey-vocabulary`, `journey-graph` | Optional `docs/journeys/`: node grammar, anchors exist, entities are spec vocabulary, nothing requires what nothing creates. |
320
324
 
321
325
  </details>
322
326
 
@@ -420,7 +424,7 @@ npx @vaubaan/harness update . # then commit the result
420
424
 
421
425
  ## Where this is going
422
426
 
423
- Decided, not shipped yet: typed context transactions (`/story`, `/decide`, `/refactor`, `/fix`), an optional `docs/todo/` pillar for increments that fold into the spec when delivered, pointer checks per section, a token budget per file, and `/compact` to rewrite a context that has grown contradictions. The [spec](./docs/spec/coding-agent-harness.md) and the [decisions](./docs/decisions/) say what exists today.
427
+ Shipped: the optional `docs/journeys/` pillar and its first typed context transaction, `/story`, which writes an increment as a `proposed` leaf before the code and passes it `implemented` when delivered. Decided, not shipped yet: the other transactions (`/decide`, `/refactor`, `/fix`), pointer checks per section, a token budget per file, and `/compact` to rewrite a context that has grown contradictions. The [spec](./docs/spec/coding-agent-harness.md) and the [decisions](./docs/decisions/) say what exists today.
424
428
 
425
429
  ## Documentation
426
430