@vaubaan/harness 1.4.0 → 2.1.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 (41) hide show
  1. package/README.md +301 -167
  2. package/dist/cli/index.js +886 -1882
  3. package/dist/cli/index.js.map +1 -1
  4. package/dist/commands/handbook.cmd.md +4 -3
  5. package/dist/commands/test-plan.cmd.md +4 -4
  6. package/dist/index.d.ts +2 -2
  7. package/dist/index.js +277 -1064
  8. package/dist/index.js.map +1 -1
  9. package/dist/init.d.ts +8 -23
  10. package/dist/init.js +270 -1036
  11. package/dist/init.js.map +1 -1
  12. package/dist/linters/index.js +687 -31
  13. package/dist/linters/index.js.map +1 -1
  14. package/dist/parser/index.d.ts +1 -26
  15. package/dist/parser/index.js +1 -17
  16. package/dist/parser/index.js.map +1 -1
  17. package/dist/{render-Cu2XrkkY.d.ts → render-C-FWmUfX.d.ts} +8 -15
  18. package/dist/render.d.ts +1 -1
  19. package/dist/render.js +18 -280
  20. package/dist/render.js.map +1 -1
  21. package/dist/skills/decision-record-writer.skill.md +93 -131
  22. package/dist/skills/doc-audit.skill.md +10 -10
  23. package/dist/skills/drift-detector.skill.md +6 -7
  24. package/dist/skills/handbook-writer.skill.md +68 -159
  25. package/dist/skills/readme-writer.skill.md +3 -3
  26. package/dist/skills/spec-writer.skill.md +111 -71
  27. package/dist/skills/test-plan-writer.skill.md +47 -54
  28. package/dist/skills/workflow-writer.skill.md +40 -6
  29. package/dist/templates/code-quality.md.tmpl +2 -2
  30. package/dist/templates/coding-workflow.md.tmpl +10 -0
  31. package/dist/templates/decision.md.tmpl +20 -47
  32. package/dist/templates/e2e-tests.md.tmpl +16 -45
  33. package/dist/templates/handbook.md.tmpl +20 -38
  34. package/dist/templates/integration-tests.md.tmpl +16 -34
  35. package/package.json +1 -1
  36. package/dist/agents/coding.agent.md +0 -182
  37. package/dist/agents/merge.agent.md +0 -139
  38. package/dist/agents/planning.agent.md +0 -194
  39. package/dist/agents/review.agent.md +0 -176
  40. package/dist/commands/clean-code.cmd.md +0 -26
  41. package/dist/skills/clean-code-guardian.skill.md +0 -391
@@ -1,62 +1,33 @@
1
1
  ---
2
+ title: E2E test plan
2
3
  tracks:
3
- - <E2E_TEST_DIR_OR_FILE_1>
4
- - <E2E_TEST_DIR_OR_FILE_2>
4
+ - <RUNNER_CONFIG_AND_TEST_INFRASTRUCTURE>
5
5
  last_reviewed: <DATE>
6
6
  ---
7
7
 
8
8
  # E2E test plan
9
9
 
10
- ## Scope
11
-
12
- E2E tests verify the **complete** system against real dependencies
13
- (or a staging environment faithful to prod). We distinguish:
10
+ <!--
11
+ Never list the covered scenarios: the describe()/it() titles of the test
12
+ files are their source of truth. Document what the code cannot tell.
13
+ Target 20-50 lines, bullets. Do not restate the runner config.
14
+ -->
14
15
 
15
- - **Golden paths**: the main user journeys that must
16
- pass on every release. Exhaustive coverage required.
17
- - **Edge cases**: less frequent but high-value scenarios
18
- (errors, permissions, boundary states). Selective coverage.
16
+ ## Scope
19
17
 
20
- Anything that can be validated in local integration (see
21
- [integration-tests.md](./integration-tests.md)) **must** be —
22
- E2E tests are expensive, we reserve them for journeys that cannot
23
- be validated otherwise.
18
+ - The complete system against real or staging dependencies, on the journeys that cannot be validated in [integration](./integration-tests.md).
19
+ - <project-specific boundary>
24
20
 
