@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
@@ -25,6 +25,7 @@ import type { DocKey } from "../../contract/project.ts";
25
25
  import { Words } from "../../face/words.ts";
26
26
  import { ConfigLoader } from "../../infra/config.ts";
27
27
  import { GitClient } from "../../infra/git.ts";
28
+ import type { RepoPath } from "../../infra/root.ts";
28
29
  import { Workspace, WorkspaceRoot } from "../../infra/workspace.ts";
29
30
  import { targetFaces } from "../faces.ts";
30
31
  import { Ledger } from "../ledger.ts";
@@ -60,12 +61,19 @@ const dirty = (repoRoot: string): void => {
60
61
  writeFileSync(path.join(repoRoot, "dirty.txt"), "dirty\n", "utf8");
61
62
  };
62
63
 
63
- /** A plan literal over `### Task N:` blocks + `- **DependsOn**:` values. */
64
+ /** A plan literal over `### Task N:` blocks + `- **DependsOn**:` values (the
65
+ * front-matter head the plan parser reads). */
64
66
  const planDoc = (blocks: readonly (readonly string[])[]): string => {
65
67
  return [
66
- "# Test Plan",
67
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
68
- "- **Parent program**: [x-overall.md v1.0](docs/kairos/specs/x-overall.md)",
68
+ "---",
69
+ "title: Test Plan",
70
+ "doc-type: plan",
71
+ "version: v1.0",
72
+ "date: 2026-10-09",
73
+ "spec: docs/kairos/specs/x-design.md",
74
+ "parent-program: docs/kairos/specs/x-overall.md",
75
+ "parent-version: v1.0",
76
+ "---",
69
77
  "",
70
78
  "## Constraints",
71
79
  "",
@@ -107,22 +115,28 @@ const memoryFs = (content: string): DocFs => {
107
115
  return {
108
116
  exists: () => true,
109
117
  read: () => content,
110
- // The sibling scan resolves the `**Parent program**` target basename — the
118
+ // The sibling scan resolves the `parent-program:` target basename — the
111
119
  // judged doc's family lists it.
112
120
  list: (_p: string) => ["x-overall.md"],
113
121
  };
114
122
  };
115
123
 
116
- /** A conforming phase-spec — every current + P4.1-T2 phase-spec element present (the
117
- * header tuple + the version lineage + a Change-history table + the design
118
- * skeleton), so the doc-contract gate passes it (zero structural findings). */
124
+ /** A conforming phase-spec — every current + P4.1-T2 phase-spec element present
125
+ * (the front-matter head (since T6) + the version lineage + a Change-history
126
+ * table + the design skeleton), so the doc-contract gate passes it (zero
127
+ * structural findings). */
119
128
  const CONFORMING_SPEC = [
120
- "# Test Spec",
121
- "- **Version**: v1.0 · 2026-10-09",
122
- "- **Status**: Draft",
123
- "- **Author**: x",
124
- "- **Parent program**: [x-overall.md v1.0](docs/kairos/specs/x-overall.md)",
125
- "- **Depends on**: P1",
129
+ "---",
130
+ "title: Test Spec",
131
+ "doc-type: phase-spec",
132
+ "version: v1.0",
133
+ "date: 2026-10-09",
134
+ "status: Draft",
135
+ "author: x",
136
+ "parent-program: docs/kairos/specs/x-overall.md",
137
+ "parent-version: v1.0",
138
+ "depends-on: P1",
139
+ "---",
126
140
  "",
127
141
  "## Design",
128
142
  "",
@@ -147,9 +161,18 @@ const CONFORMING_SPEC = [
147
161
  "| v1.0 | 2026-10-09 | initial | [human] |",
148
162
  ].join("\n");
149
163
 
150
- /** A defective phase-spec — a required section missing, so the doc-contract
151
- * gate refuses it (the negative case). */
152
- const DEFECTIVE_SPEC = ["# Test Spec", "- **Version**: v1.0", "", "## Design"].join("\n");
164
+ /** A defective phase-spec — the required sections/head keys missing, so the
165
+ * doc-contract gate refuses it (the negative case). */
166
+ const DEFECTIVE_SPEC = [
167
+ "---",
168
+ "title: Test Spec",
169
+ "doc-type: phase-spec",
170
+ "version: v1.0",
171
+ "status: Draft",
172
+ "---",
173
+ "",
174
+ "## Design",
175
+ ].join("\n");
153
176
 
154
177
  // ---------------------------------------------------------------------------
155
178
  // the seam's context builders
@@ -180,7 +203,7 @@ const waveCtx = (
180
203
 
181
204
  /** The doc-face context — the target doc judged by the doc-contract gate. `docKey`
182
205
  * is the doc's declared type (spec §12 · D34); null models a present doc carrying
183
- * no `- **Doc type**:` declaration (the seam BLOCKs). */
206
+ * no `doc-type:` key (the seam BLOCKs). */
184
207
  const docCtx = (
185
208
  repoRoot: string,
186
209
  docKey: DocKey | null,
@@ -198,7 +221,10 @@ const docCtx = (
198
221
  planText: null,
199
222
  tasks: null,
200
223
  ledger,
201
- doc: { docKey, path: `docs/kairos/specs/${docKey === "plan" ? "plan" : "spec"}.md` },
224
+ doc: {
225
+ docKey,
226
+ path: `docs/kairos/specs/${docKey === "plan" ? "plan" : "spec"}.md` as RepoPath,
227
+ },
202
228
  };
203
229
  };
204
230
 
@@ -436,12 +462,40 @@ describe("PreFlight — the doc-contract gate (Contract.validate over the doc fa
436
462
  expect(verdict.ok).toBe(false);
437
463
  expect(verdict.gate).toBe("doc-contract");
438
464
  expect(verdict.reason).toBe("doc-contract");
439
- expect(verdict.message).toContain("declares no `- **Doc type**:` line");
465
+ expect(verdict.message).toContain("declares no `doc-type:` key");
440
466
  expect(verdict.order).toEqual(["tree-clean", "doc-contract"]);
441
467
  } finally {
442
468
  cleanup();
443
469
  }
444
470
  });
471
+
472
+ it("an unparseable front-matter BLOCKs with the REAL YAML failure — never the no-doc-type misread (D1 · #341)", async () => {
473
+ const { repoRoot, cleanup } = gitRepo();
474
+ try {
475
+ const malformed = [
476
+ "---",
477
+ "title: Test Spec",
478
+ "doc-type: phase-spec",
479
+ "version: v1.0",
480
+ "status: Draft",
481
+ "author: [human] · Claude Opus 5",
482
+ "---",
483
+ "",
484
+ "## Design",
485
+ ].join("\n");
486
+ const preflight = preflightOf(memoryFs(malformed));
487
+ const verdict = await preflight.vet(docCtx(repoRoot, "phase-spec", "review"));
488
+ expect(verdict.ok).toBe(false);
489
+ expect(verdict.gate).toBe("doc-contract");
490
+ expect(verdict.reason).toBe("doc-contract");
491
+ // the misread dies — the wording reports the parse position, never "no doc-type"
492
+ expect(verdict.message).toContain("not valid YAML");
493
+ expect(verdict.message).toMatch(/on line \d+, column \d+/);
494
+ expect(verdict.message).not.toContain("declares no `doc-type:` key");
495
+ } finally {
496
+ cleanup();
497
+ }
498
+ });
445
499
  });
