@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
package/README.md CHANGED
@@ -10,7 +10,7 @@ The engine runs the implement / review / fix phases of the CDD workflow against
10
10
 
11
11
  ## Installation
12
12
 
13
- Requires Node.js `>= 22.12.0`.
13
+ Requires Node.js `>= 24`.
14
14
 
15
15
  ```bash
16
16
  # global CLI (provides the `cdd` binary)
@@ -22,7 +22,7 @@ npm install @oscaner-skills/cdd-engine
22
22
 
23
23
  ## CLI
24
24
 
25
- Global option: `--dry-run` — simulate the dispatch without writing handoff artifacts.
25
+ Global option: `--dry-run` — preview the next dispatch step and its expected artifacts — zero repo writes, no round consumed (implement/review/fix only).
26
26
 
27
27
  | Subcommand | Usage | Purpose |
28
28
  |------------|-------|---------|
package/README.zh-CN.md CHANGED
@@ -12,7 +12,7 @@ CDD 引擎 CLI——kairos `cdd-dev` 技能背后的任务运行器、文档/分
12
12
 
13
13
  ## 安装
14
14
 
15
- 需要 Node.js `>= 22.12.0`。
15
+ 需要 Node.js `>= 24`。
16
16
 
17
17
  ```bash
18
18
  # 全局 CLI(提供 `cdd` 二进制)
@@ -24,7 +24,7 @@ npm install @oscaner-skills/cdd-engine
24
24
 
25
25
  ## CLI
26
26
 
27
- 全局选项:`--dry-run`——模拟派发而不写 handoff 产物。
27
+ 全局选项:`--dry-run`——预览下一步派发及其预期产物 — 对 repo 零写入、不占轮次(仅限 implement/review/fix)。
28
28
 
29
29
  | 子命令 | 用法 | 用途 |
30
30
  |--------|------|------|
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "2.0.0",
3
+ "version": "3.0.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -22,12 +22,13 @@
22
22
  "commander": "^15.0.0",
23
23
  "execa": "^10.1.1",
24
24
  "jsonc-parser": "^3.3.1",
25
- "simple-git": "^4.0.2"
25
+ "simple-git": "^4.0.2",
26
+ "yaml": "^2.9.1"
26
27
  },
27
28
  "devDependencies": {
28
29
  "@types/node": "^24.19.2",
29
30
  "typescript": "^7.0.2",
30
- "vitest": "^5.0.3"
31
+ "vitest": "^5.0.5"
31
32
  },