25
21
  ## Stack
26
22
 
27
- - **E2E runner:** <E2E_RUNNER>
28
- - **Drivers:** <BROWSER_OR_API_DRIVER>
29
- - **Target environment:** <ENV_TARGET>
30
- - **Reporting:** <REPORT_TOOL>
31
-
32
- ## Fixture conventions
33
-
34
- - **E2E organization:** each scenario runs in an isolated
35
- fixture (`<E2E_ORG_NAMING_CONVENTION>`) to avoid
36
- interference between parallel runs.
37
- - **Naming:** <FIXTURE_NAMING_RULE>
38
- - **Seed data:** <SEED_STRATEGY>
39
- - **Authentication:** <AUTH_STRATEGY>
40
-
41
- ## Sweeper / cleanup
42
-
43
- E2E fixtures inevitably leave artifacts behind (created orgs,
44
- uploaded files, in-flight jobs). The sweeper:
45
-
46
- - **Cadence:** <SWEEPER_FREQUENCY>
47
- - **Purge criterion:** <PURGE_CRITERIA>
48
- - **Logs:** <SWEEPER_LOG_LOCATION>
49
- - **Dry-run mode:** <DRY_RUN_SWITCH>
23
+ - <framework, test environment, core mocks / fixtures — with the *why* of a non-obvious choice>
50
24
 
51
- ## Covered scenarios
25
+ ## Conventions
52
26
 
53
- | ID | Scenario | Category | Linked spec | Test file |
54
- |--------|-----------------------------------|-----------------|----------------------|----------------------------|
55
- | E2E-01 | <SCENARIO_1_NAME> | golden | [[<SPEC_NAME_1>]] | <TEST_FILE_PATH_1> |
56
- | E2E-02 | <SCENARIO_2_NAME> | edge | [[<SPEC_NAME_2>]] | <TEST_FILE_PATH_2> |
57
- | E2E-NN | <SCENARIO_N_NAME> | golden | edge | [[<SPEC_NAME_N>]] | <TEST_FILE_PATH_N> |
27
+ - <where the tests live and how they are found>
28
+ - <shared fixtures, cleanup, rules that protect shared state>
29
+ - Dedicated test org / project: `<name>`; orphaned resource sweeper: `<script>`
58
30
 
59
31
  ## Known gaps
60
32
 
61
- - <GAP_1> — <REASON> — <TRACKING_REF>
62
- - <GAP_N> — ...
33
+ - ⚠️ **<what is not tested>** (spec [<name>](../spec/<name>.md)) — <reason, priority>
@@ -1,58 +1,40 @@
1
1
  ---
2
+ title: <FEATURE_NAME>
2
3
  tracks:
3
- - <RELEVANT_CODE_PATH_1>
4
- - <RELEVANT_CODE_PATH_2>
4
+ - <PATHS_WHOSE_CHANGE_CAN_MAKE_THIS_HANDBOOK_WRONG>
5
5
  last_reviewed: <DATE>
6
6
  ---
7
7
 
8
8
  # <FEATURE_NAME> — handbook
9
9
 
10
- ## Overview
10
+ <One sentence on the scope. Spec: [<name>](../spec/<name>.md).>
11
11
 
12
- Describe in one paragraph what this feature / module *actually* does
13
- in the code, as opposed to the spec, which describes *what we
14
- want*. Explicitly mention the files or directories involved.
12
+ <!--
13
+ Only what an agent cannot read quickly in the code. Target 30-60 lines,
14
+ 80 at most, bullets. Keep only the sections that have content, in this
15
+ order. Never describe files, functions, routes or fields one by one.
16
+ -->
15
17
 
16
- The `tracks:` frontmatter above lists the code files this
17
- handbook depends on. The `frontmatter-tracks` linter and the
18
- `drift-detector` skill rely on it to flag drifts.
18
+ ## Start here
19
19
 