446
500
 
447
501
  // ---------------------------------------------------------------------------
@@ -449,11 +503,11 @@ describe("PreFlight — the doc-contract gate (Contract.validate over the doc fa
449
503
  // ---------------------------------------------------------------------------
450
504
 
451
505
  describe("PreFlight — the lifecycle dispatch-entry wiring (child zero dispatch)", () => {
452
- it("advance() refuses a preflight-blocked frame without dispatching the child", () => {
506
+ it("advance() refuses a preflight-blocked frame without dispatching the child", async () => {
453
507
  const { repoRoot, cleanup } = gitRepo();
454
508
  try {
455
509
  const calls: OpenFrame[] = [];
456
- const dispatch: DispatchStep = (frame) => {
510
+ const dispatch: DispatchStep = async (frame) => {
457
511
  calls.push(frame);
458
512
  return { status: "APPROVED", findings: [] };
459
513
  };
@@ -475,15 +529,15 @@ describe("PreFlight — the lifecycle dispatch-entry wiring (child zero dispatch
475
529
  new ConfigLoader(),
476
530
  ),
477
531
  dispatch,
478
- target: { kind: "doc", doc: "docs/kairos/specs/x.md" },
532
+ target: { kind: "spec", doc: "docs/kairos/specs/x.md" },
479
533
  preflight: { gate: () => blocked },
480
534
  });
481
- const step = run.advance();
535
+ const step = await run.advance();
482
536
  expect(step).not.toBeNull();
483
537
  expect(step!.preflight).toEqual(blocked);
484
538
  expect(step!.route).toBeNull();
485
539
  expect(calls).toEqual([]); // child zero dispatch
486
- expect(run.advance()).not.toBeNull(); // the refused frame re-offers (resume)
540
+ expect(await run.advance()).not.toBeNull(); // the refused frame re-offers (resume)
487
541
  } finally {
488
542
  cleanup();
489
543
  }
@@ -0,0 +1,142 @@
1
+ // packages/cdd-engine/src-next/session/__tests__/round-naming.test.ts
2
+ // P11 T4 — the RoundNaming colocated pins: the frame → artifact-name derivations
3
+ // (report / evidence / brief) the lifecycle's read-back and the dry-run preview
4
+ // share, and the family-op mapping those stems key on. The class touches no disk
5
+ // (resolve is pure path arithmetic), so the workspace is constructed inline.
6
+
7
+ import path from "node:path";
8
+ import { describe, expect, it } from "vitest";
9
+ import { Workspace, WorkspaceRoot } from "../../infra/workspace.ts";
10
+ import type { OpType } from "../ledger.ts";
11
+ import { RoundNaming } from "../round-naming.ts";
12
+ import type { OpenFrame } from "../run.ts";
13
+
14
+ const ROOT = "/repo";
15
+ const WORKSPACE = new Workspace(new WorkspaceRoot(ROOT, ".kairos/cdd"), "p3");
16
+ const NAMING = new RoundNaming(WORKSPACE);
17
+ const inWorkspace = (name: string): string => path.join(ROOT, ".kairos/cdd", "p3", name);
18
+
19
+ /** A frame built from the wave implement frame's shape; `over` supplies the face. */
20
+ const frame = (over: Partial<OpenFrame>): OpenFrame => ({
21
+ type: "wave",
22
+ phase: "implement",
23
+ round: 1,
24
+ target: { kind: "wave", tasks: [1] },
25
+ params: { tasks: "1" },
26
+ key: "1",
27
+ ...over,
28
+ });
29
+
30
+ describe("RoundNaming — the frame → prescribed artifact names (report / evidence / brief)", () => {
31
+ it("derives the brief path of a wave's task group", () => {
32
+ expect(NAMING.brief("1,2")).toBe(inWorkspace("tasks-1,2-brief.md"));
33
+ });
34
+
35
+ it("derives the report path per face — the wave/branch family stems and the doc line's round-keyed stem", () => {
36
+ // the wave implement round carries no round token (the line keys implement alone)
37
+ expect(NAMING.report(frame({ type: "wave", phase: "implement" }))).toBe(
38
+ inWorkspace("tasks-1-implement-report.md"),
39
+ );
40
+ // a wave review round books its own round-keyed report
41
+ expect(
42
+ NAMING.report(
43
+ frame({ type: "wave", phase: "review", round: 2, params: { tasks: "1", round: 2 } }),
44
+ ),
45
+ ).toBe(inWorkspace("tasks-1-review-2-report.md"));
46
+ // the branch review rides the review op (branch-review → review), never the raw phase
47
+ expect(
48
+ NAMING.report(
49
+ frame({
50
+ type: "branch",
51
+ phase: "branch-review",
52
+ round: 3,
53
+ target: { kind: "branch" },
54
+ params: { round: 3 },
55
+ key: "branch",
56
+ }),
57
+ ),
58
+ ).toBe(inWorkspace("branch-review-3-report.md"));
59
+ expect(
60
+ NAMING.report(
61
+ frame({
62
+ type: "branch",
63
+ phase: "fix",
64
+ round: 1,
65
+ target: { kind: "branch" },
66
+ params: { round: 1 },
67
+ key: "branch",
68
+ }),
69
+ ),
70
+ ).toBe(inWorkspace("branch-fix-1-report.md"));
71
+ // the doc line keys the {type}-{op}-{round} stem
72
+ expect(
73
+ NAMING.report(
74
+ frame({
75
+ type: "spec",
76
+ phase: "review",
77
+ round: 1,
78
+ target: { kind: "spec", doc: "s.md" },
79
+ params: { round: 1 },
80
+ }),
81
+ ),
82
+ ).toBe(inWorkspace("spec-review-1-report.md"));
83
+ expect(
84
+ NAMING.report(
85
+ frame({
86
+ type: "plan",
87
+ phase: "fix",
88
+ round: 2,
89
+ target: { kind: "plan", doc: "p.md" },
90
+ params: { round: 2 },
91
+ }),
92
+ ),
93
+ ).toBe(inWorkspace("plan-fix-2-report.md"));
94
+ });
95
+
96
+ it("derives the evidence name/path on the work faces only — the review and doc faces prescribe none", () => {
97
+ // the task families key the line; the branch line names the family alone
98
+ expect(NAMING.evidenceName(frame({ type: "wave", phase: "implement" }))).toBe(
99
+ "tasks-1-test-evidence.json",
100
+ );
101
+ expect(NAMING.evidence(frame({ type: "wave", phase: "implement" }))).toBe(
102
+ inWorkspace("tasks-1-test-evidence.json"),
103
+ );
104
+ expect(
105
+ NAMING.evidenceName(
106
+ frame({ type: "wave", phase: "fix", round: 2, params: { tasks: "1", round: 2 } }),
107
+ ),
108
+ ).toBe("tasks-1-test-evidence.json");
109
+ expect(
110
+ NAMING.evidenceName(
111
+ frame({ type: "branch", phase: "fix", target: { kind: "branch" }, params: { round: 1 } }),
112
+ ),
113
+ ).toBe("branch-test-evidence.json");
114
+ // off the work faces the evidence slot is empty (only present facts ride)
115
+ expect(
116
+ NAMING.evidence(
117
+ frame({ type: "wave", phase: "review", round: 1, params: { tasks: "1", round: 1 } }),
118
+ ),
119
+ ).toBe("");
120
+ expect(
121
+ NAMING.evidenceName(
122
+ frame({ type: "spec", phase: "review", target: { kind: "spec", doc: "s.md" } }),
123
+ ),
124
+ ).toBe("");
125
+ expect(
126
+ NAMING.evidence(frame({ type: "plan", phase: "fix", target: { kind: "plan", doc: "p.md" } })),
127
+ ).toBe("");
128
+ });
129
+
130
+ it("maps the frame phase to the handoff-family op — branch-review rides the review family", () => {
131
+ expect(NAMING.op(frame({ phase: "implement" }))).toBe("implement");
132
+ expect(NAMING.op(frame({ phase: "review" }))).toBe("review");
133
+ expect(NAMING.op(frame({ phase: "fix" }))).toBe("fix");
134
+ const branchReview = NAMING.op(frame({ type: "branch", phase: "branch-review" })) as OpType;
135
+ expect(branchReview).toBe("review");
136
+ });
137
+
138
+ it("carries the evidence family prefix — tasks for the wave families, branch for the branch line", () => {
139
+ expect(NAMING.prefix(frame({ type: "wave" }))).toBe("tasks");
140
+ expect(NAMING.prefix(frame({ type: "branch" }))).toBe("branch");
141
+ });
142
+ });