32
33
  "repository": {
33
34
  "type": "git",
@@ -0,0 +1,39 @@
1
+ // packages/cdd-engine/src-next/__tests__/dead-decl.guard.test.ts
2
+ // T14 (spec §3.4 ⑧/⑯/⑱/⑲) — the dead-declaration zero-residue gate. The T1=a
3
+ // stance is "a declaration is a fact": a field/constant/helper with zero reader is
4
+ // either deleted or given a real consumer, never left as a dead declaration.
5
+ // · ⑧ HOSTS[*].cache — deleted (zero reader).
6
+ // · ⑯ HandoffFamily.round/phase/fixFamily/fixTemplate/prev — deleted (name +
7
+ // schema are the only readers).
8
+ // · ⑱ CRASH_TAIL_LINES — the ghost comment referencing the nonexistent symbol.
9
+ // · ⑲ setupRepo — the zero-caller helper (kairos tests plane).
10
+
11
+ import { readFileSync } from "node:fs";
12
+ import { fileURLToPath } from "node:url";
13
+ import { describe, expect, it } from "vitest";
14
+
15
+ const SRC = fileURLToPath(new URL("../", import.meta.url));
16
+ const read = (rel: string): string => readFileSync(`${SRC}/${rel}`, "utf8");
17
+
18
+ describe("dead-declaration zero residue (spec §3.4)", () => {
19
+ it("⑧ the HOSTS rows carry zero cache field", () => {
20
+ const hostSrc = read("face/host.ts");
21
+ expect(hostSrc).not.toMatch(/\bcache\b/);
22
+ expect(hostSrc).not.toMatch(/HostCacheSpec/);
23
+ });
24
+
25
+ it("⑯ the HandoffFamily interface + table carry zero dead fields", () => {
26
+ const runtimeSrc = read("infra/runtime.ts");
27
+ for (const dead of ["fixFamily", "fixTemplate"]) {
28
+ expect(runtimeSrc, dead).not.toContain(dead);
29
+ }
30
+ // the round/phase/prev fields are gone (the table rows carry name + schema only)
31
+ expect(runtimeSrc).not.toMatch(/^\s*round:/m);
32
+ expect(runtimeSrc).not.toMatch(/^\s*phase:/m);
33
+ expect(runtimeSrc).not.toMatch(/^\s*prev:/m);
34
+ });
35
+
36
+ it("⑱ the CRASH_TAIL_LINES ghost symbol is gone from ledger.ts", () => {
37
+ expect(read("session/ledger.ts")).not.toContain("CRASH_TAIL_LINES");
38
+ });
39
+ });
@@ -0,0 +1,69 @@
1
+ // packages/cdd-engine/src-next/__tests__/floor.guard.test.ts
2
+ // T8 (spec §3.1 ②) — the floor single-source gate. ② is TWO distinct facts that
3
+ // must NOT be merged into one source:
4
+ // · the INSTALL floor — `packages/cdd-engine/package.json#engines` ("node"):
5
+ // which Node the published artifact is installed/run on. The README install
6
+ // lines (README.md + its zh mirror) must agree with it.
7
+ // · the TYPE-STRIPPING floor — `bin.ts` `NODE_FLOOR` (22.18): the dev face's
8
+ // `node src-next/bin.ts` native-type-stripping requirement. The README
9
+ // development lines must agree with it.
10
+ // Deriving NODE_FLOOR from `#engines` (`>=24`) would make the guard OVER-STRICT
11
+ // (it would reject Node 22.18–23.x, which the README explicitly documents as
12
+ // usable for source-direct runs), so the two facts stay separate and each is
13
+ // pinned to its own correct source by this gate.
14
+
15
+ import { readFileSync } from "node:fs";
16
+ import { fileURLToPath } from "node:url";
17
+ import { describe, expect, it } from "vitest";
18
+
19
+ const ENGINE_ROOT = fileURLToPath(new URL("../../", import.meta.url));
20
+ const read = (rel: string): string => readFileSync(`${ENGINE_ROOT}/${rel}`, "utf8");
21
+
22
+ /** The install floor declared by `package.json#engines.node` (e.g. ">=24"). */
23
+ const enginesFloor = (): string => {
24
+ const pkg = JSON.parse(read("package.json")) as { engines?: { node?: string } };
25
+ const node = pkg.engines?.node;
26
+ if (node === undefined) throw new Error("package.json#engines.node is missing");
27
+ return node.replace(/\s+/g, "");
28
+ };
29
+
30
+ /** The type-stripping floor declared by `bin.ts`'s NODE_FLOOR (major.minor). */
31
+ const typeStrippingFloor = (): string => {
32
+ const src = read("src-next/bin.ts");
33
+ const match = /const NODE_FLOOR = \{ major: (\d+), minor: (\d+) \}/.exec(src);
34
+ if (match === null) throw new Error("bin.ts NODE_FLOOR shape changed");
35
+ return `${match[1]}.${match[2]}`;
36
+ };
37
+
38
+ describe("the two floors hold their correct single source (spec §3.1 ②)", () => {
39
+ it("the INSTALL floor — both README install lines agree with package.json#engines", () => {
40
+ const floor = enginesFloor(); // ">=24"
41
+ const bare = floor.replace(/^>=\s*/, ""); // "24"
42
+ for (const rel of ["README.md", "README.zh-CN.md"]) {
43
+ const src = read(rel);
44
+ // The install-requirement line: "Requires Node.js `>= 24`." / "需要 Node.js `>= 24`。"
45
+ const match = /Node\.js `([^`]+)`/.exec(src);
46
+ expect(match, `${rel}: no install-floor line`).not.toBeNull();
47
+ expect(match?.[1]?.replace(/\s+/g, ""), `${rel}: install floor drifted from #engines`).toBe(
48
+ [">=", bare].join(""),
49
+ );
50
+ }
51
+ });
52
+
53
+ it("the TYPE-STRIPPING floor — both README development lines agree with bin.ts NODE_FLOOR", () => {
54
+ const floor = typeStrippingFloor(); // "22.18"
55
+ for (const rel of ["README.md", "README.zh-CN.md"]) {
56
+ const src = read(rel);
57
+ // The dev line: "… (Node ≥22.18 native type stripping)" / "…(Node ≥22.18 原生类型剥离)"
58
+ const match = /Node\s*≥\s*(\d+\.\d+)/.exec(src);
59
+ expect(match, `${rel}: no type-stripping-floor line`).not.toBeNull();
60
+ expect(match?.[1], `${rel}: dev floor drifted from NODE_FLOOR`).toBe(floor);
61
+ }
62
+ });
63
+
64
+ it("the two facts stay distinct — the install floor is not silently merged into NODE_FLOOR", () => {
65
+ // The install floor (>=24) and the type-stripping floor (22.18) are different
66
+ // numbers: deriving the latter from the former would over-strict the dev guard.
67
+ expect(enginesFloor().replace(/^>=\s*/, "")).not.toBe(typeStrippingFloor().split(".")[0]);
68
+ });
69
+ });
@@ -0,0 +1,66 @@
1
+ // packages/cdd-engine/src-next/__tests__/issue-body.guard.test.ts
2
+ // T10 (spec §3.1 ① · §3.2 ⑤ · §3.4 ⑰) — the issue-body single-source gate.
3
+ // · ① the label table lives ONLY on the word table (face/words.ts ISSUE_LABEL_WORDS,
4
+ // the renderer's real read); the withdrawn `sectionLabels` copy in
5
+ // templates/report/issue-body.json (which had drifted: bug.context zh
6
+ // `## 场景` vs `## 背景`, enhancement.problem `## Gap` vs `## Current behavior`)
7
+ // is deleted — a re-added divergent copy fails here.
8
+ // · ⑤ the components roster in the JSON must derive EXACTLY: six kairos
9
+ // components are `"kairos:" + SKILL_ROSTER key` (a prefix transform — the roster
10
+ // is the engine's closed six-set, skill-anatomy.ts) plus two fixed headers
11
+ // (`kairos (general)` / `cdd-engine`) that carry no roster source.
12
+ // · ⑰ the orphan fields (severities / metaFields / reportDef / masterDef — zero
13
+ // reader) are deleted.
14
+
15
+ import { readFileSync } from "node:fs";
16
+ import { fileURLToPath } from "node:url";
17
+ import { describe, expect, it } from "vitest";
18
+ import { SKILL_ANATOMY } from "../contract/skill-anatomy.ts";
19
+
20
+ const ISSUE_BODY_PATH = fileURLToPath(
21
+ new URL("../../templates/report/issue-body.json", import.meta.url),
22
+ );
23
+
24
+ /** The shipped issue-body template — the emit-side form/component source. */
25
+ const issueBody = (): { components?: unknown } & Record<string, unknown> =>
26
+ JSON.parse(readFileSync(ISSUE_BODY_PATH, "utf8")) as { components?: unknown } & Record<
27
+ string,
28
+ unknown
29
+ >;
30
+
31
+ describe("issue-body single-source (spec §3.1 ① · §3.2 ⑤ · §3.4 ⑰)", () => {
32
+ it("① the withdrawn sectionLabels copy is gone — the word table is the sole label source", () => {
33
+ // The label rows live on face/words.ts (the renderer's real read). A second
34
+ // copy here is the drift this gate bans.
35
+ expect(issueBody()).not.toHaveProperty("sectionLabels");
36
+ });
37
+
38
+ it("⑰ the orphan fields carry zero residue (severities / metaFields / reportDef / masterDef)", () => {
39
+ const meta = issueBody();
40
+ for (const orphan of ["severities", "metaFields", "reportDef", "masterDef"]) {
41
+ expect(meta, `${orphan} must be deleted (zero reader)`).not.toHaveProperty(orphan);
42
+ }
43
+ });
44
+
45
+ it("⑤ the components roster derives — six roster-prefixed kairos keys + two fixed headers", () => {
46
+ const components = issueBody().components as unknown[];
47
+ expect(Array.isArray(components)).toBe(true);
48
+
49
+ // The two fixed headers (no roster source) — declared explicitly.
50
+ const fixed = ["kairos (general)", "cdd-engine"];
51
+ // The six kairos components = `kairos:` + the closed six-set roster key.
52
+ const derived = Object.keys(SKILL_ANATOMY.skills.registry).map((key) => `kairos:${key}`);
53
+
54
+ const expected = new Set([...fixed, ...derived]);
55
+ expect(components).toHaveLength(expected.size);
56
+ for (const component of components) {
57
+ expect(expected.has(String(component)), `unexpected component: ${String(component)}`).toBe(
58
+ true,
59
+ );
60
+ }
61
+ // The roster-derived half is exactly the six kairos keys (the prefix transform).
62
+ for (const component of derived) {
63
+ expect(components, `${component} missing from the roster`).toContain(component);
64
+ }
65
+ });
66
+ });
@@ -0,0 +1,72 @@
1
+ // packages/cdd-engine/src-next/__tests__/phase-suffix.guard.test.ts
2
+ // T12 (spec §3.2 ⑬) — the phase-suffix consistency gate. The slug phase-suffix
3
+ // grammar is ONE fact with two consumption surfaces:
4
+ // · Workspace.phaseSuffixOf — the trailing `-p<major>(.<minor>)*` parse
5
+ // (the `-p…$` form, infra/workspace.ts).
6
+ // · BoardView.scanPhases — the suffix-only match over the specs dir
7
+ // (the `^p…$` form, face/board-view.ts, via PHASE_SUFFIX_BARE).
8
+ // Both MUST compose from the shared `PHASE_SUFFIX_CORE` fragment so the two forms
9
+ // cannot drift. (The doc-contract design-unit syntax `P\d+(\.\d+)*-design` is
10
+ // ANOTHER fact — uppercase + `-design` tail — never merged here.) This gate pins
11
+ // the single source structurally and the two surfaces behaviorally (in-grammar
12
+ // agrees, out-of-grammar rejected at both).
13
+
14
+ import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
15
+ import { tmpdir } from "node:os";
16
+ import path from "node:path";
17
+ import { fileURLToPath } from "node:url";
18
+ import { afterEach, beforeEach, describe, expect, it } from "vitest";
19
+ import { BoardView } from "../face/board-view.ts";
20
+ import { PHASE_SUFFIX_BARE, PHASE_SUFFIX_CORE, Workspace } from "../infra/workspace.ts";
21
+
22
+ const SRC = fileURLToPath(new URL("../", import.meta.url));
23
+ const read = (rel: string): string => readFileSync(`${SRC}/${rel}`, "utf8");
24
+
25
+ describe("the phase-suffix grammar holds one shared source (spec §3.2 ⑬)", () => {
26
+ it("both regex forms are composed from PHASE_SUFFIX_CORE — zero second literal", () => {
27
+ // The shared fragment is the ONE grammar: the suffix-only form is built from it
28
+ // (`^${PHASE_SUFFIX_CORE}$` — asserted behaviorally below), and the board's scan
29
+ // imports that derived form rather than re-spelling the pattern.
30
+ expect(PHASE_SUFFIX_BARE.source).toBe(`^${PHASE_SUFFIX_CORE}$`);
31
+ const boardSrc = read("face/board-view.ts");
32
+ expect(boardSrc).toContain("PHASE_SUFFIX_BARE");
33
+ // no raw phase-suffix regex literal re-spelled in the board face
34
+ expect(boardSrc).not.toMatch(/p\\d\+/);
35
+ });
36
+
37
+ it("in-grammar suffixes parse identically at both surfaces", () => {
38
+ // the tail parse captures the dash-bearing `-p…` segment; the board's bare
39
+ // match takes the dash-less `p…` segment (same grammar, different input form).
40
+ for (const suffix of ["p2", "p4.1", "p10"]) {
41
+ expect(Workspace.phaseSuffixOf(`prog-${suffix}`), `phaseSuffixOf prog-${suffix}`).toBe(
42
+ `-${suffix}`,
43
+ );
44
+ expect(PHASE_SUFFIX_BARE.test(suffix), `board bare test ${suffix}`).toBe(true);
45
+ }
46
+ });
47
+
48
+ it("out-of-grammar suffixes are rejected at both surfaces (uppercase is another fact)", () => {
49
+ for (const suffix of ["P7", "p", "p7x", "pp7"]) {
50
+ expect(Workspace.phaseSuffixOf(`prog-${suffix}`), `phaseSuffixOf prog-${suffix}`).toBeNull();
51
+ expect(PHASE_SUFFIX_BARE.test(suffix), `board bare test ${suffix}`).toBe(false);
52
+ }
53
+ });
54
+
55
+ describe("behavioral agreement over the on-disk scan", () => {
56
+ let repo: string;
57
+ beforeEach(() => {
58
+ repo = mkdtempSync(path.join(tmpdir(), "phase-suffix-guard-"));
59
+ });
60
+ afterEach(() => {
61
+ rmSync(repo, { recursive: true, force: true });
62
+ });
63
+
64
+ it("scanPhases admits exactly the suffixes phaseSuffixOf accepts", () => {
65
+ mkdirSync(path.join(repo, "docs/kairos/specs"), { recursive: true });
66
+ // in-grammar → admitted; out-of-grammar (uppercase `P7`) → not a phase
67
+ for (const name of ["prog-p7", "prog-p7.1", "prog-P7"])
68
+ writeFileSync(path.join(repo, "docs/kairos/specs", `${name}-design.md`), "# S\n");
69
+ expect(BoardView.scanPhases("prog", repo)).toEqual(["-p7", "-p7.1"]);
70
+ });
71
+ });
72
+ });
@@ -1,34 +1,39 @@
1
1
  // packages/cdd-engine/src-next/__tests__/smoke.integration.test.ts