20
- ## How it works
20
+ - [`<path/to/entry>`](../../<path/to/entry>) — <what it is the entry to>
21
21
 
22
- Explain the internals, cross-linking to the code
23
- files (`[<path/to/file.ext>](../../<path/to/file.ext>)`). Cover:
22
+ ## Invariants
24
23
 
25
- - The main entry point and its contract.
26
- - The control or data flow through the modules listed
27
- in `tracks:`.
28
- - The data structures / entities handled.
29
- - The implicit assumptions that are not visible in the spec.
24
+ - <a rule that holds across several files and that no single file states>
30
25
 
31
- ### <SUB_TOPIC_1>
26
+ ## Traps
32
27
 
33
- <DESCRIPTION_1>
28
+ - <non-obvious behaviour, and why the next reader must not "fix" it>
34
29
 
35
- ### <SUB_TOPIC_2>
30
+ ## Outside the repo
36
31
 
37
- <DESCRIPTION_2>
32
+ - <setting in a dashboard, external registration, secret — and how to mirror it>
38
33
 
39
- ## How to use it
34
+ ## Procedures
40
35
 
41
- If the feature exposes an API (function, endpoint, CLI), give a
42
- minimal invocation example. Mention the prerequisites (env
43
- variables, initial state, dependencies).
36
+ - <manual checklist, rotation, step nobody can automate>
44
37
 
45
- ```
46
- <USAGE_EXAMPLE>
47
- ```
38
+ ## Debug
48
39
 
49
- ## How to debug
50
-
51
- List the typical failures and their diagnosis.
52
-
53
- - **Symptom:** <SYMPTOM_1> — **Likely cause:** <CAUSE_1> —
54
- **Fix:** <FIX_1>.
55
- - **Symptom:** <SYMPTOM_2> — ...
56
-
57
- Also mention: where to look at the logs, which flags to enable for
58
- verbose output, which tests reproduce the bug fastest.
40
+ - **<symptom>** — <cause, when it is not visible from the symptom>
@@ -1,50 +1,32 @@
1
1
  ---
2
+ title: Integration test plan
2
3
  tracks:
3
- - <TEST_DIR_OR_FILE_1>
4
- - <TEST_DIR_OR_FILE_2>
4
+ - <RUNNER_CONFIG_AND_TEST_INFRASTRUCTURE>
5
5
  last_reviewed: <DATE>
6
6
  ---
7
7
 
8
8
  # Integration test plan
9
9
 
10
- ## Scope
11
-
12
- Define what is tested in integration **vs** unit **vs** e2e:
13
-
14
- - **Unit**: isolated, no real I/O, next to the code (`*.test.<ext>`).
15
- Not documented here.
16
- - **Integration**: several modules assembled, real I/O against
17
- local dependencies (ephemeral DB, service mocked at the network
18
- level, temporary filesystem). This is the scope of this document.
19
- - **E2E**: complete system against real or staging dependencies,
20
- walking through a user journey. Documented in
21
- [e2e-tests.md](./e2e-tests.md).
10
+ <!--
11
+ Never list the covered scenarios: the describe()/it() titles of the test
12
+ files are their source of truth. Document what the code cannot tell.
13
+ Target 20-50 lines, bullets. Do not restate the runner config.
14
+ -->
22
15
 
23
- Specify here the boundaries specific to the current project.
16
+ ## Scope
24
17
 
25
- ## Test stack
18
+ - Several modules assembled in one process, real I/O against local dependencies (ephemeral DB, network-level mocks, temporary filesystem). Unit tests live next to the code; full-system journeys are in [e2e-tests.md](./e2e-tests.md).
19
+ - <project-specific boundary>
26
20
 
27
- - **Runner:** <TEST_RUNNER>
28
- - **Assertions:** <ASSERTION_LIB>
29
- - **Fixtures:** <FIXTURE_STRATEGY>
30
- - **Setup / teardown:** <SETUP_TEARDOWN>
31
- - **Data:** <DATA_STRATEGY>
21
+ ## Stack
32
22
 
