@oscaner-skills/cdd-engine 3.1.0 → 4.0.1

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.
@@ -48,6 +48,7 @@
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
  import { DISPATCH } from "../face/host.js";
51
+ import { TerminationPolicy } from "../face/termination.js";
51
52
  /** The nominal fixed-frame cells shared by every shell (byte-identical words — the
52
53
  * fixed prefix is read on every dispatch, so every word costs child context). */
53
54
  const FRAME_ITEMS = [
@@ -68,12 +69,14 @@ const LICENSE_ITEMS = [
68
69
  "- {{> cl:eof-newline}}",
69
70
  "- {{> cl:no-full-tree-find}}",
70
71
  "- {{> cl:bash-stall-limit}}",
72
+ "- {{> cl:no-infinite-loop}}",
71
73
  "- {{> cl:plan-freeze}}",
72
74
  "- {{> cl:atomic-commit}}",
73
75
  "- {{> cl:self-validate}}",
76
+ "- {{> cl:sync-completion}}",
74
77
  ];
75
78
  /** The `## Handoff schema` section — the injected writable-subset fence at every
76
- * shell's tail (the {{HANDOFF_SCHEMA}} slot; the face's sets differ per mode, so
79
+ * shell's tail (the {{HANDOFF_SCHEMA}} slot; the plane's sets differ per mode, so
77
80
  * the section's bytes are fixed per mode — §3.5 prefix-cache grouping). */
78
81
  const SCHEMA_SECTION = ["", "## Handoff schema", "", "{{HANDOFF_SCHEMA}}"];
79
82
  /** The implement row's fixed prefix — header + instructions + the shared work tail. */
@@ -83,7 +86,7 @@ const IMPLEMENT_SHELL = [
83
86
  "## Instructions",
84
87
  "",
85
88
  ...FRAME_ITEMS,
86
- `**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).`,
89
+ `**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 + the reason in \`notes\`) and \`artifacts\` (the prescribed \`OUTPUT_REPORT\`/\`OUTPUT_EVIDENCE\` paths from the round context — the \`{family}-{key}-\` canonical names, zero free naming).`,
87
90
  EVIDENCE_ITEM,
88
91
  ...LICENSE_ITEMS,
89
92
  ...SCHEMA_SECTION,
@@ -104,7 +107,7 @@ const FIX_SHELL = [
104
107
  "**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).",
105
108
  EVIDENCE_ITEM,
106
109
  ...LICENSE_ITEMS,
107
- // T5 (v0.3) — The delivery face's ONE strict-schema sentence: every top-level draft
110
+ // T5 (v0.3) — The work plane's ONE strict-schema sentence: every top-level draft
108
111
  // field comes from the `## Handoff schema` declared properties (the fields'
109
112
  // single source is the injected fence below — never a second enumeration in the
110
113
  // shell prose; a fix child that mirrors the source review carrier's top-level
@@ -114,27 +117,24 @@ const FIX_SHELL = [
114
117
  ...SCHEMA_SECTION,
115
118
  ];
116
119
  /** The docs-fix row's fixed prefix — header + instructions (no evidence — the
117
- * docs-fix face writes no evidence file). */
120
+ * docs-fix round writes no evidence file). */
118
121
  const DOCS_FIX_SHELL = [
119
122
  "# CDD dispatch — docs-fix round",
120
123
  "",
121
124
  "## Instructions",
122
125
  "",
123
126
  ...FRAME_ITEMS,
124
- "**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).",
127
+ "**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` and report the round in `status` (APPROVED once every finding is applied, else BLOCKED + the reason in `notes`). Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; retry = full re-run (idempotent).",
125
128
  ...LICENSE_ITEMS,
126
- // T5 (v0.3) — The findings face's ONE strict-schema sentence: same schema-first
127
- // directive as the work shell, naming the required `findings` (carried over from
128
- // the source review carrier verbatim — the required key is told how to fill, so
129
- // the sentence never contradicts the findings carrier's own required gate; the
130
- // work shell's field list is never copied here, and no field enumeration rides
131
- // the findings shell's prose either).
132
- "**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.",
129
+ // The generic strict-schema sentence — the SAME one the work shells carry: the
130
+ // injected declaration is the draft's single field source, zero per-mode field
131
+ // enumeration in the shell prose.
132
+ "**Draft fields:** every top-level field of the draft comes from the `## Handoff schema` declared `properties` — the declaration is the field source, zero extra keys.",
133
133
  ...SCHEMA_SECTION,
134
134
  ];
135
135
  /** The review variants' shared instruction text — the review's mode rule (the
136
136
  * criteria body + the lens vocabulary ride per-type fixed items below). */
137
- const REVIEW_ITEM = "**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.";
137
+ const REVIEW_ITEM = "**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`, and a face whose spec carries a `program:` also carries the parent charter at `INPUT_OVERALL`. 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. **Read-only:** never mutate tracked content, the index, HEAD, or branch state — the prescribed `OUTPUT_*` artifacts are a review's only writes, and committing belongs to the orchestrator — read history through `git show` / `git diff` / `git log`, and inspect another revision in a separate directory rather than moving HEAD here; repairs belong to the fix round, never to a review. **Single agent:** do the whole review yourself — never spawn a subagent for part of the diff or for a second opinion; this overrides any dispatched skill's parallel-sub-agent default.";
138
138
  /** The review mode's shared reduced tail — the only dynamic region of every review
139
139
  * variant (the criteria/lens are fixed-prefix per type, never here). Each review
140
140
  * type carries its own judged-doc referent (wave → `INPUT_WAVE_BRIEF`; plan/branch
@@ -148,6 +148,7 @@ const REVIEW_CONTEXT = [
148
148
  "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
149
149
  "- `INPUT_PLAN`: {{INPUT_PLAN}}",
150
150
  "- `INPUT_SPEC`: {{INPUT_SPEC}}",
151
+ "- `INPUT_OVERALL`: {{INPUT_OVERALL}}",
151
152
  "- `BASE_BRANCH`: {{BASE_BRANCH}}",
152
153
  "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
153
154
  "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
@@ -186,6 +187,7 @@ const MODE_PROMPTS = {
186
187
  "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
187
188
  "- `INPUT_PLAN`: {{INPUT_PLAN}}",
188
189
  "- `INPUT_SPEC`: {{INPUT_SPEC}}",
190
+ "- `INPUT_OVERALL`: {{INPUT_OVERALL}}",
189
191
  "- `INPUT_REVIEWS`: {{INPUT_REVIEWS}}",
190
192
  "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
191
193
  "- `OUTPUT_EVIDENCE`: {{OUTPUT_EVIDENCE}}",
@@ -204,6 +206,7 @@ const MODE_PROMPTS = {
204
206
  "- `WAVE`: {{WAVE}}",
205
207
  "- `INPUT_PLAN`: {{INPUT_PLAN}}",
206
208
  "- `INPUT_SPEC`: {{INPUT_SPEC}}",
209
+ "- `INPUT_OVERALL`: {{INPUT_OVERALL}}",
207
210
  "- `INPUT_REVIEWS`: {{INPUT_REVIEWS}}",
208
211
  "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
209
212
  "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
@@ -218,15 +221,15 @@ const MODE_PROMPTS = {
218
221
  export const REVIEWS = {
219
222
  wave: {
220
223
  lensEnum: ["standards", "spec", "buildability"],
221
- axesGuide: "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.",
224
+ axesGuide: "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).",
222
225
  },
223
226
  branch: {
224
227
  lensEnum: ["standards", "spec", "buildability"],
225
- axesGuide: "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).",
228
+ axesGuide: "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). Three things a green run cannot show you: design — does the changed structure fit this codebase and is it the simplest structure that solves the plan's problem (over-engineering is a finding, not a preference); test adequacy — would these tests fail if the code broke (a run that cannot go red is not evidence); migration — does every breaking change name the path a not-yet-migrated consumer takes.",
226
229
  },
227
230
  spec: {
228
231
  lensEnum: ["completeness", "consistency", "clarity"],
229
- axesGuide: "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).",
232
+ axesGuide: "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 + program conformance — judge the phase against its parent overall at `INPUT_OVERALL` (the charter its `program:` names): the phase must sit inside the scope the overall's Phase inventory registered for it, and a phase that reaches beyond it is a completeness 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).",
230
233
  },
231
234
  plan: {
232
235
  lensEnum: ["completeness", "decomposition", "buildability"],
@@ -337,6 +340,7 @@ const TOKENS = [
337
340
  { name: "HANDOFF_SCHEMA", zone: "shell" },
338
341
  { name: "INPUT_PLAN", zone: "round-context" },
339
342
  { name: "INPUT_SPEC", zone: "round-context" },
343
+ { name: "INPUT_OVERALL", zone: "round-context" },
340
344
  { name: "INPUT_REVIEWS", zone: "round-context" },
341
345
  { name: "INPUT_WAVE_BRIEF", zone: "round-context" },
342
346
  // find #5 — the prescribed artifact write paths (the {family}-{key}-{artifact}
@@ -355,19 +359,40 @@ export const CLAUSES = {
355
359
  "cl:english-comments": "Write code comments and shipped prose in English only — English-primary (no other-language comment blocks, no translated mirrors).",
356
360
  "cl:eof-newline": "Every text file must end with exactly one newline (EOF newline): no missing final newline and no trailing blank lines.",
357
361
  "cl:no-full-tree-find": "Never run an unbounded full-tree `find` over a large directory and never bare-read a large file — constrain to explicit paths with `maxdepth`/`-path`, or read only the needed range.",
358
- "cl:bash-stall-limit": "If a Bash command stalls without progress for more than 10 minutes, terminate it and substitute an equivalent, lighter command.",
362
+ "cl:bash-stall-limit": `Put a \`timeout\` on every Bash command — no single invocation may run longer than ${TerminationPolicy.CHILD_BASH_TIMEOUT_MS / 60_000} minutes; a command that stalls without progress is terminated and replaced with an equivalent, lighter command.`,
363
+ "cl:no-infinite-loop": "Never run an unbounded loop — no `while True: pass`, no `while true; do …; done`, no spin-wait or tail-follow that only a human can stop. A wait must carry a bounded exit condition (a timeout, a max-attempt counter, or a terminating predicate) that ends the loop on its own.",
359
364
  "cl:plan-freeze": "Approved plan/spec files are frozen — zero modification authority; any change needed is reported to the orchestrator through findings, never edited in place.",
360
365
  "cl:atomic-commit": "Commit each round's change as one atomic conventional commit scoped to the round — no mixed or out-of-scope content, no AI-generation trailers.",
361
366
  "cl:self-validate": "Self-validate before returning: run the validation/checks your change requires and record the evidence (command + exit code + result) in the report.",
367
+ "cl:sync-completion": "This dispatch is one-shot and non-interactive: end your turn with anything still running and the process exits — the work and the handoff die with it. So do not end your turn — a background command, a background subagent, or any yield-and-wait path such as `bg_run` / `bg_delegate` — before the handoff draft is written. Finish nested work in this same turn: complete it synchronously in this process turn, then write the handoff and finish.",
362
368
  };
363
- /** The dispatch-prompt data plane — the typed template-contract surface. $version 9
364
- * is the kind-named doc-anchor shape (INPUT_PLAN / INPUT_SPEC replace the generic
365
- * INPUT_DOC; INPUT_WAVE_BRIEF), the branch scope anchor BASE_BRANCH, the single
369
+ /** The dispatch-prompt data plane — the typed template-contract surface. $version 16
370
+ * unifies the handoff carrier on one op-derived plane (work / judge — implement /
371
+ * fix author a status-bearing work carrier, review a findings-only judge carrier)
372
+ * and gives the docs-fix round a `status` to report its outcome in. $version 15
373
+ * carries the `INPUT_OVERALL` read face (the parent charter a spec's `program:`
374
+ * names, mirroring `INPUT_SPEC` — a face without `program:` drops the slot) and
375
+ * adds the spec axis's program-scope conformance criterion (the phase judged against
376
+ * the scope its charter's Phase inventory registered for it). $version 14
377
+ * rewrites the sync-completion clause to name the one-shot fact (ending your turn with
378
+ * work still running exits the process — the work and the handoff die with it) and the
379
+ * subagent class (a background subagent is a yield-and-wait path, exactly like a
380
+ * background command; `bg_run` / `bg_delegate` were the only names before). $version 13
381
+ * adds the two hard review disciplines (read-only — a review mutates no tracked
382
+ * content, index, HEAD, or branch state; single agent — a review never spawns a
383
+ * subagent) and the branch axis's three judgment points (design · test adequacy ·
384
+ * migration). $version 12 adds the bounded-loop discipline clause (no `while True: pass` /
385
+ * spin-wait — every wait carries its own terminating condition). $version 11 makes the Bash discipline
386
+ * clause a hard per-command ceiling (every Bash run carries a `timeout`, no invocation
387
+ * longer than `CHILD_BASH_TIMEOUT_MS`). $version 10 adds the sync-completion discipline
388
+ * clause (P14 — one-shot CDD children must finish nested work in-process before writing
389
+ * the handoff; no bg_run / bg_delegate yield).
390
+ * $version 9 was the kind-named doc-anchor shape (INPUT_PLAN / INPUT_SPEC replace the
391
+ * generic INPUT_DOC; INPUT_WAVE_BRIEF), the branch scope anchor BASE_BRANCH, the single
366
392
  * prose return contract (`RETURN_PROSE` — nothing downstream parses the child's
367
- * stdout), and the per-type review criterion shells. The bump from 8 marks the
368
- * return-shape change (the two-line key-value block retired). */
393
+ * stdout), and the per-type review criterion shells. */
369
394
  export const TEMPLATE_PROMPT = {
370
- $version: 9,
395
+ $version: 16,
371
396
  modes: MODE_PROMPTS,
372
397
  reviews: REVIEW_VARIANTS,
373
398
  return: RETURN_ZONE,
@@ -1,17 +1,17 @@
1
1
  // packages/cdd-engine/src-next/session/handoff-schema.ts
2
- // T15 v1.9 — the handoff schema face (design spec §3.6): the child's writable handoff
3
- // contract as ONE typed declaration with TWO projections. The cutover deleted the old
2
+ // The handoff schema face: the child's writable handoff contract as ONE typed
3
+ // declaration projected onto the two carrier planes. The cutover deleted the old
4
4
  // JSON schema file together with its Ajv loader; the structural constraint now lives
5
5
  // here as a typed declaration — zero JSON schema files, one source, two consumers:
6
6
  //
7
7
  // · projections: ① the prompt-injection text (schemaText — the ```json fences
8
- // byte-fixed per face, so the fixed prefix tail of the dispatch prompt stays
8
+ // byte-fixed per plane, so the fixed prefix tail of the dispatch prompt stays
9
9
  // cache-friendly) and ② the engine read-back validator (violations /
10
10
  // evidenceViolations — the child draft is validated against exactly the same
11
- // declared objects the prompt showed it).
12
- // · faces: the per-family `schema` field of the handoff families (infra/runtime.ts)
13
- // selects the face — `delivery` (implement/fix: status+artifacts, plus the separate
14
- // test-evidence file for task-family rounds) or `findings` (reviews: findings-only
11
+ // projected objects the prompt showed it).
12
+ // · planes: the carrier plane is DERIVED from the op (planeOf), never declared per
13
+ // family — `work` (implement/fix: status + artifacts, plus the separate
14
+ // test-evidence file for task-family rounds) or `judge` (reviews: findings-only
15
15
  // carrier — the engine rolls the status up from the findings, never a
16
16
  // child-authored status).
17
17
  //
@@ -26,7 +26,7 @@
26
26
  //
27
27
  // Module-level exports are types / the declared schema objects / the class — zero
28
28
  // behavior-carrying bare functions (the plan's zero-bare-function discipline).
29
- /** One finding row — the shared base declaration of the findings face (severity +
29
+ /** One finding row — the shared base declaration of the judge plane (severity +
30
30
  * lens + summary required; the extra review columns — section / line / fix — are
31
31
  * declared optional, and unknown extra fields ride along). */
32
32
  const FINDING = {
@@ -41,40 +41,42 @@ const FINDING = {
41
41
  fix: { type: "string" },
42
42
  },
43
43
  };
44
- /** The `delivery` writable subset — implement/fix carrier. `status` and `artifacts` are
45
- * the round's required core; notes rides the declared optional field. Reserved
44
+ /** The ONE carrier declaration — the four child-writable slots. DECLARATION ORDER IS
45
+ * PROJECTION ORDER: `#writable(plane)` filters these properties in this order, so the
46
+ * judge fence keeps its `findings` · `artifacts` · `notes` byte order. Reserved
46
47
  * fields (phase · tasks) are NOT declared and are DROPPED by materialize (never a
47
48
  * BLOCK) — the engine stays the carrier's single author.
48
- * `as const` preserves the literal property keys — the carrier type family
49
- * (`CarrierOf<F>` below) derives its field set FROM these declared keys. */
50
- const CARRIER_DELIVERY = {
49
+ * `as const` preserves the literal property keys — the `Carrier` type family below
50
+ * derives its field set FROM these declared keys. */
51
+ const CARRIER = {
51
52
  type: "object",
52
- required: ["status", "artifacts"],
53
53
  properties: {
54
54
  status: { type: "string", enum: ["APPROVED", "BLOCKED"] },
55
- failure_category: { type: "string" },
56
- artifacts: { type: "object" },
57
- notes: { type: "array", items: { type: "string" } },
58
- },
59
- };
60
- /** The `findings` writable subset — review + docs-fix carrier. NO status: the
61
- * conclusion is derived from the findings at judgment time
62
- * (`conclusionOf("findings", carrier)` → `rollup(findings)`), never a carrier field
63
- * the child authors or the engine persists — the declaration plane IS the writable
64
- * plane (one face, one field set). `as const` — see CARRIER_DELIVERY. */
65
- const CARRIER_FINDINGS = {
66
- type: "object",
67
- required: ["findings"],
68
- properties: {
69
55
  findings: { type: "array", items: FINDING },
70
56
  artifacts: { type: "object" },
71
57
  notes: { type: "array", items: { type: "string" } },
72
58
  },
73
59
  };
60
+ /** The plane → writable slot table — the ONE projection source (`#writable`) the
61
+ * prompt fence, the read-back validator and the dropped-key walk all read. The
62
+ * shared slots (artifacts · notes) are both-plane by design; the exclusive slot IS
63
+ * the plane (`status` for work, `findings` for judge). */
64
+ const PLANE_SLOTS = {
65
+ work: ["status", "artifacts", "notes"],
66
+ judge: ["findings", "artifacts", "notes"],
67
+ };
68
+ /** The plane → required slot table. The work plane's round conclusion is the child's
69
+ * own declared status, so status + artifacts are the required core. The judge plane
70
+ * requires the findings its conclusion rolls up from; artifacts / notes ride as
71
+ * declared optional slots (a review writes only what it has). */
72
+ const PLANE_REQUIRED = {
73
+ work: ["status", "artifacts"],
74
+ judge: ["findings"],
75
+ };
74
76
  /** The test-evidence file schema — the evidence gate's engine read-back contract
75
77
  * (the second fix for a prose-only claim: the old prompt asserted an engine read-back
76
- * that the engine never performed; now both projections are real). A task-family
77
- * work round missing or violating this file rewrites the round to BLOCKED. */
78
+ * that the engine never performed; now both projections are real). A work-plane wave /
79
+ * branch round missing or violating this file rewrites the round to BLOCKED. */
78
80
  const EVIDENCE = {
79
81
  type: "object",
80
82
  required: ["command", "exit_code", "passed", "warnings_count", "typecheck"],
@@ -95,30 +97,28 @@ const EVIDENCE = {
95
97
  behavior_change: { type: "boolean" },
96
98
  },
97
99
  };
98
- /** The face → declared writable-subset table (the single source both projections read).
99
- * `as const` keeps the declarations' literal property keys visible — the carrier type
100
- * family's `[K in keyof (typeof BY_FACE)[F]["properties"]]` derives its field set from
101
- * exactly these tables, so a schema edit reshapes the carrier types by construction. */
102
- const BY_FACE = {
103
- delivery: CARRIER_DELIVERY,
104
- findings: CARRIER_FINDINGS,
105
- };
106
100
  /**
107
- * HandoffSchema — one declaration, two projections. `violations(face, value)` is
101
+ * HandoffSchema — one declaration, two projections. `violations(plane, value)` is
108
102
  * the read-back validator (projection ② — the engine's seat, session plane);
109
- * `schemaText(face, evidence)` is the injected prompt text (projection ① — fixed
110
- * prefix tail, byte-stable per face so the dispatch prompt stays cache-friendly).
103
+ * `schemaText(plane, evidence)` is the injected prompt text (projection ① — fixed
104
+ * prefix tail, byte-stable per plane so the dispatch prompt stays cache-friendly).
111
105
  * `rollup(findings)` derives the review conclusion the old JSON face rolled up.
112
106
  */
113
107
  export class HandoffSchema {
114
- /** Projection ① — the `## Handoff schema` section text: the face's writable
115
- * subset in a ```json fence + (delivery faces) the evidence file's schema in a second
116
- * fence. The text is byte-stable per (face, evidence, prefix) — the fixed bytes
108
+ /** The carrier plane of an op — the ONE derivation, never a per-family declaration.
109
+ * implement / fix author a work carrier (status + artifacts); review authors a
110
+ * judge carrier (findings — conclusion rolled up). */
111
+ static planeOf(op) {
112
+ return op === "review" ? "judge" : "work";
113
+ }
114
+ /** Projection ① — the `## Handoff schema` section text: the plane's writable
115
+ * subset in a ```json fence + (work plane) the evidence file's schema in a second
116
+ * fence. The text is byte-stable per (plane, evidence, prefix) — the fixed bytes
117
117
  * of the dispatch prompt's contract surface. The evidence prefix is the family
118
118
  * spine (§3.7 naming: `tasks-` for the task families, `branch-` for the branch
119
119
  * fix — a branch evidence file never carries the misleading tasks- prefix). */
120
- schemaText(face, evidence, evidencePrefix = "tasks") {
121
- const carrier = this.#json(BY_FACE[face]);
120
+ schemaText(plane, evidence, evidencePrefix = "tasks") {
121
+ const carrier = this.#json(this.#writable(plane));
122
122
  let text = `Write the handoff draft at \`OUTPUT_HANDOFF\` per this writable subset — the engine validates it, then materializes the final carrier in place; fields not listed here are engine-reserved, do not write them.\n\n\`\`\`json\n${carrier}\n\`\`\``;
123
123
  if (evidence) {
124
124
  text += `\n\nThe evidence file (\`${evidencePrefix}-{key}-test-evidence.json\` under \`WORKSPACE_DIR\`) must comply with this schema — the engine reads it back with the same stakes:\n\n\`\`\`json\n${this.#json(EVIDENCE)}\n\`\`\``;
@@ -129,15 +129,15 @@ export class HandoffSchema {
129
129
  evidenceSchemaText() {
130
130
  return this.#json(EVIDENCE);
131
131
  }
132
- /** Projection ② — validate a child draft against a face's writable subset. Every
132
+ /** Projection ② — validate a child draft against a plane's writable subset. Every
133
133
  * problem is a read-back BLOCK; the draft is left untouched for the child's
134
134
  * resume (never overwritten — the engine never clobbers a child's work). */
135
- violations(face, value) {
135
+ violations(plane, value) {
136
136
  const problems = [];
137
- this.#check(BY_FACE[face], value, "", problems);
137
+ this.#check(this.#writable(plane), value, "", problems);
138
138
  return problems.map((problem) => problem.path.length === 0 ? problem.reason : `${problem.path}: ${problem.reason}`);
139
139
  }
140
- /** Projection ② — validate the test-evidence file (task-family work rounds). */
140
+ /** Projection ② — validate the test-evidence file (work-plane wave / branch rounds). */
141
141
  evidenceViolations(value) {
142
142
  if (value === null || value === undefined)
143
143
  return ["the evidence file is missing"];
@@ -145,26 +145,26 @@ export class HandoffSchema {
145
145
  this.#check(EVIDENCE, value, "", problems);
146
146
  return problems.map((problem) => problem.path.length === 0 ? problem.reason : `${problem.path}: ${problem.reason}`);
147
147
  }
148
- /** The round conclusion, DERIVED at judgment time from the face's own plane — the
149
- * single source the review/fix ledger legs read (D27 · judgment face ⊥ input face).
150
- * The findings face rolls its conclusion UP from its findings (defined for every
148
+ /** The round conclusion, DERIVED at judgment time from the plane — the single
149
+ * source the review/fix ledger legs read (D27 · judgment face ⊥ input face).
150
+ * The judge plane rolls its conclusion UP from its findings (defined for every
151
151
  * carrier — a review never carries a child-authored status, and the persisted
152
- * findings carrier holds none). The delivery face reads its DECLARED status, and the
152
+ * findings carrier holds none). The work plane reads its DECLARED status, and the
153
153
  * absence of a declaration is itself a fact: an ABSENT status → `undefined` (no
154
154
  * conclusion was declared — never an invented approval OR an invented failure ·
155
155
  * D27 present-facts-only), while a PRESENT-but-invalid byte (outside the enum the
156
156
  * schema pinned) degrades to BLOCKED — the conservative reading of a malformed
157
157
  * declaration. `undefined` is DISTINCT from BLOCKED to the caller (the router
158
158
  * treats undefined as "not a failure", a declared BLOCKED as the failure face), so
159
- * a delivery carrier that predates the status field never reads as a fabricated
159
+ * a work carrier that predates the status field never reads as a fabricated
160
160
  * failure. `carrier` is the on-disk carrier (or a freshly built one) — the
161
- * conclusion is never a stored field, so any face's carrier derives it the same way. */
162
- conclusionOf(face, carrier) {
163
- if (face === "findings") {
161
+ * conclusion is never a stored field, so any plane's carrier derives it the same way. */
162
+ conclusionOf(plane, carrier) {
163
+ if (plane === "judge") {
164
164
  const findings = Array.isArray(carrier.findings) ? carrier.findings : [];
165
165
  return this.rollup(findings);
166
166
  }
167
- // The delivery face reads its DECLARED status. Absent → undefined (no declaration);
167
+ // The work plane reads its DECLARED status. Absent → undefined (no declaration);
168
168
  // present-but-invalid → BLOCKED (a declared conclusion that is malformed is a
169
169
  // failure signal, never silently approved). This is the ONE ruling for a work
170
170
  // status: the reconstruct's work leg delegates here, so the read-back and the
@@ -199,23 +199,36 @@ export class HandoffSchema {
199
199
  }
200
200
  return rows;
201
201
  }
202
- /** The declared schema object of a face — the single-source introspection of this
203
- * module's reparametrized `HandoffFamily.schema` value. */
204
- faceSchema(face) {
205
- return BY_FACE[face];
202
+ /** The plane's writable subset — the ONE projection every consumer reads (prompt
203
+ * fence · read-back validator · dropped-key walk). The properties are CARRIER's
204
+ * own slot declarations filtered in declaration order; the required set comes from
205
+ * the plane table — zero second declaration. */
206
+ planeSchema(plane) {
207
+ return this.#writable(plane);
206
208
  }
207
- /** The draft keys materialize drops — every key the face does not declare as a
208
- * child-writable `properties` slot (extra child fields such as a findings-draft
209
- * `status`). The read-back validator judges these the same way (drop, never a
209
+ /** The draft keys materialize drops — every key the plane does not declare as a
210
+ * child-writable `properties` slot (extra child fields such as a work draft
211
+ * `findings`). The read-back validator judges these the same way (drop, never a
210
212
  * BLOCK) — materialize surfaces them as the single §8.7 WARN on the carrier's
211
213
  * notes. A non-object draft drops nothing here (its shape is the validator's
212
214
  * semantic refusal). */
213
- droppedKeys(face, value) {
215
+ droppedKeys(plane, value) {
214
216
  if (typeof value !== "object" || value === null || Array.isArray(value))
215
217
  return [];
216
- const declared = new Set(Object.keys(BY_FACE[face].properties ?? {}));
218
+ const declared = new Set(Object.keys(this.#writable(plane).properties ?? {}));
217
219
  return Object.keys(value).filter((key) => !declared.has(key));
218
220
  }
221
+ /** The plane's writable subset — CARRIER's declared slots filtered to the plane's
222
+ * writable set (declaration order preserved) + the plane's required slots. */
223
+ #writable(plane) {
224
+ const slots = PLANE_SLOTS[plane];
225
+ const properties = {};
226
+ for (const [key, node] of Object.entries(CARRIER.properties)) {
227
+ if (slots.includes(key))
228
+ properties[key] = node;
229
+ }
230
+ return { type: "object", required: [...PLANE_REQUIRED[plane]], properties };
231
+ }
219
232
  /** Serialize a declared schema object into the prompt's fence — COMPACT (no pretty
220
233
  * indent: the injected text is the per-mode fixed prefix's biggest token cost, and
221
234
  * every dispatch pays it in the child context — minify keeps the round cheap). The
@@ -245,11 +258,10 @@ export class HandoffSchema {
245
258
  if (obj[key] !== undefined)
246
259
  this.#check(sub, obj[key], this.#at(path, key), problems);
247
260
  }
248
- // Non-declared keys (extra child fields such as a findings-draft
249
- // `status`) are DROPPED by materialize, never a BLOCK — the validator
250
- // and materialize judge the same field the same way (§8.7). Only
251
- // semantic errors on declared fields (required / type / enum / length)
252
- // refuse the draft.
261
+ // Non-declared keys (extra child fields such as a work-draft `findings`) are
262
+ // DROPPED by materialize, never a BLOCK — the validator and materialize judge
263
+ // the same field the same way (§8.7). Only semantic errors on declared fields
264
+ // (required / type / enum / length) refuse the draft.
253
265
  return;
254
266
  }
255
267
  if (node.type === "array") {
@@ -25,7 +25,7 @@ import { createHash } from "node:crypto";
25
25
  import { readFileSync } from "node:fs";
26
26
  import { BriefRenderer } from "../render/brief.js";
27
27
  import { targetFaces } from "./faces.js";
28
- import { HandoffSchema, } from "./handoff-schema.js";
28
+ import { HandoffSchema } from "./handoff-schema.js";
29
29
  import { NextStepRouter } from "./next.js";
30
30
  import { EMPTY_RUN_STATE } from "./run.js";
31
31
  // ---------------------------------------------------------------------------
@@ -93,7 +93,7 @@ export class Ledger {
93
93
  * the `closedWaves()` read face and the wave gate share the same router). */
94
94
  #router = new NextStepRouter();
95
95
  /** The handoff-schema face — the conclusion single source (`conclusionOf`), one
96
- * instance per ledger (the round verdict derives from the face's own plane at
96
+ * instance per ledger (the round verdict derives from the op's carrier plane at
97
97
  * judgment time · D27). */
98
98
  #handoffSchema = new HandoffSchema();
99
99
  /** The review-reference face (T25) — the refKind classification + the same-ref
@@ -446,6 +446,15 @@ export class Ledger {
446
446
  this.writeProgress(data);
447
447
  return data.timeoutCount;
448
448
  }
449
+ /** Increment the contract-violation counter — the read-back write point (one
450
+ * `handoff-absent` or `contract-violation` crash lands, the count goes up by
451
+ * one). The counter's only writer. */
452
+ incrementContractViolationCount() {
453
+ const data = this.readProgress() ?? this.emptyProgress();
454
+ data.contractViolationCount += 1;
455
+ this.writeProgress(data);
456
+ return data.contractViolationCount;
457
+ }
449
458
  // -------------------------------------------------------------------------
450
459
  // closedWaves — the closure single read face (v1.20)
451
460
  // -------------------------------------------------------------------------
@@ -583,12 +592,12 @@ export class Ledger {
583
592
  throw new Error(`unknown handoff family: ${op}.${type}`);
584
593
  return family;
585
594
  }
586
- /** The handoff FACE of an op/type pair — the family's `schema` selector (work when
587
- * the family declares none). The face-aware read/write/bookkeep spine (T2): a
588
- * findings-face round rides the findings writable subset, a delivery-face round rides
589
- * the findings-free work subset — never the caller's guess. */
590
- handoffFaceOf(op, type) {
591
- return this.#family(op, type).schema ?? "delivery";
595
+ /** The carrier PLANE of an op — the ONE op-derived derivation (`HandoffSchema.planeOf`).
596
+ * The plane-aware read/write/bookkeep spine: a judge-plane round (review) rides the
597
+ * findings writable subset, a work-plane round (implement / fix) rides the
598
+ * status-bearing work subset — never the caller's guess, never a per-family declaration. */
599
+ planeOf(op) {
600
+ return HandoffSchema.planeOf(op);
592
601
  }
593
602
  /** The canonical handoff file name — the family's `{placeholder}` pattern, filled. */
594
603
  handoffName(op, type, params = {}) {
@@ -600,9 +609,9 @@ export class Ledger {
600
609
  handoffPath(op, type, params = {}) {
601
610
  return this.#workspace.resolve(this.handoffName(op, type, params));
602
611
  }
603
- buildHandoff(face, init = {}) {
612
+ buildHandoff(plane, init = {}) {
604
613
  const carrier = { artifacts: init.artifacts ?? {} };
605
- if (face === "findings" || init.findings !== undefined)
614
+ if (plane === "judge" || init.findings !== undefined)
606
615
  carrier.findings = init.findings;
607
616
  return carrier;
608
617
  }
@@ -729,9 +738,9 @@ export class Ledger {
729
738
  return {
730
739
  phase: "review",
731
740
  // The conclusion is DERIVED from the review carrier's own findings at judgment
732
- // time (D27 · the findings carrier holds no status field) — the single source
733
- // shared with the fix leg below (`HandoffSchema.conclusionOf`).
734
- status: this.#handoffSchema.conclusionOf("findings", carrier),
741
+ // time (D27 · the judge-plane carrier holds no status field) — the single
742
+ // source shared with the fix leg below (`HandoffSchema.conclusionOf`).
743
+ status: this.#handoffSchema.conclusionOf("judge", carrier),
735
744
  findings: this.#findingsOf(carrier),
736
745
  reviewsPath: this.handoffPath("review", type, reviewParams),
737
746
  consecutiveS1: this.#consecutiveS1Run(type, params, round),
@@ -750,9 +759,8 @@ export class Ledger {
750
759
  return {
751
760
  phase: "fix",
752
761
  // The fix round's conclusion derives from ITS OWN carrier's declared plane (the
753
- // delivery face reads its status; a docs-fix findings face rolls its findings up) —
754
- // the same `conclusionOf` single source (D27).
755
- status: this.#handoffSchema.conclusionOf(this.handoffFaceOf("fix", type), fixCarrier),
762
+ // work plane reads its status) — the same `conclusionOf` single source (D27).
763
+ status: this.#handoffSchema.conclusionOf(this.planeOf("fix"), fixCarrier),
756
764
  findings: this.#findingsOf(reviewCarrier),
757
765
  reviewsPath: this.handoffPath("review", type, reviewParams),
758
766
  consecutiveS1: this.#consecutiveS1Run(type, params, round),
@@ -53,7 +53,7 @@ export const ROUTE_DECISION_WORDS = ["done", "next-wave", "review", "fix", "soft
53
53
  * frame's plan fact. */
54
54
  export const PIPELINE_NEXT = {
55
55
  "phase-spec": { kind: "ref", ref: "kairos:cdd-plan" },
56
- "overall-spec": { kind: "done" },
56
+ overall: { kind: "done" },
57
57
  plan: { kind: "ref", ref: "kairos:cdd-dev" },
58
58
  wave: { kind: "literal", literal: "review --type branch --plan <plan>" },
59
59
  branch: { kind: "ref", ref: "kairos:cdd-close" },