@oscaner-skills/cdd-engine 2.0.0 → 3.0.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 (84) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/package.json +4 -3
  4. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  5. package/src-next/__tests__/floor.guard.test.ts +69 -0
  6. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  7. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  8. package/src-next/__tests__/smoke.integration.test.ts +60 -77
  9. package/src-next/__tests__/support/strip-comments.ts +99 -0
  10. package/src-next/__tests__/zero-dep.test.ts +6 -46
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +39 -21
  12. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +40 -28
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +40 -23
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +38 -21
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +21 -6
  16. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +22 -12
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +23 -8
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +21 -6
  19. package/src-next/contract/__tests__/declare.test.ts +251 -12
  20. package/src-next/contract/__tests__/doc.test.ts +214 -45
  21. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  22. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  23. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  24. package/src-next/contract/__tests__/judge.test.ts +410 -172
  25. package/src-next/contract/__tests__/lint.test.ts +49 -39
  26. package/src-next/contract/__tests__/project.test.ts +60 -19
  27. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  28. package/src-next/contract/declare.ts +179 -91
  29. package/src-next/contract/doc.ts +227 -164
  30. package/src-next/contract/frontmatter.ts +233 -0
  31. package/src-next/contract/home-extractors.ts +397 -0
  32. package/src-next/contract/invariants.ts +214 -69
  33. package/src-next/contract/judge.ts +28 -19
  34. package/src-next/contract/lint.ts +5 -41
  35. package/src-next/contract/project.ts +103 -43
  36. package/src-next/contract/skill-anatomy.ts +39 -11
  37. package/src-next/face/__tests__/board-view.test.ts +318 -115
  38. package/src-next/face/__tests__/capsule.test.ts +49 -25
  39. package/src-next/face/__tests__/channel-closure.guard.test.ts +28 -1
  40. package/src-next/face/__tests__/cli.test.ts +1091 -837
  41. package/src-next/face/__tests__/face.test.ts +5 -5
  42. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  43. package/src-next/face/__tests__/preview.test.ts +374 -0
  44. package/src-next/face/__tests__/projection.test.ts +5 -3
  45. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  46. package/src-next/face/__tests__/termination.test.ts +650 -0
  47. package/src-next/face/artifacts.ts +90 -37
  48. package/src-next/face/board-view.ts +128 -138
  49. package/src-next/face/capsule.ts +30 -16
  50. package/src-next/face/cli.ts +306 -97
  51. package/src-next/face/declare.ts +15 -18
  52. package/src-next/face/gate.ts +19 -18
  53. package/src-next/face/host.ts +6 -30
  54. package/src-next/face/lifecycle.ts +213 -188
  55. package/src-next/face/preview.ts +151 -0
  56. package/src-next/face/projection.ts +4 -1
  57. package/src-next/face/route-render.ts +39 -14
  58. package/src-next/face/termination.ts +573 -0
  59. package/src-next/face/words.ts +20 -2
  60. package/src-next/infra/__tests__/infra.test.ts +49 -3
  61. package/src-next/infra/__tests__/root.test.ts +56 -0
  62. package/src-next/infra/doc-roots.ts +29 -0
  63. package/src-next/infra/root.ts +73 -0
  64. package/src-next/infra/runtime.ts +12 -65
  65. package/src-next/infra/workspace.ts +95 -5
  66. package/src-next/render/__tests__/render.test.ts +92 -41
  67. package/src-next/render/__tests__/skeleton.test.ts +282 -64
  68. package/src-next/render/issue-body.ts +5 -2
  69. package/src-next/render/skeleton.ts +155 -90
  70. package/src-next/render/templates.ts +51 -56
  71. package/src-next/session/__tests__/graph.test.ts +11 -4
  72. package/src-next/session/__tests__/ledger.test.ts +3 -2
  73. package/src-next/session/__tests__/next.test.ts +100 -8
  74. package/src-next/session/__tests__/preflight.test.ts +79 -25
  75. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  76. package/src-next/session/__tests__/run.test.ts +140 -128
  77. package/src-next/session/__tests__/wave.test.ts +11 -4
  78. package/src-next/session/ledger.ts +96 -24
  79. package/src-next/session/next.ts +116 -15
  80. package/src-next/session/preflight.ts +41 -10
  81. package/src-next/session/round-naming.ts +84 -0
  82. package/src-next/session/run.ts +24 -20
  83. package/templates/report/issue-body.json +0 -46
  84. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
@@ -1,7 +1,7 @@
1
1
  // packages/cdd-engine/src-next/render/templates.ts
2
2
  // T21 — the template-contract typed surface: the template-contract JSON's data-plane
3
3
  // home PLUS the TemplateAssembler (one module, one renderer). The dispatch prompt
4
- // data (the per-mode shell frames · the review variants · the return-format block ·
4
+ // data (the per-mode shell frames · the review variants · the single prose return block ·
5
5
  // the round-context subsets · the token registry · the clause partials) and the
6
6
  // review criteria (the four-type axes guides — P4, extended to spec/plan by the
7
7
  // v1.8 review-closeout) are typed constant data here, imported never parsed:
@@ -34,7 +34,7 @@
34
34
  // in the same plane: the `## Handoff schema` section at every shell's tail carries