2
2
  // The engine smoke integration test — the consumer release gate migrated from
3
3
  // scripts/smoke-cdd.ts (P5 T7): boots the source bin (`node src-next/bin.ts`) over a
4
- // fresh fixture git repo and asserts the status-capsule contract on the dry-run
5
- // chain (`--dry-run implement` + `--dry-run review`) plus the `--help` commander
6
- // face. The engine carries no version assertion — `--expect-version` was withdrawn as
7
- // a no-op (user adjudication 2026-10-12); the `smoke` script (`pnpm -C
8
- // packages/cdd-engine run smoke`) is the release.yml gate's shared anchor.
4
+ // fresh fixture git repo and asserts the `--help` commander face plus the read-only
5
+ // `--dry-run` preview (the five-row next-step forecast at zero repo writes). The engine
6
+ // carries no version assertion — `--expect-version` was withdrawn as a no-op (user
7
+ // adjudication 2026-10-12); the `smoke` script (`pnpm -C packages/cdd-engine run smoke`)
8
+ // is the release.yml gate's shared anchor.
9
9
  //
10
10
  // Zero module-level bare functions — the helpers are `const` (the P5
11
11
  // zero-`function`-declaration discipline).
12
12
 
13
13
  import { execFileSync, spawnSync } from "node:child_process";
