@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
@@ -10,6 +10,7 @@
10
10
 
11
11
  import { describe, expect, it } from "vitest";
12
12
  import { Translator } from "../../contract/translate.ts";
13
+ import { DISPATCH } from "../../face/host.ts";
13
14
  import { Words } from "../../face/words.ts";
14
15
  import { BriefRenderer } from "../brief.ts";
15
16
  import { IssueBodyRenderer, type IssueReportInput } from "../issue-body.ts";
@@ -24,8 +25,9 @@ const ALL_VALUES: Record<string, string> = {
24
25
  ROLE: "implement",
25
26
  WAVE: "4,12",
26
27
  INPUT_WAVE_BRIEF: "/ws/tasks-4,12-brief.md",
27
- INPUT_FINDINGS: "",
28
- INPUT_DOC: "",
28
+ INPUT_REVIEWS: "",
29
+ INPUT_PLAN: "",
30
+ INPUT_SPEC: "",
29
31
  BASE_BRANCH: "",
30
32
  OUTPUT_REPORT: "/ws/tasks-4,12-implement-report.md",
31
33
  OUTPUT_EVIDENCE: "/ws/tasks-4,12-test-evidence.json",
@@ -43,16 +45,16 @@ describe("TemplateAssembler — the template assembly + hard gates", () => {
43
45
  // v1.8 — the mode dispatch table; v1.9 — RETURN_JSON / DOCS_FIX retired; the
44
46
  // review criteria/lens tokens are gone (§3.7).
45
47
  expect(assembler.workModes()).toEqual(["implement", "fix", "review", "docs-fix"]);
46
- expect(assembler.returnFormats()).toEqual(["RETURN_STDOUT_BLOCK"]);
47
48
  expect(assembler.declaredTokens()).toContain("ROLE");
48
49
  expect(assembler.declaredTokens()).toContain("OUTPUT_HANDOFF");
49
50
  expect(assembler.declaredTokens()).toContain("OUTPUT_REPORT");
50
51
  expect(assembler.declaredTokens()).toContain("OUTPUT_EVIDENCE");
51
52
  expect(assembler.declaredTokens()).toContain("BASE_BRANCH");
52
53
  expect(assembler.declaredTokens()).toContain("HANDOFF_SCHEMA");
53
- // the retired reference tokens — the range/plan/brief range tokens are gone
54
+ // the retired reference tokens — the range/brief tokens are gone; INPUT_PLAN is
55
+ // resurrected as the semantic plan-doc anchor (the kind-named round context)
54
56
  expect(assembler.declaredTokens()).not.toContain("INPUT_RANGE");
55
- expect(assembler.declaredTokens()).not.toContain("INPUT_PLAN");
57
+ expect(assembler.declaredTokens()).toContain("INPUT_PLAN");
56
58
  expect(assembler.declaredTokens()).not.toContain("FIX_BASE");
57
59
  expect(assembler.declaredTokens()).not.toContain("OUTPUT_BRIEF");
58
60
  expect(assembler.declaredTokens()).not.toContain("INPUT_CRITERIA");
@@ -61,23 +63,26 @@ describe("TemplateAssembler — the template assembly + hard gates", () => {
61
63
  expect(assembler.declaredTokens()).not.toContain("INPUT_RULES");
62
64
  });
63
65
 
64
- it("renders the two-line return contract — exactly status + artifacts, the commits line retired (§2.4)", () => {
65
- // The `## Return` zone prescribes exactly two command lines inside its fence:
66
- // `status:` then `artifacts:`. The retired `commits:` line must not survive
67
- // anywhere in the assembled prompt (the child returns status + artifacts; the
68
- // engine appends the counters/next lines — never the child's).
66
+ it("renders the single prose return contract — the retired status/artifacts key block is gone (§2.4)", () => {
67
+ // P11 §2.1: the `## Return` zone is ONE plain-prose contract block — the child
68
+ // narrates the round in prose and nothing downstream parses its stdout (the
69
+ // handoff draft at OUTPUT_HANDOFF is the machine-readable result). The retired
70
+ // two-line key block (`status:` / `artifacts:` inside a fence) must not survive
71
+ // anywhere in the assembled prompt.
69
72
  const out = assembler.render(ALL_VALUES);
70
- const fence = out.split("```")[1];
71
- expect(fence).toBeDefined();
72
- const commandLines = fence!
73
- .split("\n")
74
- .map((line) => line.trim())
75
- .filter((line) => line.length > 0);
76
- expect(commandLines).toEqual([
77
- "status: <APPROVED|BLOCKED>",
78
- "artifacts: report=<path> test_evidence=<path>",
79
- ]);
73
+ const returnZone = out.split("## Return")[1];
74
+ expect(returnZone).toBeDefined();
75
+ // the prose contract is present, byte-anchored on the RETURN_PROSE zone
76
+ expect(returnZone).toContain(
77
+ "Report in a few plain sentences what this round did, whether it succeeded",
78
+ );
79
+ expect(returnZone).toContain("`OUTPUT_HANDOFF` is the round's machine-readable result");
80
+ expect(returnZone).toContain("Do not emit key-value lines");
81
+ // zero key-value residue — no fenced command block, no `status:`/`artifacts:` line
82
+ expect(out).not.toContain("```");
80
83
  expect(out).not.toContain("commits:");
84
+ expect(out).not.toMatch(/^status: /m);
85
+ expect(out).not.toMatch(/^artifacts: /m);
81
86
  });
82
87
 
83
88
  it("assembles the implement mode — the fixed prefix + the reduced round context", () => {
@@ -106,20 +111,24 @@ describe("TemplateAssembler — the template assembly + hard gates", () => {
106
111
  expect(out).not.toContain("DOCS_FIX");
107
112
  // the per-mode trimming: an implement round's context carries no review/fix keys
108
113
  expect(out).not.toContain("INPUT_CRITERIA");
109
- expect(out).not.toContain("INPUT_FINDINGS");
114
+ expect(out).not.toContain("INPUT_REVIEWS");
110
115
  expect(out).not.toContain("FIX_BASE");
111
116
  expect(out).not.toContain("BASE_BRANCH");
117
+ // ⑫ the implement dispatch ref is the DISPATCH single source — the rendered
118
+ // shell carries DISPATCH.implement's value (zero drift pin; the literal lives
119
+ // ONLY in the DISPATCH table, never re-spelled in the template prose).
120
+ expect(out).toContain(DISPATCH.implement);
112
121
  });
113
122
 
114
123
  it("renders the docs-fix mode through the same table — its own rules + subset", () => {
115
124
  const out = assembler.render({
116
125
  ...ALL_VALUES,
117
126
  ROLE: "docs-fix",
118
- INPUT_DOC: "docs/x-design.md",
127
+ INPUT_SPEC: "docs/x-design.md",
119
128
  });
120
129
  expect(out.startsWith("# CDD dispatch — docs-fix round")).toBe(true);
121
- expect(out).toContain("apply `INPUT_FINDINGS` (all severities) directly to `INPUT_DOC`");
122
- expect(out).toContain("- `INPUT_DOC`: docs/x-design.md");
130
+ expect(out).toContain("apply `INPUT_REVIEWS` (all severities) directly to the judged doc");
131
+ expect(out).toContain("- `INPUT_SPEC`: docs/x-design.md");
123
132
  expect(out).not.toContain("BASE_BRANCH");
124
133
  // the review-only keys stay out of the docs-fix context
125
134
  expect(out).not.toContain("INPUT_CRITERIA");
@@ -129,7 +138,7 @@ describe("TemplateAssembler — the template assembly + hard gates", () => {
129
138
  const out = assembler.render({
130
139
  ...ALL_VALUES,
131
140
  ROLE: "fix",
132
- INPUT_FINDINGS: "/ws/tasks-1-review-1.json",
141
+ INPUT_REVIEWS: "/ws/tasks-1-review-1.json",
133
142
  });
134
143
  expect(out.startsWith("# CDD dispatch — fix round")).toBe(true);
135
144
  // verify-then-apply — the receiving-code-review core: VERIFY each finding
@@ -145,7 +154,7 @@ describe("TemplateAssembler — the template assembly + hard gates", () => {
145
154
  const out = assembler.render({
146
155
  ...ALL_VALUES,
147
156
  ROLE: "fix",
148
- INPUT_FINDINGS: "/ws/tasks-1-review-1.json",
157
+ INPUT_REVIEWS: "/ws/tasks-1-review-1.json",
149
158
  });
150
159
  // the work face's ONE strict-schema directive — the declared properties are the
151
160
  // draft's field source (the keyset rides the injected `## Handoff schema` fence,
@@ -155,17 +164,17 @@ describe("TemplateAssembler — the template assembly + hard gates", () => {
155
164
  );
156
165
  expect(out).toContain("zero extra keys");
157
166
  // keyset zero-residue + the retired guard sentences are gone: the shell prose
158
- // enumerates no field and names no explicit INPUT_FINDINGS mirror ban
167
+ // enumerates no field and names no explicit INPUT_REVIEWS mirror ban
159
168
  expect(out).not.toContain("**Writable fields:**");
160
169
  expect(out).not.toContain("accepts exactly");
161
170
  expect(out).not.toContain("**Findings read-only:**");
162
171
  });
163
172
 
164
- it("T5 — the docs-fix shell carries the findings face's single strict-schema sentence — the required findings rides from INPUT_FINDINGS verbatim (no contradiction with the required gate)", () => {
173
+ it("T5 — the docs-fix shell carries the findings face's single strict-schema sentence — the required findings rides from INPUT_REVIEWS verbatim (no contradiction with the required gate)", () => {
165
174
  const out = assembler.render({
166
175
  ...ALL_VALUES,
167
176
  ROLE: "docs-fix",
168
- INPUT_DOC: "docs/x-design.md",
177
+ INPUT_SPEC: "docs/x-design.md",
169
178
  });
170
179
  // the findings face's ONE strict-schema directive — same schema-first wording,
171
180
  // the required `findings` told how to fill (the verbatim carry-over), so the
@@ -173,7 +182,7 @@ describe("TemplateAssembler — the template assembly + hard gates", () => {
173
182
  expect(out).toContain(
174
183
  "every top-level field of the draft comes from the `## Handoff schema` declared `properties`",
175
184
  );
176
- expect(out).toContain("`findings` (required) rides over from `INPUT_FINDINGS` verbatim");
185
+ expect(out).toContain("`findings` (required) rides over from `INPUT_REVIEWS` verbatim");
177
186
  expect(out).toContain("zero extra keys");
178
187
  // keyset zero-residue + the retired carried-as-is guard marker is gone
179
188
  expect(out).not.toContain("**Writable fields:**");
@@ -190,7 +199,7 @@ describe("TemplateAssembler — the template assembly + hard gates", () => {
190
199
  ROLE: "review",
191
200
  REVIEW_TYPE: "spec",
192
201
  INPUT_WAVE_BRIEF: "",
193
- INPUT_DOC: "docs/kairos/specs/s1-design.md",
202
+ INPUT_SPEC: "docs/kairos/specs/s1-design.md",
194
203
  OUTPUT_HANDOFF: "/ws/spec-review-1.json",
195
204
  });
196
205
  expect(spec.startsWith("# CDD dispatch — review round")).toBe(true);
@@ -200,9 +209,16 @@ describe("TemplateAssembler — the template assembly + hard gates", () => {
200
209
  // the claimed→pin clause (T4) — every behavior claim must cite a colocated pin;
201
210
  // the spec + plan review variants carry it (the task/branch variants do not)
202
211
  expect(spec).toContain("Claimed→pin");
203
- expect(spec).toContain("- `INPUT_DOC`: docs/kairos/specs/s1-design.md");
212
+ // the review-quality clauses (P10/D49) — every axis carries the vision-document
213
+ // rule (silence is not permission), the declined-to-judge ledger, and severity
214
+ // calibration; pinned per distinctive phrase
215
+ expect(spec).toContain("its silence is not permission");
216
+ expect(spec).toContain("nothing set aside is dropped silently");
217
+ expect(spec).toContain("accurate praise earns the rest of the report trust");
218
+ expect(spec).toContain("- `INPUT_SPEC`: docs/kairos/specs/s1-design.md");
219
+ expect(spec).not.toContain("- `INPUT_PLAN`");
204
220
  expect(spec).not.toContain("- `INPUT_WAVE_BRIEF`");
205
- expect(spec).not.toContain("- `INPUT_FINDINGS`");
221
+ expect(spec).not.toContain("- `INPUT_REVIEWS`");
206
222
  expect(spec).not.toContain("- `FIX_BASE`");
207
223
  expect(spec).not.toContain("BASE_BRANCH"); // spec review carries no scope anchor
208
224
  // a task review selects its own variant — the task axes + lens + the wave brief
@@ -220,6 +236,11 @@ describe("TemplateAssembler — the template assembly + hard gates", () => {
220
236
  expect(task).toContain("- `BASE_BRANCH`: develop");
221
237
  expect(task).not.toContain("Follow URC");
222
238
  expect(task).not.toContain("Claimed→pin"); // the task axes carry no clause
239
+ // every review axis (task/branch/spec/plan) carries the three review-quality
240
+ // clauses (P10/D49) — here on the wave variant
241
+ expect(task).toContain("its silence is not permission");
242
+ expect(task).toContain("nothing set aside is dropped silently");
243
+ expect(task).toContain("accurate praise earns the rest of the report trust");
223
244
  // a branch review carries the single doc anchor (the plan) + the scope anchor
224
245
  // BASE_BRANCH — the shared review layout carries the slot (§3.1/§3.2)
225
246
  const branch = assembler.render({
@@ -227,12 +248,18 @@ describe("TemplateAssembler — the template assembly + hard gates", () => {
227
248
  ROLE: "review",
228
249
  REVIEW_TYPE: "branch",
229
250
  INPUT_WAVE_BRIEF: "",
230
- INPUT_DOC: "docs/kairos/plans/p.md",
251
+ INPUT_PLAN: "docs/kairos/plans/p.md",
252
+ INPUT_SPEC: "docs/kairos/specs/p-design.md",
231
253
  BASE_BRANCH: "develop",
232
254
  OUTPUT_HANDOFF: "/ws/branch-review-1.json",
233
255
  });
234
- expect(branch).toContain("- `INPUT_DOC`: docs/kairos/plans/p.md");
256
+ expect(branch).toContain("- `INPUT_PLAN`: docs/kairos/plans/p.md");
257
+ expect(branch).toContain("- `INPUT_SPEC`: docs/kairos/specs/p-design.md");
235
258
  expect(branch).toContain("- `BASE_BRANCH`: develop");
259
+ // the branch variant carries the three review-quality clauses too (P10/D49)
260
+ expect(branch).toContain("its silence is not permission");
261
+ expect(branch).toContain("nothing set aside is dropped silently");
262
+ expect(branch).toContain("accurate praise earns the rest of the report trust");
236
263
  // a plan review carries the same claimed→pin clause as the spec variant; the
237
264
  // semantic spec/plan-absent anchor rule (the tree-review faces only) is the
238
265
  // lifecycle-injection concern — pinned at the CLI dispatch face (cli.test.ts)
@@ -241,11 +268,28 @@ describe("TemplateAssembler — the template assembly + hard gates", () => {
241
268
  ROLE: "review",
242
269
  REVIEW_TYPE: "plan",
243
270
  INPUT_WAVE_BRIEF: "",
244
- INPUT_DOC: "docs/kairos/plans/p.md",
271
+ INPUT_PLAN: "docs/kairos/plans/p.md",
272
+ INPUT_SPEC: "docs/kairos/specs/p-design.md",
245
273
  OUTPUT_HANDOFF: "/ws/plan-review-1.json",
246
274
  });
247
275
  expect(plan).toContain("**Criteria — plan:**");
248
276
  expect(plan).toContain("Claimed→pin");
277
+ // a plan review carries the plan's design-spec anchor (INPUT_SPEC) so the
278
+ // reviewer judges the plan against the spec it implements
279
+ expect(plan).toContain("- `INPUT_PLAN`: docs/kairos/plans/p.md");
280
+ expect(plan).toContain("- `INPUT_SPEC`: docs/kairos/specs/p-design.md");
281
+ // the spec review's judged doc IS the spec — carries INPUT_SPEC only; the wave
282
+ // review carries neither judged-doc anchor (the empty slots are dropped by the
283
+ // assembler)
284
+ const wave = assembler.render({
285
+ ...ALL_VALUES,
286
+ ROLE: "review",
287
+ REVIEW_TYPE: "wave",
288
+ BASE_BRANCH: "develop",
289
+ OUTPUT_HANDOFF: "/ws/tasks-1-review-1.json",
290
+ });
291
+ expect(wave).not.toContain("- `INPUT_PLAN`");
292
+ expect(wave).not.toContain("- `INPUT_SPEC`");
249
293
  });
250
294
 
251
295
  it("hard gates: a missing token value throws (named)", () => {
@@ -285,16 +329,23 @@ describe("TemplateAssembler — the template assembly + hard gates", () => {
285
329
  // every real declared mode renders cleanly under the assertion
286
330
  expect(() => assembler.render(ALL_VALUES)).not.toThrow();
287
331
  expect(() =>
288
- assembler.render({ ...ALL_VALUES, ROLE: "fix", INPUT_FINDINGS: "/f.json" }),
332
+ assembler.render({ ...ALL_VALUES, ROLE: "fix", INPUT_REVIEWS: "/f.json" }),
289
333
  ).not.toThrow();
290
334
  });
291
335
  });
292
336
 
293
- /** A two-task plan — task 1 steps all checkable, task 2 carries a bare step. */
337
+ /** A two-task plan — task 1 steps all checkable, task 2 carries a bare step (the
338
+ * front-matter head the plan parser reads). */
294
339
  const PLAN = [
295
- "# Test Plan",
296
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
297
- "- **Parent program**: [x-overall.md v1.21](docs/kairos/specs/x-overall.md)",
340
+ "---",
341
+ "title: Test Plan",
342
+ "doc-type: plan",
343
+ "version: v1.0",
344
+ "date: 2026-10-09",
345
+ "spec: docs/kairos/specs/x-design.md",
346
+ "parent-program: docs/kairos/specs/x-overall.md",
347
+ "parent-version: v1.21",
348
+ "---",
298
349
  "",
299
350
  "### Task 1: one",
300
351
  "- **Objective**: objective",