35
35
  // the {{HANDOFF_SCHEMA}} slot (projection ① of session/handoff-schema.ts — the same
36
36
  // declared objects the engine validates the draft against, projection ②). The
37
- // handoff-format prose is gone; RETURN_STDOUT_BLOCK is the ONE return contract.
37
+ // handoff-format prose is gone; RETURN_PROSE is the ONE return contract.
38
38
  //
39
39
  // T15 v1.10/1.11 (the review-closeout batch — §3.7) refines the shell composition:
40
40
  // the work-mode tail is the shared EVIDENCE_ITEM cell (implement/fix carry it;
@@ -42,12 +42,13 @@
42
42
  // variants fold the criteria/lens in.
43
43
  //
44
44
  // P5 (M1) supersede: the implement mode's dispatch wording names the upstream
45
- // `mattpocock-skills:implement` skill (the ref the dispatch row now resolves to),
46
- // never the retired tdd alias.
45
+ // implement skill ref (`DISPATCH.implement`, the ref the dispatch row resolves
46
+ // to), never the retired tdd alias.
47
47
  //
48
48
  // Module-level exports are types / the declared constant data / the class — zero
49
49
  // behavior-carrying bare functions (the plan's zero-bare-function discipline).
50
50
 
51
+ import { DISPATCH } from "../face/host.ts";
51
52
  import type { TargetType } from "../session/faces.ts";
52
53
 
53
54
  /** The per-dispatch slot values — one entry per declared template token. */
@@ -63,11 +64,6 @@ export interface TemplateToken {
63
64
  zone: string;
64
65
  }
65
66
 
66
- /** One per-return-format block — the `## Return` zone's declared variants. */
67
- export interface ReturnZone {
68
- [format: string]: readonly string[];
69
- }
70
-
71
67
  /** The work-modes of the dispatch table — the ROLE values (fix's spec/plan face is
72
68
  * the docs-fix mode; review covers task/branch/spec/plan + branch-review). */
73
69
  export type WorkMode = "implement" | "fix" | "review" | "docs-fix";