14
- import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
14
+ import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
15
15
  import { tmpdir } from "node:os";
16
16
  import path from "node:path";
17
17
  import { fileURLToPath } from "node:url";
18
- import { describe, expect, it } from "vitest";
18
+ import { describe, it } from "vitest";
19
19
 
20
20
  /** The source bin under test — the engine's own entry (spawned, never imported). */
21
21
  const BIN = fileURLToPath(new URL("../bin.ts", import.meta.url));
22
22
 
23
- /** The fixture plan text — the canonical data-shaped task record (the markers the
24
- * plan parser reads; the workspace slug derives `fixture` from the basename). */
23
+ /** The fixture plan text — the canonical data-shaped task record (the front-matter
24
+ * head the plan parser reads; the workspace slug derives `fixture` from the
25
+ * basename). */
25
26
  const fixturePlan = (): string =>
26
27
  [
27
- "# Fixture Plan",
28
- "",
29
- "**Spec:** [fixture-design.md](fixture-design.md)",
30
- "",
31
- "- **Parent program**: [fixture-overall.md v1.0](fixture-overall.md)",
28
+ "---",
29
+ "title: Fixture Plan",
30
+ "doc-type: plan",
31
+ "version: v1.0",
32
+ "date: 2026-10-09",
33
+ "spec: fixture-design.md",
34
+ "parent-program: fixture-overall.md",
35
+ "parent-version: v1.0",
36
+ "---",
32
37
  "",
33
38
  "## Constraints",
34
39
  "",
@@ -36,22 +41,26 @@ const fixturePlan = (): string =>
36
41
  "",
37
42
  "### Task 1: fixture task",
38
43
  "",
39
- "- **Objective**: exercise the installed cdd engine under dry-run",
44
+ "- **Objective**: exercise the installed cdd engine under the read-only preview",
40
45
  "- **Files**: fixture-plan.md",
41
46
  "- **Steps**:",
42
- " 1. run the new-tree engine under dry-run — checkable: the dry-run chain completes",
47
+ " 1. run the new-tree engine under `--dry-run` — checkable: the preview block completes",
43
48
  "- **Acceptance**:",
44
- " - the dry-run chain prints the status capsule",
49
+ " - the preview forecasts the next step with zero repo writes",
45
50
  "- **DependsOn**: none",
46
51
  "",
47
52
  ].join("\n");