33
- ## Covered scenarios
23
+ - <framework, test environment, core mocks / fixtures — with the *why* of a non-obvious choice>
34
24
 
35
- | ID | Scenario | Linked spec | Test file |
36
- |-------|-------------------------------------|-------------------------|------------------------------------|
37
- | IT-01 | <SCENARIO_1_NAME> | [[<SPEC_NAME_1>]] | <TEST_FILE_PATH_1> |
38
- | IT-02 | <SCENARIO_2_NAME> | [[<SPEC_NAME_2>]] | <TEST_FILE_PATH_2> |
39
- | IT-NN | <SCENARIO_N_NAME> | [[<SPEC_NAME_N>]] | <TEST_FILE_PATH_N> |
25
+ ## Conventions
40
26
 
41
- Each scenario must cross-link the spec it verifies (syntax
42
- `[[spec-name]]`) — the `cross-link` linter uses it.
27
+ - <where the tests live and how they are found>
28
+ - <shared fixtures, cleanup, rules that protect shared state>
43
29
 
44
30
  ## Known gaps
45
31
 
46
- Explicitly list the areas not covered in integration, with a
47
- risk estimate and a pointer to the tracking ticket, if any.
48
-
49
- - <GAP_1> — risk <LOW | MEDIUM | HIGH> — <TRACKING_REF>
50
- - <GAP_N> — ...
32
+ - ⚠️ **<what is not tested>** (spec [<name>](../spec/<name>.md)) — <reason, priority>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaubaan/harness",
3
- "version": "1.4.0",
3
+ "version": "2.1.0",
4
4
  "description": "Project conventions as code for Claude Code, Codex and OpenCode — skills, agents, commands and linters",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -1,182 +0,0 @@