@@ -102,8 +98,10 @@ export interface TemplatePrompt {
102
98
  /** The review mode's per-type rows — each variant's fixed prefix carries its
103
99
  * criteria + lens (folded in, never tokens). */
104
100
  reviews: Readonly<Record<TargetType, ModePromptRow>>;
105
- /** The `## Return` zone — the single block contract (v1.9). */
106
- return: ReturnZone;
101
+ /** The `## Return` zone — the single plain-prose block (P11: the child's stdout
102
+ * contract is prose, never a fixed key=value block; the handoff draft is the
103
+ * round's machine-readable result). */
104
+ return: { readonly RETURN_PROSE: readonly string[] };
107
105
  /** The token registry — the union across every mode's round context + the shell's
108
106
  * schema slot (the gate's declared list). */
109
107
  tokens: readonly TemplateToken[];
@@ -164,7 +162,7 @@ const IMPLEMENT_SHELL: readonly string[] = [
164
162
  "## Instructions",
165
163
  "",
166
164
  ...FRAME_ITEMS,
167
- "**implement:** read `INPUT_WAVE_BRIEF` (the complete plan mirror — every `### Task N:` of the wave + the plan's `## Constraints` section, fresh-extracted at dispatch). `WAVE` = this round's wave (the task list); implement ALL tasks of the wave, never a subset. `CONFIRMED_SEAMS` in the brief → apply as-is; else propose test boundaries in the report, then invoke **`mattpocock-skills:implement`**. Write the handoff draft at `OUTPUT_HANDOFF` per `## Handoff schema` BEFORE the return block: `status` (APPROVED once applied, else BLOCKED + `failure_category`) and `artifacts` (the prescribed `OUTPUT_REPORT`/`OUTPUT_EVIDENCE` paths from the round context — the `{family}-{key}-` canonical names, zero free naming).",
165
+ `**implement:** read \`INPUT_WAVE_BRIEF\` (the complete plan mirror — every \`### Task N:\` of the wave + the plan's \`## Constraints\` section, fresh-extracted at dispatch). \`WAVE\` = this round's wave (the task list); implement ALL tasks of the wave, never a subset. \`CONFIRMED_SEAMS\` in the brief → apply as-is; else propose test boundaries in the report, then invoke **\`${DISPATCH.implement}\`**. Write the handoff draft at \`OUTPUT_HANDOFF\` per \`## Handoff schema\` BEFORE the return block: \`status\` (APPROVED once applied, else BLOCKED + \`failure_category\`) and \`artifacts\` (the prescribed \`OUTPUT_REPORT\`/\`OUTPUT_EVIDENCE\` paths from the round context — the \`{family}-{key}-\` canonical names, zero free naming).`,
168
166
  EVIDENCE_ITEM,
169
167
  ...LICENSE_ITEMS,
170
168
  ...SCHEMA_SECTION,
@@ -184,7 +182,7 @@ const FIX_SHELL: readonly string[] = [
184
182
  "",
185
183
  ...FRAME_ITEMS,
186
184
  ...FIX_TYPED_INSTRUCTIONS,
187
- "**fix:** read `INPUT_FINDINGS` (open findings) + the plan context (`INPUT_WAVE_BRIEF` on a wave line — the complete plan mirror; `INPUT_DOC` on the branch/doc lines — the plan document). Fix ALL findings (blocker/warn/nit), verifying against `INPUT_FINDINGS` none remain open. Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; draft write failure → `status: BLOCKED`; retry = full re-run (idempotent).",
185
+ "**fix:** read `INPUT_REVIEWS` (open findings) + the plan context (`INPUT_WAVE_BRIEF` on a wave line — the complete plan mirror; `INPUT_PLAN` on the plan/branch lines — the plan document; `INPUT_SPEC` on the spec line — the spec document). Fix ALL findings (blocker/warn/nit), verifying against `INPUT_REVIEWS` none remain open. Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; draft write failure → `status: BLOCKED`; retry = full re-run (idempotent).",
188
186
  EVIDENCE_ITEM,
189
187
  ...LICENSE_ITEMS,
190
188
  // T5 (v0.3) — The work face's ONE strict-schema sentence: every top-level draft
@@ -205,7 +203,7 @@ const DOCS_FIX_SHELL: readonly string[] = [
205
203
  "## Instructions",
206
204
  "",
207
205
  ...FRAME_ITEMS,
208
- "**docs-fix:** apply `INPUT_FINDINGS` (all severities) directly to `INPUT_DOC`, removing fixed findings; record the path in `artifacts.doc`; empty `findings` = all fixed. Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema`; the engine derives the conclusion from the residual findings; draft write failure → `status: BLOCKED`; retry = full re-run (idempotent).",
206
+ "**docs-fix:** apply `INPUT_REVIEWS` (all severities) directly to the judged doc — `INPUT_PLAN` on a plan-doc line, `INPUT_SPEC` on a spec-doc line — removing fixed findings; record the path in `artifacts.doc`; empty `findings` = all fixed. Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema`; the engine derives the conclusion from the residual findings; draft write failure → `status: BLOCKED`; retry = full re-run (idempotent).",
209
207
  ...LICENSE_ITEMS,
210
208
  // T5 (v0.3) — The findings face's ONE strict-schema sentence: same schema-first
211
209
  // directive as the work shell, naming the required `findings` (carried over from
@@ -213,27 +211,28 @@ const DOCS_FIX_SHELL: readonly string[] = [
213
211
  // the sentence never contradicts the findings carrier's own required gate; the
214
212
  // work shell's field list is never copied here, and no field enumeration rides
215
213
  // the findings shell's prose either).
216
- "**Draft fields:** every top-level field of the draft comes from the `## Handoff schema` declared `properties` — `findings` (required) rides over from `INPUT_FINDINGS` verbatim, unmodified; the declaration is the field source, zero extra keys.",
214
+ "**Draft fields:** every top-level field of the draft comes from the `## Handoff schema` declared `properties` — `findings` (required) rides over from `INPUT_REVIEWS` verbatim, unmodified; the declaration is the field source, zero extra keys.",
217
215
  ...SCHEMA_SECTION,
218
216
  ];
219
217
 
220
218
  /** The review variants' shared instruction text — the review's mode rule (the
221
219
  * criteria body + the lens vocabulary ride per-type fixed items below). */
222
220
  const REVIEW_ITEM =
223
- "**review:** review the criteria below against the reference face named in the round context. Wave reviews judge `INPUT_WAVE_BRIEF` (the complete plan mirror); the branch/spec/plan reviews judge `INPUT_DOC`. Write findings into the draft at `OUTPUT_HANDOFF` per `## Handoff schema` (never print them); empty `findings` = approved. The engine derives the conclusion from the draft's findings (blocker → CHANGES_REQUESTED · warn/nit → REVIEW_FIX · none → APPROVED) — a review never declares its own status.";
221
+ "**review:** review the criteria below against the reference face named in the round context. Wave reviews judge `INPUT_WAVE_BRIEF` (the complete plan mirror); the plan/branch reviews judge the plan at `INPUT_PLAN`, the spec review judges the spec at `INPUT_SPEC`. Write findings into the draft at `OUTPUT_HANDOFF` per `## Handoff schema` (never print them); empty `findings` = approved. The engine derives the conclusion from the draft's findings (blocker → CHANGES_REQUESTED · warn/nit → REVIEW_FIX · none → APPROVED) — a review never declares its own status.";
224
222
 
225
223
  /** The review mode's shared reduced tail — the only dynamic region of every review
226
224
  * variant (the criteria/lens are fixed-prefix per type, never here). Each review
227
- * type carries its own referent (wave → `INPUT_WAVE_BRIEF`; branch/spec/plan →
228
- * `INPUT_DOC`); the branch review additionally carries `BASE_BRANCH` (the scope
229
- * anchor). Empty slots are dropped by the assembler. */
225
+ * type carries its own judged-doc referent (wave → `INPUT_WAVE_BRIEF`; plan/branch
226
+ * → `INPUT_PLAN`; spec → `INPUT_SPEC`); the branch review additionally carries
227
+ * `BASE_BRANCH` (the scope anchor). Empty slots are dropped by the assembler. */
230
228
  const REVIEW_CONTEXT: readonly string[] = [
231
229
  "## Round context",
232
230
  "",
233
231
  "- `ROLE`: {{ROLE}}",
234
232
  "- `WAVE`: {{WAVE}}",
235
233
  "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
236
- "- `INPUT_DOC`: {{INPUT_DOC}}",
234
+ "- `INPUT_PLAN`: {{INPUT_PLAN}}",
235
+ "- `INPUT_SPEC`: {{INPUT_SPEC}}",
237
236
  "- `BASE_BRANCH`: {{BASE_BRANCH}}",
238
237
  "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
239
238
  "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
@@ -271,8 +270,9 @@ const MODE_PROMPTS: Readonly<Record<WorkModeRowKey, ModePromptRow>> = {
271
270
  "- `ROLE`: {{ROLE}}",
272
271
  "- `WAVE`: {{WAVE}}",
273
272
  "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
274
- "- `INPUT_DOC`: {{INPUT_DOC}}",
275
- "- `INPUT_FINDINGS`: {{INPUT_FINDINGS}}",
273
+ "- `INPUT_PLAN`: {{INPUT_PLAN}}",
274
+ "- `INPUT_SPEC`: {{INPUT_SPEC}}",
275
+ "- `INPUT_REVIEWS`: {{INPUT_REVIEWS}}",
276
276
  "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
277
277
  "- `OUTPUT_EVIDENCE`: {{OUTPUT_EVIDENCE}}",
278
278
  "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
@@ -288,8 +288,9 @@ const MODE_PROMPTS: Readonly<Record<WorkModeRowKey, ModePromptRow>> = {
288
288
  "",
289
289
  "- `ROLE`: {{ROLE}}",
290
290
  "- `WAVE`: {{WAVE}}",
291
- "- `INPUT_DOC`: {{INPUT_DOC}}",
292
- "- `INPUT_FINDINGS`: {{INPUT_FINDINGS}}",
291
+ "- `INPUT_PLAN`: {{INPUT_PLAN}}",
292
+ "- `INPUT_SPEC`: {{INPUT_SPEC}}",
293
+ "- `INPUT_REVIEWS`: {{INPUT_REVIEWS}}",
293
294
  "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
294
295
  "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
295
296
  "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
@@ -305,22 +306,22 @@ export const REVIEWS = {
305
306
  wave: {
306
307
  lensEnum: ["standards", "spec", "buildability"],
307
308
  axesGuide:
308
- "Standards axis (repo coding standards + code-review smell baseline) + Spec axis (wave brief / plan requirements) + Buildability axis (the reviewer explicitly runs the repository's typecheck command — `tsc --noEmit`, or the repo equivalent — AND its test command; every buildability finding self-reports the dual evidence, both commands ran) + Scope axis (changed-surface reasonableness): run `git diff origin/<BASE_BRANCH>..HEAD` yourself (BASE_BRANCH as named in the round context; on a missing artifact judge the working tree) — every changed file must fall within the wave brief's file surface (`**Files:**` seams) or be attributable to the plan / reviewed intent; an unattributable changed file is a candidate finding (severity by your judgment). The reviewer is the changed-surface judge — the engine reconciles nothing. Single agent, four axes.",
309
+ "Standards axis (repo coding standards + code-review smell baseline) + Spec axis (wave brief / plan requirements) + Buildability axis (the reviewer explicitly runs the repository's typecheck command — `tsc --noEmit`, or the repo equivalent — AND its test command; every buildability finding self-reports the dual evidence, both commands ran) + Scope axis (changed-surface reasonableness): run `git diff origin/<BASE_BRANCH>..HEAD` yourself (BASE_BRANCH as named in the round context; on a missing artifact judge the working tree) — every changed file must fall within the wave brief's file surface (`**Files:**` seams) or be attributable to the plan / reviewed intent; an unattributable changed file is a candidate finding (severity by your judgment). The reviewer is the changed-surface judge — the engine reconciles nothing. The reviewed artifact is a vision, not an exhaustive enumeration — behavior it is silent on is judged by what a reasonable user would expect; its silence is not permission, and a finding's severity grades that expectation, not whether the text mentions the trigger. Before your verdict, list every behavior you considered and set aside as outside the reviewed scope — one line each with the reason; nothing set aside is dropped silently; an empty list means you set nothing aside. Calibrate findings by real severity — not everything is a blocker — and acknowledge what was done well before listing findings (accurate praise earns the rest of the report trust). Single agent, four axes.",
309
310
  },
310
311
  branch: {
311
312
  lensEnum: ["standards", "spec", "buildability"],
312
313
  axesGuide:
313
- "Same four axes as task (branch-wide health: run `git diff origin/<BASE_BRANCH>..HEAD` + plan conformance) + Buildability axis (the reviewer explicitly runs the repository's typecheck command — `tsc --noEmit`, or the repo equivalent — AND its test command; every buildability finding self-reports the dual evidence, both commands ran) + Scope axis (changed-surface reasonableness): branch review IS the full diff — every changed file must be attributable to a finding, a plan requirement, or the reviewed intent; unrelated surface = candidate finding (severity by your judgment), normal finding → fix loop.",
314
+ "Same four axes as task (branch-wide health: run `git diff origin/<BASE_BRANCH>..HEAD` + plan conformance) + Buildability axis (the reviewer explicitly runs the repository's typecheck command — `tsc --noEmit`, or the repo equivalent — AND its test command; every buildability finding self-reports the dual evidence, both commands ran) + Scope axis (changed-surface reasonableness): branch review IS the full diff — every changed file must be attributable to a finding, a plan requirement, or the reviewed intent; unrelated surface = candidate finding (severity by your judgment), normal finding → fix loop. The reviewed artifact is a vision, not an exhaustive enumeration — behavior it is silent on is judged by what a reasonable user would expect; its silence is not permission, and a finding's severity grades that expectation, not whether the text mentions the trigger. Before your verdict, list every behavior you considered and set aside as outside the reviewed scope — one line each with the reason; nothing set aside is dropped silently; an empty list means you set nothing aside. Calibrate findings by real severity — not everything is a blocker — and acknowledge what was done well before listing findings (accurate praise earns the rest of the report trust).",
314
315
  },
315
316
  spec: {
316
317
  lensEnum: ["completeness", "consistency", "clarity"],
317
318
  axesGuide:
318
- "Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity) + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding",
319
+ "Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity) + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + The reviewed spec is a vision, not an exhaustive enumeration — behavior it is silent on is judged by what a reasonable downstream author would expect; its silence is not permission, and a finding's severity grades that expectation, not whether the text mentions the trigger. Before your verdict, list every behavior you considered and set aside as outside the reviewed scope — one line each with the reason; nothing set aside is dropped silently; an empty list means you set nothing aside. Calibrate findings by real severity — not everything is a blocker — and acknowledge what was done well before listing findings (accurate praise earns the rest of the report trust).",
319
320
  },
320
321
  plan: {
321
322
  lensEnum: ["completeness", "decomposition", "buildability"],
322
323
  axesGuide:
323
- "Follow URC: single-cycle, lens-tagged findings (completeness/decomposition/buildability) + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding",
324
+ "Follow URC: single-cycle, lens-tagged findings (completeness/decomposition/buildability) + spec conformance — the plan is judged against its design spec at `INPUT_SPEC` (the plan's `spec` front-matter target): every spec requirement must map to a task, and a spec requirement with no owning task is a completeness finding + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + The reviewed spec is a vision, not an exhaustive enumeration — behavior it is silent on is judged by what a reasonable implementer would expect; its silence is not permission, and a finding's severity grades that expectation, not whether the text mentions the trigger. Before your verdict, list every behavior you considered and set aside as outside the reviewed scope — one line each with the reason; nothing set aside is dropped silently; an empty list means you set nothing aside. Calibrate findings by real severity — not everything is a blocker — and acknowledge what was done well before listing findings (accurate praise earns the rest of the report trust).",
324
325
  },
325
326
  } as const satisfies ReviewGuides;
326
327
 
@@ -405,22 +406,19 @@ const REVIEW_VARIANTS: Readonly<Record<TargetType, ModePromptRow>> = {
405
406
  },
406
407
  };
407
408
 
408
- /** The `## Return` zone — the single block contract (v1.9: the child's content
409
- * lives in the draft file, the block is the pointer every mode returns). */
410
- const RETURN_ZONE: ReturnZone = {
411
- RETURN_STDOUT_BLOCK: [
409
+ /** The `## Return` zone — the single plain-prose contract block (P11: the child
410
+ * narrates the round in prose; nothing downstream parses its stdout — the handoff
411
+ * draft at `OUTPUT_HANDOFF` is the round's machine-readable result). */
412
+ const RETURN_ZONE: TemplatePrompt["return"] = {
413
+ RETURN_PROSE: [
412
414
  "## Return",
413
415
  "",
414
- "Output exactly 2 lines — this block is the FINAL output; nothing may follow it:",
415
- "",
416
- "```",
417
- "status: <APPROVED|BLOCKED>",
418
- "artifacts: report=<path> test_evidence=<path>",
419
- "```",
416
+ "Report in a few plain sentences what this round did, whether it succeeded, and — if it",
417
+ "did not — what blocked it. Nothing downstream parses this text; the handoff draft at",
418
+ "`OUTPUT_HANDOFF` is the round's machine-readable result. Do not emit key-value lines,",
419
+ "JSON, or any fixed block.",
420
420
  "",
421
- "RETURN_STDOUT_BLOCK (one contract): the handoff content (findings/notes/evidence) lives in the draft at `OUTPUT_HANDOFF` — this block is the pointer. Review/docs-fix rounds state `status: APPROVED` (their conclusion derives from the draft's findings); work rounds state the concluding status. Never emit the 3rd `counters:` / 4th `next:` lines (the engine appends them). Any non-`APPROVED` status (e.g. `NEEDS_CONTEXT`) → collapsed to `BLOCKED` + exit 1.",
422
- "",
423
- "The `artifacts:` line's paths are the round context's prescribed `OUTPUT_REPORT`/`OUTPUT_EVIDENCE` values — copy them verbatim (zero free naming; a declared path deviating from the canonical name is corrected to it and flagged on the carrier's notes).",
421
+ "(fail: an uncaught failure → exit non-zero with a one-line reason)",
424
422
  ],
425
423
  };
426
424
 
@@ -432,8 +430,9 @@ const RETURN_ZONE: ReturnZone = {
432
430
  const TOKENS: readonly TemplateToken[] = [
433
431
  { name: "BASE_BRANCH", zone: "round-context" },
434
432
  { name: "HANDOFF_SCHEMA", zone: "shell" },
435
- { name: "INPUT_DOC", zone: "round-context" },
436
- { name: "INPUT_FINDINGS", zone: "round-context" },
433
+ { name: "INPUT_PLAN", zone: "round-context" },
434
+ { name: "INPUT_SPEC", zone: "round-context" },
435
+ { name: "INPUT_REVIEWS", zone: "round-context" },
437
436
  { name: "INPUT_WAVE_BRIEF", zone: "round-context" },
438
437
  // find #5 — the prescribed artifact write paths (the {family}-{key}-{artifact}
439
438
  // single naming; the brief is a pure read input with no write slot).
@@ -465,12 +464,14 @@ export const CLAUSES = {
465
464
  "Self-validate before returning: run the validation/checks your change requires and record the evidence (command + exit code + result) in the report.",
466
465
  } as const;
467
466
 
468
- /** The dispatch-prompt data plane — the typed template-contract surface. $version 7
469
- * is the single-reference-face shape: one doc anchor per line (INPUT_DOC /
470
- * INPUT_WAVE_BRIEF), the branch scope anchor BASE_BRANCH, the two-line return
471
- * contract, and the per-type review criterion shells. */
467
+ /** The dispatch-prompt data plane — the typed template-contract surface. $version 9
468
+ * is the kind-named doc-anchor shape (INPUT_PLAN / INPUT_SPEC replace the generic
469
+ * INPUT_DOC; INPUT_WAVE_BRIEF), the branch scope anchor BASE_BRANCH, the single
470
+ * prose return contract (`RETURN_PROSE` — nothing downstream parses the child's
471
+ * stdout), and the per-type review criterion shells. The bump from 8 marks the
472
+ * return-shape change (the two-line key-value block retired). */
472
473
  export const TEMPLATE_PROMPT = {
473
- $version: 7,
474
+ $version: 9,
474
475
  modes: MODE_PROMPTS,
475
476
  reviews: REVIEW_VARIANTS,
476
477
  return: RETURN_ZONE,
@@ -495,12 +496,6 @@ export class TemplateAssembler {
495
496
  this.#contract = TEMPLATE_PROMPT;
496
497
  }
497
498
 
498
- /** The return formats the contract declares — the single block contract (v1.9:
499
- * one format; every pre-v1.9 return variant is retired). */
500
- returnFormats(): readonly string[] {
501
- return Object.keys(this.#contract.return);
502
- }
503
-
504
499
  /** The tokens the contract declares (the union across every mode — all zones). */
505
500
  declaredTokens(): readonly string[] {
506
501
  return this.#contract.tokens.map((token) => token.name);
@@ -519,7 +514,7 @@ export class TemplateAssembler {
519
514
  const row = this.#rowOf(values);
520
515
  const zones: Record<string, string> = {
521
516
  shell: this.#joinLines(row.shell),
522
- return: this.#joinLines(this.#contract.return.RETURN_STDOUT_BLOCK),
517
+ return: this.#joinLines(this.#contract.return.RETURN_PROSE),
523
518
  "round-context": this.#contextLines(row, values),
524
519
  };
525
520
  return this.#fill([zones.shell, zones.return, zones["round-context"]].join("\n\n"), values);
@@ -606,7 +601,7 @@ export class TemplateAssembler {
606
601
  const namesOf = (text: string): string[] => text.match(naming) ?? [];
607
602
  const allowed = new Set<string>([
608
603
  ...row.roundContext.flatMap((line) => namesOf(line)),
609
- ...namesOf(this.#joinLines(this.#contract.return.RETURN_STDOUT_BLOCK)),
604
+ ...namesOf(this.#joinLines(this.#contract.return.RETURN_PROSE)),
610
605
  ]);
611
606
  for (const name of new Set(namesOf(this.#joinLines(row.shell)))) {
612
607
  if (!allowed.has(name)) {
@@ -20,12 +20,19 @@ import { PlanDocType } from "../../contract/doc.ts";
20
20
  import type { GraphIssue } from "../graph.ts";
21
21
  import { TaskGraph } from "../graph.ts";
22
22
 
23
- /** A plan document over `### Task N:` blocks + `- **DependsOn**:` values. */
23
+ /** A plan document over `### Task N:` blocks + `- **DependsOn**:` values (the
24
+ * front-matter head the plan parser reads). */
24
25
  const planDoc = (blocks: readonly (readonly string[])[]): string => {
25
26
  return [
26
- "# Test Plan",
27
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
28
- "- **Parent program**: [x-overall.md v1.0](docs/kairos/specs/x-overall.md)",
27
+ "---",
28
+ "title: Test Plan",
29
+ "doc-type: plan",
30
+ "version: v1.0",
31
+ "date: 2026-10-09",
32
+ "spec: docs/kairos/specs/x-design.md",
33
+ "parent-program: docs/kairos/specs/x-overall.md",
34
+ "parent-version: v1.0",
35
+ "---",
29
36
  "",
30
37
  "## Constraints",
31
38
  "",
@@ -313,6 +313,7 @@ describe("crash — the lane-crash recovery record", () => {
313
313
  attemptedHandoff: "tasks-1-implement.json",
314
314
  next: "cdd implement --tasks 1",
315
315
  cause: "child-exit" as const,
316
+ lastSample: null,
316
317
  };
317
318
  ledger.writeCrash("implement", 1, record);
318
319
  expect(ledger.readCrash("implement", 1)).toEqual(record);
@@ -351,7 +352,7 @@ describe("round — the round carrier", () => {
351
352
  { severity: "blocker", summary: "defect" },
352
353
  { severity: "warn", summary: "smell" },
353
354
  ]);
354
- expect(carrier!.findingsPath).toBe(workspace.resolve("tasks-7,9-review-1.json"));
355
+ expect(carrier!.reviewsPath).toBe(workspace.resolve("tasks-7,9-review-1.json"));
355
356
  expect(carrier!.consecutiveS1).toBe(1);
356
357
  } finally {
357
358
  cleanup();
@@ -379,7 +380,7 @@ describe("round — the round carrier", () => {
379
380
  expect(carrier!.phase).toBe("fix");
380
381
  // the judgment findings are the source review's input, never the fix's own empty carrier
381
382
  expect(carrier!.findings).toEqual([{ severity: "blocker", summary: "the input findings" }]);
382
- expect(carrier!.findingsPath).toBe(workspace.resolve("tasks-7,9-review-1.json"));
383
+ expect(carrier!.reviewsPath).toBe(workspace.resolve("tasks-7,9-review-1.json"));
383
384
  expect(carrier!.consecutiveS1).toBe(1);
384
385
  } finally {
385
386
  cleanup();
@@ -27,6 +27,7 @@ import {
27
27
  FIX_READBACK_SUFFIX,
28
28
  NextStepRouter,
29
29
  PIPELINE_NEXT,
30
+ type PipelineFaceReport,
30
31
  REVIEW_CYCLE_CAP,
31
32
  SOFT_CAP_SUGGESTION,
32
33
  } from "../next.ts";
@@ -77,9 +78,9 @@ describe("review rounds — zero findings flows the next wave on or closes the r
77
78
  expect(
78
79
  router.next(
79
80
  state([]),
80
- round({ phase: "review", findings, findingsPath: "tasks-7,9-review-1.json" }),
81
+ round({ phase: "review", findings, reviewsPath: "tasks-7,9-review-1.json" }),
81
82
  ),
82
- ).toEqual({ kind: "fix", findings: "tasks-7,9-review-1.json" });
83
+ ).toEqual({ kind: "fix", reviews: "tasks-7,9-review-1.json" });
83
84
 
84
85
  const blockers: Round["findings"] = [finding("blocker", "defect")];
85
86
  expect(router.next(state([]), round({ phase: "review", findings: blockers }))).toEqual({
@@ -167,8 +168,8 @@ describe("the failure face — BLOCKED/TIMEOUT produce no next line", () => {
167
168
  });
168
169
 
169
170
  describe("the pinned surface — Route/soft-cap constants (the brief's type-check checkable)", () => {
170
- it("the soft-cap constant is the literal 10 and the wording is stable", () => {
171
- expect(REVIEW_CYCLE_CAP).toBe(10);
171
+ it("the soft-cap constant is the literal 20 and the wording is stable", () => {
172
+ expect(REVIEW_CYCLE_CAP).toBe(20);
172
173
  expect(SOFT_CAP_SUGGESTION).toBe("BLOCKED: review-cycle-cap — user adjudicates");
173
174
  });
174
175
 
@@ -188,11 +189,11 @@ describe("the pinned surface — Route/soft-cap constants (the brief's type-chec
188
189
 
189
190
  it("the soft-cap constants keep their literal types at compile time", () => {
190
191
  // Compile-time pins — this file fails under `tsc --noEmit` if either constant's
191
- // declared type drifts from the decision table's domain (cap == 10, verbatim wording).
192
- const cap: 10 = REVIEW_CYCLE_CAP;
192
+ // declared type drifts from the decision table's domain (cap == 20, verbatim wording).
193
+ const cap: 20 = REVIEW_CYCLE_CAP;
193
194
  const wording: "BLOCKED: review-cycle-cap — user adjudicates" = SOFT_CAP_SUGGESTION;
194
195
  expect({ cap, wording }).toEqual({
195
- cap: 10,
196
+ cap: 20,
196
197
  wording: "BLOCKED: review-cycle-cap — user adjudicates",
197
198
  });
198
199
  });
@@ -306,7 +307,7 @@ describe("P4.1 T4 — the router's routes render parseable next literals (zero-e
306
307
  it.each([
307
308
  ["implement wave", { kind: "next-wave", tasks: "1,2" } as Route],
308
309
  ["re-review", { kind: "review" } as Route],
309
- ["the one-way fix hop", { kind: "fix", findings: "tasks-1-review-1.json" } as Route],
310
+ ["the one-way fix hop", { kind: "fix", reviews: "tasks-1-review-1.json" } as Route],
310
311
  ["closure", { kind: "done" } as Route],
311
312
  ] as const)("%s — the route's literal argv parses", (_label, route) => {
312
313
  if (route.kind === "done") {
@@ -366,3 +367,94 @@ describe("D40 — the face-to-face handoff route + the single resolver", () => {
366
367
  expect(NextStepRouter.resolve(null, null)).toEqual({ kind: "done" });
367
368
  });
368
369
  });
370
+
371
+ // ---------------------------------------------------------------------------
372
+ // D40 / D26 — walk(): the ONE face-to-face traversal. The board reports the
373
+ // observed faces (keyed), the router decides the next step. This is the D26 guard
374
+ // for the board off-by-one: a just-closed spec hands off to the SPEC's exit
375
+ // (cdd-plan), never the absent plan's exit (cdd-dev).
376
+ // ---------------------------------------------------------------------------
377
+
378
+ describe("D40/D26 — walk(): the single face-to-face traversal", () => {
379
+ /** A face report with every face unentered/open by default (the caller overrides). */
380
+ const report = (over: Partial<PipelineFaceReport>): PipelineFaceReport => ({
381
+ "phase-spec": { closed: false, active: null, target: null },
382
+ plan: { closed: false, active: null, target: null },
383
+ wave: { closed: false, active: null, target: null },
384
+ branch: { closed: false, active: null, target: null },
385
+ ...over,
386
+ });
387
+ const tSpec = { type: "spec", id: "docs/kairos/specs/p-design.md" } as const;
388
+ const tPlan = {
389
+ type: "plan",
390
+ id: "docs/kairos/plans/p.md",
391
+ plan: "docs/kairos/plans/p.md",
392
+ } as const;
393
+
394
+ it("a face with an active C5 hop renders that hop (the in-flight work wins)", () => {
395
+ const next = NextStepRouter.walk(
396
+ report({
397
+ "phase-spec": { closed: true, active: null, target: tSpec },
398
+ plan: { closed: false, active: { kind: "review" }, target: tPlan },
399
+ }),
400
+ );
401
+ expect(next.route).toEqual({ kind: "review" });
402
+ expect(next.target).toEqual(tPlan);
403
+ });
404
+
405
+ it("the off-by-one D26 guard — a just-closed spec + an ABSENT plan hands off to the SPEC's exit", () => {
406
+ // The board's frontier is the plan face, but it was never entered (no doc). The
407
+ // retired fork used the frontier LINE's key → plan's exit (cdd-dev). The walk uses
408
+ // the PRECEDING entered face's exit → the spec's (cdd-plan).
409
+ const next = NextStepRouter.walk(
410
+ report({ "phase-spec": { closed: true, active: null, target: tSpec } }),
411
+ );
412
+ expect(next.route).toEqual({ kind: "handoff", entry: PIPELINE_NEXT["phase-spec"] });
413
+ expect(next.target).toEqual(tSpec);
414
+ });
415
+
416
+ it("a frontier ENTERED but drained (a present doc, no active hop) renders its OWN exit", () => {
417
+ const next = NextStepRouter.walk(
418
+ report({
419
+ "phase-spec": { closed: true, active: null, target: tSpec },
420
+ plan: { closed: false, active: null, target: tPlan },
421
+ }),
422
+ );
423
+ expect(next.route).toEqual({ kind: "handoff", entry: PIPELINE_NEXT.plan });
424
+ expect(next.target).toEqual(tPlan);
425
+ });
426
+
427
+ it("no preceding entered face → the FIRST face's exit (the pipeline entrance)", () => {
428
+ const next = NextStepRouter.walk(report({}));
429
+ expect(next.route).toEqual({ kind: "handoff", entry: PIPELINE_NEXT["phase-spec"] });
430
+ });
431
+
432
+ it("every face closed → the LAST entered face's exit (the pipeline terminus)", () => {
433
+ const next = NextStepRouter.walk(
434
+ report({
435
+ "phase-spec": { closed: true, active: null, target: tSpec },
436
+ plan: { closed: true, active: null, target: tPlan },
437
+ wave: { closed: true, active: null, target: { type: "wave", id: "1", plan: tPlan.plan } },
438
+ branch: {
439
+ closed: true,
440
+ active: null,
441
+ target: { type: "branch", id: "branch", plan: tPlan.plan },
442
+ },
443
+ }),
444
+ );
445
+ expect(next.route).toEqual({ kind: "handoff", entry: PIPELINE_NEXT.branch });
446
+ });
447
+
448
+ it("every face closed with nothing entered → the bare terminal `done`", () => {
449
+ expect(
450
+ NextStepRouter.walk(
451
+ report({
452
+ "phase-spec": { closed: true, active: null, target: null },
453
+ plan: { closed: true, active: null, target: null },
454
+ wave: { closed: true, active: null, target: null },
455
+ branch: { closed: true, active: null, target: null },
456
+ }),
457
+ ).route,
458
+ ).toEqual({ kind: "done" });
459
+ });
460
+ });