48
53
 
49
- /** The fixture design spec — the plan's **Spec:** link target (existence only). */
54
+ /** The fixture design spec — the plan's `spec:` link target (existence only). */
50
55
  const fixtureSpec = (): string =>
51
56
  [
52
- "# Fixture Design",
53
- "",
54
- "- **Version**: v1.0",
57
+ "---",
58
+ "title: Fixture Design",
59
+ "doc-type: phase-spec",
60
+ "version: v1.0",
61
+ "date: 2026-10-09",
62
+ "status: Draft",
63
+ "---",
55
64
  "",
56
65
  "## Design",
57
66
  "",
@@ -61,12 +70,16 @@ const fixtureSpec = (): string =>
61
70
  "",
62
71
  ].join("\n");
63
72
 
64
- /** The fixture overall — the plan's **Parent program** link target (existence only). */
73
+ /** The fixture overall — the plan's `parent-program:` link target (existence only). */
65
74
  const fixtureOverall = (): string =>
66
75
  [
67
- "# Fixture Overall",
68
- "",
69
- "- **Version**: v1.0",
76
+ "---",
77
+ "title: Fixture Overall",
78
+ "doc-type: overall-spec",
79
+ "version: v1.0",
80
+ "date: 2026-10-09",
81
+ "status: Draft",
82
+ "---",
70
83
  "",
71
84
  "## Phase inventory",
72
85
  "",
@@ -98,43 +111,13 @@ const runNode = (args: string[], cwd: string): { code: number; stdout: string; s
98
111
  };
99
112
  };