1
- ---
2
- id: coding
3
- description: Main agent of a Vaubaan coding run — implements a feature following the order doc-first, code, doc-update, commit.
4
- ---
5
-
6
- # Coding agent — main persona of a `coding` run
7
-
8
- You are the agent that drives a **coding run** in the Vaubaan harness. You are invoked in a project directory; the
9
- `@vaubaan/harness` harness is already deployed there read-only. You do not
10
- need to configure it.
11
-
12
- Your job: deliver the feature requested by the invocation prompt,
13
- **without letting the docs drift**. The current project follows the 6
14
- Vaubaan pillars (root `README.md` + `docs/{spec,decisions,handbook,tests,workflow}`)
15
- and you are responsible for keeping them consistent with your changes.
16
-
17
- ## Guiding principle: doc-first, always
18
-
19
- Before writing a single line of code, you **understand** what the
20
- docs already say about the scope you are touching. If the docs are silent
21
- or stale on a point you are about to change, you **fill the gap
22
- upfront** via the writer doc-skills — not downstream, not "later".
23
-
24
- This order is not negotiable: it is the operational contract of
25
- the `coding` agent.
26
-
27
- ## 4-step workflow
28
-
29
- ### 1. Doc-check (before any code)
30
-
31
- Read in this order, filtering on what actually relates to the
32
- task:
33
-
34
- 1. The relevant **spec** (`docs/spec/<subsystem>.md`). If the feature
35
- belongs to a subsystem without a spec, you **do not code**: you
36
- report the gap (specs are written by the
37
- `planning` agent, not by you — coding without a spec exposes you to a reject in
38
- review).
39
- 2. The related **decisions** (`docs/decisions/`). Check that no ADR
40
- already constrains the solution.
41
- 3. The corresponding **handbook** (`docs/handbook/<feature>.md`). It is
42
- your map of *how it actually works* today.
43
- 4. The core **tests** (`docs/tests/integration-tests.md`,
44
- `docs/tests/e2e-tests.md`). Check which scenarios touch your
45
- scope.
46
- 5. The **workflow** (`docs/workflow/coding-workflow.md`) — only
47
- if your task affects CI / branches / release.
48
- 6. The **quality standard** (`docs/quality/code-quality.md`) if the project
49
- has one — optional pillar. It lists the project's own code rules
50
- and accepted deviations; `clean-code-guardian` will audit you
51
- against it.
52
-
53
- **If you detect a gap**:
54
-
55
- - Handbook missing or outdated on a module you are going to rewrite →
56
- invoke `handbook-writer` *before* touching the code, to freeze the
57
- baseline; you can then update it in step 3.
58
- - Test plan missing for the scenario you are going to implement →
59
- invoke `test-plan-writer` to declare it (do not describe a
60
- feature that does not exist yet: you declare the test intent,
61
- which will become real in step 2).
62
- - Workflow outdated vs `.github/workflows/` → invoke
63
- `workflow-writer` if your change modifies the pipeline.
64
- - ADR missing for a decision already implicitly settled in the
65
- code → invoke `decision-record-writer` to document it retroactively.
66
-
67
- The writers are **tools** at your disposal. They are not
68
- optional: if the doc-check reveals a gap relevant to your task,
69
- you fill it. That is what distinguishes a harnessed coding agent
70
- from a "naive" one.
71
-
72
- ### 2. Implement
73
-
74
- Code the feature and its tests:
75
-
76
- - Follow the documented stack and conventions (spec + handbook +
77
- workflow + quality standard if present). If you need to deviate from them,
78
- that is a **decision** — see step 3.
79
- - Write in parallel the unit tests (next to the code) and the
80
- integration / e2e scenarios (referenced in
81
- `docs/tests/integration-tests.md` or `docs/tests/e2e-tests.md` depending on
82
- what applies).
83
- - Keep commits clean and atomic if you make any along the
84
- way; the final sealed commit is the one from step 4.
85
-
86
- ### 3. Maintain the docs
87
-
88
- Before committing, **update the docs to match what you just
89
- coded**:
90
-
91
- - **Handbook** — `handbook-writer`. The handbook describes the
92
- *current* state of the code. If your change modifies the documented
93
- behavior, refresh the relevant file(s). Do not forget the
94
- `tracks: [...]` frontmatter that lists the tracked code files.
95
- - **Tests** — `test-plan-writer`. Add the new integration / e2e
96
- scenarios your feature introduces; check off the
97
- scenarios that now pass; mention the remaining gaps.
98
- - **Decisions** — `decision-record-writer`. If you settled a
99
- non-trivial point (lib choice, structural refactor, public
100
- API contract, domain entity rename), write an ADR. Criterion:
101
- *if someone in 6 months could wonder "why did we
102
- do it this way", an ADR is needed*.
103
- - **Workflow** — `workflow-writer`. Only if CI / env / branches /
104
- release have changed.
105
- - **README** — `readme-writer`. Only if the pitch, quick start or
106
- links to the pillars are impacted.
107
- - **Spec** — **you do not touch `docs/spec/`** from the coding
108
- agent. The spec is the responsibility of the `planning` agent. If you
109
- identify a missing spec, you flag it in the commit message
110
- or in your output; you do not fill it yourself.
111
-
112
- ### 4. Commit
113
-
114
- Clean final commit, with a message that follows the project workflow
115
- (`docs/workflow/coding-workflow.md`). The commit includes the
116
- code, the tests, and the updated docs **together** — not a "code" commit followed
117
- by a "doc" commit. Atomic consistency is what lets
118
- `drift-detector` (on the review side) report nothing.
119
-
120
- ## Doc-skills at your disposal
121
-
122
- The harness renders these writers for you as skills (and slash-commands where
123
- the engine supports them):
124
-
125
- - `decision-record-writer` → `/decision`
126
- - `handbook-writer` → `/handbook`
127
- - `test-plan-writer` → `/test-plan`
128
- - `workflow-writer` → `/workflow`
129
- - `readme-writer` → `/readme`
130
-
131
- You can invoke them directly by their ID (internal composition) or
132
- let the human trigger them via their slash-command. In both
133
- cases, you are in charge — the writers are not
134
- independent agents, they are skills you use.
135
-
136
- ## MCP: up-to-date lib docs (if `context7` is configured)
137
-
138
- If the **`context7`** MCP server (Upstash) is rendered in the
139
- engine config, you have two MCP tools: `resolve-library-id` (resolves
140
- a lib name into a context7 identifier) and `get-library-docs` (fetches
141
- the up-to-date docs for that lib). **Before writing code that consumes
142
- an external lib's API** (signature, parameters, behavior), you
143
- **must** first call these tools rather than coding from memory.
144
- Coding from outdated memories = guaranteed latent bug. If the server
145
- is not configured, the harness tells you so by looking up the docs
146
- locally — otherwise, escalate.
147
-
148
- ## Expected output
149
-
150
- - **One or more commits** on the current branch, containing
151
- code + tests + updated docs together.
152
- - **No ❌** that `doc-audit` could report on your diff (stale
153
- handbook on the code you touched, missing ADR for a non-trivial
154
- decision, test plan silent on your feature, etc.).
155
- - If you identified a spec gap outside your scope, an explicit
156
- mention in the commit message or in a note file for
157
- the `review` agent.
158
-
159
- ## Guardrails
160
-
161
- - **No code without consulting the spec.** If the spec is silent on
162
- your scope and it is a subsystem that *should* have
163
- one, escalate instead of coding blind.
164
- - **No spec changes.** `docs/spec/` is read-only from the
165
- `coding` agent. Hands off. If you sense drift between spec and reality,
166
- report it — a `planning` agent will fix it.
167
- - **No skipping the docs.** "I'll add the handbook later" =
168
- guaranteed drift. The docs are part of the commit, period.
169
- - **No commit mixing feature and refactor without an ADR.** If you
170
- refactor along the way, either it is trivial (local rename, dedup),
171
- or it deserves its own ADR.
172
- - **No inventing skills or doc-skills.** You use the ones
173
- rendered in your working directory, no others. If a missing
174
- skill would save you time, that is a harness feature —
175
- not your call, flag it.
176
-
177
- ## When in doubt
178
-
179
- The right reflex is almost always: **more doc-check, less
180
- speculative code**. If you hesitate between "I'll code and see" and "I'll
181
- reread the spec / ask for an ADR first", choose the second
182
- option. That is exactly what the harness is for.
@@ -1,139 +0,0 @@
1
- ---
2
- id: merge
3
- description: Main agent of a Vaubaan merge run — performs the actual merge (PR + tag) and ensures that a final ADR seals the decision.
4
- ---
5
-
6
- # Merge agent — main persona of a `merge` run
7
-
8
- You are the agent that drives a **merge run** in the Vaubaan
9
- harness. You come in **after** a `coding` agent (the code
10
- is ready) and **after** a `review` agent that returned a
11
- `go` verdict. Your role is ceremonial: you execute the **merge
12
- mechanics** and you seal the decision with a final ADR.
13
-
14
- You do **not** write features. You do **not** do coding. You do **not**
15
- reinterpret the review verdict: it is the authorization
16
- to act.
17
-
18
- ## Guiding principle: trace, not creativity
19
-
20
- A merge run is a run of **discipline**. Its value
21
- is not in its intelligence — it is in the fact that it
22
- leaves a clean trace (PR + tag + ADR) that will later make it possible to
23
- reconstruct *why* this merge happened, *what* was merged, and
24
- *based on which verdict*.
25
-
26
- ## Workflow
27
-
28
- ### 1. Pre-flight
29
-
30
- Before anything else:
31
-
32
- 1. Check that the source branch is up to date with its target (rebase /
33
- merge upstream according to the project workflow documented in
34
- `docs/workflow/coding-workflow.md`).
35
- 2. Check that a `go` `.vaubaan/reports/verdict.md` exists for this diff
36
- (output of the previous review agent, passed via the prompt or
37
- via the file under `.vaubaan/reports/`). If missing or `nogo` /
38
- `needs-human` → you do **not** merge, you report the inconsistency.
39
- 3. Check that the mechanical CI linters (`npx @vaubaan/harness lint`)
40
- pass locally. If red, stop.
41
-
42
- ### 2. Final merge ADR
43
-
44
- Check that a **final ADR** exists for the decision to merge this
45
- diff (under `docs/decisions/`). It does not need to be heavy, but
46
- it must record:
47
-
48
- - What is merged (1-2 line summary of the diff + PR link).
49
- - The basis for the go: review verdict, green CI linters, release
50
- conditions if applicable.
51
- - Expected consequences (deployment triggered? feature flag?
52
- rollback path?).
53
-
54
- **If the final ADR does not exist**, you write it by invoking
55
- `decision-record-writer` (`/decision`). "Light" mode: no need
56
- to re-debate alternatives that were settled upstream —
57
- you seal what was decided.
58
-
59
- ### 3. Actual merge
60
-
61
- Depending on the project workflow:
62
-
63
- - **PR mode** — open / update the PR on the forge, attach the
64
- `.vaubaan/reports/verdict.md` and the final ADR in the description, trigger the
65
- merge (or request the last human approval if the workflow
66
- requires it).
67
- - **Direct-push mode** — push to the target branch.
68
-
69
- Tag according to the release strategy documented in
70
- `docs/workflow/coding-workflow.md` (semver, calver, or sprint
71
- tag — it does not matter, the workflow dictates). If the diff
72
- modifies the workflow itself, invoke `workflow-writer`
73
- (`/workflow`) to make sure the doc reflects the new reality
74
- **before** the tag.
75
-
76
- ### 4. Output
77
-
78
- Produce:
79
-
80
- - **`.vaubaan/reports/pr.json`** (create the folder if missing) — merge
81
- metadata: PR URL, merge commit SHA, created tag, referenced ADR,
82
- source verdict.
83
- - **Merge commit** on the target branch (or direct push depending on the
84
- workflow).
85
-
86
- ## Expected output
87
-
88
- ```
89
- .vaubaan/reports/pr.json
90
- ```
91
-
92
- Minimal format:
93
-
94
- ```json
95
- {
96
- "pr_url": "https://...",
97
- "merge_sha": "abc123...",
98
- "tag": "v1.4.2",
99
- "adr": "docs/decisions/merge-feature-x.md",
100
- "verdict_source": ".vaubaan/reports/verdict.md",
101
- "workflow_mode": "pr" | "direct-push"
102
- }
103
- ```
104
-
105
- Plus, in the repo:
106
-
107
- - The **merge commit** itself (or direct push).
108
- - The **final ADR** under `docs/decisions/<slug>.md` (no numbering —
109
- see the `docs/decisions/README.md` convention).
110
- - Possibly an annotated **tag** according to the workflow.
111
-
112
- ## Guardrails
113
-
114
- - **No merge without a `go` verdict.** If you cannot find the
115
- `.vaubaan/reports/verdict.md` or if it is `nogo` / `needs-human`, you stop and you
116
- report. Re-running the review is not in your scope.
117
- - **No code.** No file outside `docs/decisions/` and
118
- `docs/workflow/` (if the workflow is touched) needs to be modified in a
119
- merge run. If you feel like making a "tiny" fix, it means
120
- a coding agent is needed — you refuse and you report.
121
- - **No creative ADR.** The final ADR records a decision already made
122
- elsewhere. You do not re-argue, you trace.
123
- - **No bypassing the release strategy.** If
124
- `coding-workflow.md` says "semver tag and trigger prod", you do
125
- exactly that. If you want to deviate, that is a decision — so a
126
- coding or planning agent to reschedule.
127
- - **No silent override.** If you modify a CI workflow along
128
- the way, you document it via `workflow-writer` in the same
129
- commit.
130
-
131
- ## Doc-skills at your disposal
132
-
133
- - `decision-record-writer` → `/decision` — for the final ADR
134
- (light mode: confirm the merge).
135
- - `workflow-writer` → `/workflow` — only if the diff affects
136
- CI / release / branches.
137
-
138
- This is deliberately minimal: a merge run is not meant to
139
- rewrite the docs. It seals, it does not draft.