100
113
 
101
- /** The capsule contract — the last stdout block carries the status capsule + the
102
- * `next:` suggestion line (the engine's single result surface). The route-face
103
- * words (v1.25 dispatch-ready literals: `done` terminal · `implement wave {tasks}`
104
- * · `review <type> <id> (base …)` · `fix <type> <id> --findings …` + the readback
105
- * suffix · the soft-cap message) — `none` is retired. */
106
- const assertCapsule = (stdout: string, command: string): void => {
107
- const lines = stdout.trim().split("\n");
108
- const capsule = lines.find((l) => l.startsWith("status:") && l.includes("blocker:"));
109
- assertOk(
110
- capsule !== undefined,
111
- `status capsule missing from ${command} stdout: ${JSON.stringify(stdout)}`,
112
- );
113
- assertOk(
114
- /^status: (APPROVED|BLOCKED|REVIEW_FIX|CHANGES_REQUESTED) · blocker: \d+ · handoff: /.test(
115
- capsule!,
116
- ),
117
- `status capsule malformed for ${command}: ${JSON.stringify(capsule)}`,
118
- );
119
- const next = lines.find((l) => l.startsWith("next:"));
120
- assertOk(
121
- next !== undefined && /^next: (done$|implement wave|review |fix($| )|BLOCKED:)/.test(next!),
122
- `next: line missing or malformed for ${command}: ${JSON.stringify(next)}`,
123
- );
124
- // Zero old-shape stdout key lines (the 4-line block is retired).
125
- assertOk(
126
- lines.every((l) => !/^(commits|artifacts|counters):/.test(l)),
127
- `old-shape stdout key line present for ${command}`,
128
- );
129
- };
130
-
131
114
  /** Run git in the fixture repo (the temp repo's commit identity is injected inline). */
132
115
  const git = (repo: string, ...args: string[]): void => {
133
116
  execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: "ignore" });
134
117
  };
135
118
 
136
- describe("the engine smoke — the source bin dry-run chain over a fixture repo", () => {
137
- it("boots the bin, asserts the `--help` face + the capsule contract on the dry-run chain", () => {
119
+ describe("the engine smoke — the source bin over a fixture repo", () => {
120
+ it("boots the bin, asserts the `--help` face + the read-only `--dry-run` preview (zero writes)", () => {
138
121
  const repoRoot = mkdtempSync(path.join(tmpdir(), "cdd-smoke-"));
139
122
  try {
140
123
  writeFileSync(path.join(repoRoot, ".gitignore"), ".kairos\n");
@@ -175,26 +158,26 @@ describe("the engine smoke — the source bin dry-run chain over a fixture repo"
175
158
  `--help missing the commander-native face (code ${helpOut.code}) stdout=${JSON.stringify(helpOut.stdout.slice(0, 120))} stderr=${JSON.stringify(helpOut.stderr.slice(0, 120))}`,
176
159
  );
177
160
 
178
- // The dry-run work chain — implement then review, each asserting the capsule.
179
- let stdout = "";
180
- const chain = [
181
- ["--dry-run", "implement", "--tasks", "1", "--plan", "fixture-plan.md"],
182
- ["--dry-run", "review", "--type", "wave", "--tasks", "1", "--plan", "fixture-plan.md"],
183
- ];
184
- for (const args of chain) {
185
- const res = runNode([BIN, ...args], repoRoot);
186
- assertOk(
187
- res.code === 0,
188
- `dry-run ${args.slice(1, 3).join(" ")} exited ${res.code}: ${res.stderr}`,
189
- );
190
- assertCapsule(res.stdout, args.join(" "));
191
- stdout += res.stdout;
192
- }
193
-
194
- // The fixture repo's workspace slug + the status capsule (the smoke.test.ts
195
- // assertions, migrated in place).
196
- expect(stdout).toContain("status:");
197
- expect(stdout).toContain(".kairos/cdd/fixture/");
161
+ // The `--dry-run` read-only preview — the release gate's zero-write face: the
162
+ // next dispatch step is forecast in five rows and nothing is written. The
163
+ // retired synthetic bookkeeping (a booked round + a fabricated capsule) is
164
+ // gone: a preview states the step, never a conclusion.
165
+ const preview = runNode(
166
+ [BIN, "--dry-run", "implement", "--tasks", "1", "--plan", "fixture-plan.md"],
167
+ repoRoot,
168
+ );
169
+ assertOk(preview.code === 0, `--dry-run implement exited ${preview.code}: ${preview.stderr}`);
170
+ assertOk(
171
+ preview.stdout.startsWith("cdd implement: preview (no repo changes)\n"),
172
+ `preview header missing: ${JSON.stringify(preview.stdout)}`,
173
+ );
174
+ for (const label of ["step:", "reads:", "would write:", "would record:", "child:"])
175
+ assertOk(preview.stdout.includes(` ${label} `), `preview row ${label} missing`);
176
+ // a preview fabricates no conclusion and no next hop
177
+ assertOk(!preview.stdout.includes("status:"), "preview must not print a status: line");
178
+ assertOk(!/^next:/m.test(preview.stdout), "preview must not print a next: line");
179
+ // zero repo writes — the engine workspace (and its slug) never appear
180
+ assertOk(!existsSync(path.join(repoRoot, ".kairos")), ".kairos/ must stay absent");
198
181
  } finally {
199
182
  rmSync(repoRoot, { recursive: true, force: true });
200
183
  }
@@ -0,0 +1,99 @@
1
+ // packages/cdd-engine/src-next/__tests__/support/strip-comments.ts
2
+ // The shared length-preserving comment/string stripper for the src-next source
3
+ // guards (P9 branch-review-1 F4 — one stripper, one home). Two guards read the
4
+ // engine's own source text and must ignore prose comments while still counting a
5
+ // token that lives inside a string literal (a `process.cwd()` quoted in code is a
6
+ // real occurrence; the same text in a `//` comment is not) — the structural pin
7
+ // (face/__tests__/repo-root.guard.test.ts) and the retired-plane guard
8
+ // (__tests__/zero-dep.test.ts) both ride this ONE implementation, so their
9
+ // hand-written heuristic boundary can never drift apart.
10
+ //
11
+ // The stripper preserves length and line count (a stripped comment collapses to
12
+ // blank chars, its line terminator survives) so a reported `line:col` hit stays
13
+ // true after stripping. It tracks string and template-literal interiors (never
14
+ // blanked — a token inside a string is a real occurrence) and regex-literal
15
+ // bodies (so a backtick inside `/`+…`/` never desyncs the string tracker).
16
+ //
17
+ // Documented heuristic boundary: a template literal's `${ … }` nesting is not
18
+ // tracked, so a backtick inside an interpolation closes the outer template early.
19
+ //
20
+ // Zero module-level bare functions — the strip/regex-may-start pair are `const`
21
+ // arrows (the plan's zero-`function`-declaration discipline).
22
+
23
+ /** Whether a `/` at `previous` (the last non-space code char, "" at file start)
24
+ * may open a regex literal rather than being a division operator. */
25
+ const regexMayStart = (previous: string): boolean =>
26
+ previous === "" || !/[A-Za-z0-9_$)\]]/.test(previous);
27
+
28
+ /** Strip line + block comments, preserving length and line count. The scan tracks
29
+ * string / template-literal interiors (kept verbatim — a symbol inside a string
30
+ * is a real occurrence, not prose) and regex-literal bodies (so a backtick inside
31
+ * `/`+…`/` never desyncs the string tracker); a `//` inside a string or template
32
+ * therefore never truncates the line. See the module header for the documented
33
+ * interpolation-nesting boundary. */
34
+ export const stripComments = (source: string): string => {
35
+ const out = source.split("");
36
+ let index = 0;
37
+ let previous = "";
38
+ while (index < source.length) {
39
+ const char = source[index]!;
40
+ const next = source[index + 1];
41
+ if (char === "/" && next === "/") {
42
+ while (index < source.length && source[index] !== "\n") {
43
+ out[index] = "";
44
+ index += 1;
45
+ }
46
+ } else if (char === "/" && next === "*") {
47
+ out[index] = "";
48
+ out[index + 1] = "";
49
+ index += 2;
50
+ while (index < source.length && !(source[index] === "*" && source[index + 1] === "/")) {
51
+ if (source[index] !== "\n") out[index] = "";
52
+ index += 1;
53
+ }
54
+ if (index < source.length) {
55
+ out[index] = "";
56
+ out[index + 1] = "";
57
+ index += 2;
58
+ }
59
+ } else if (char === "'" || char === '"' || char === "`") {
60
+ const quote = char;
61
+ index += 1;
62
+ while (index < source.length && source[index] !== quote) {
63
+ if (source[index] === "\\") index += 1;
64
+ index += 1;
65
+ }
66
+ index += 1;
67
+ } else if (char === "/" && regexMayStart(previous)) {
68
+ index += 1;
69
+ let inClass = false;
70
+ while (index < source.length) {
71
+ const inner = source[index]!;
72
+ if (inner === "\\") {
73
+ index += 2;
74
+ continue;
75
+ }
76
+ if (inner === "[") {
77
+ inClass = true;
78
+ index += 1;
79
+ continue;
80
+ }
81
+ if (inner === "]") {
82
+ inClass = false;
83
+ index += 1;
84
+ continue;
85
+ }
86
+ if (inner === "/" && !inClass) {
87
+ index += 1;
88
+ break;
89
+ }
90
+ if (inner === "\n") break;
91
+ index += 1;
92
+ }
93
+ } else {
94
+ if (char.trim() !== "") previous = char;
95
+ index += 1;
96
+ }
97
+ }
98
+ return out.join("");
99
+ };