@oscaner-skills/cdd-engine 1.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 (120) hide show
  1. package/README.md +11 -10
  2. package/README.zh-CN.md +11 -10
  3. package/package.json +16 -22
  4. package/src-next/__tests__/bin.test.ts +128 -0
  5. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  6. package/src-next/__tests__/floor.guard.test.ts +69 -0
  7. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  8. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  9. package/src-next/__tests__/smoke.integration.test.ts +185 -0
  10. package/src-next/__tests__/support/strip-comments.ts +99 -0
  11. package/src-next/__tests__/zero-dep.test.ts +94 -0
  12. package/src-next/bin.ts +61 -0
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +256 -0
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +165 -0
  15. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +190 -0
  16. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +106 -0
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +240 -0
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +165 -0
  19. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +190 -0
  20. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +100 -0
  21. package/src-next/contract/__tests__/declare.test.ts +481 -0
  22. package/src-next/contract/__tests__/doc.test.ts +527 -0
  23. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  24. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  25. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  26. package/src-next/contract/__tests__/judge.test.ts +1111 -0
  27. package/src-next/contract/__tests__/lint.test.ts +324 -0
  28. package/src-next/contract/__tests__/project.test.ts +460 -0
  29. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  30. package/src-next/contract/__tests__/translate.test.ts +96 -0
  31. package/src-next/contract/declare.ts +1071 -0
  32. package/src-next/contract/doc.ts +816 -0
  33. package/src-next/contract/frontmatter.ts +233 -0
  34. package/src-next/contract/home-extractors.ts +397 -0
  35. package/src-next/contract/invariants.ts +1413 -0
  36. package/src-next/contract/judge.ts +151 -0
  37. package/src-next/contract/lint.ts +239 -0
  38. package/src-next/contract/project.ts +656 -0
  39. package/src-next/contract/skill-anatomy.ts +301 -0
  40. package/src-next/contract/translate.ts +113 -0
  41. package/src-next/face/__tests__/board-view.test.ts +1151 -0
  42. package/src-next/face/__tests__/capsule.test.ts +300 -0
  43. package/src-next/face/__tests__/channel-closure.guard.test.ts +129 -0
  44. package/src-next/face/__tests__/cli.test.ts +4897 -0
  45. package/src-next/face/__tests__/face.test.ts +289 -0
  46. package/src-next/face/__tests__/graph-view.test.ts +61 -0
  47. package/src-next/face/__tests__/host.test.ts +24 -0
  48. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  49. package/src-next/face/__tests__/negation.ts +6 -0
  50. package/src-next/face/__tests__/preview.test.ts +374 -0
  51. package/src-next/face/__tests__/projection.test.ts +303 -0
  52. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  53. package/src-next/face/__tests__/termination.test.ts +650 -0
  54. package/src-next/face/__tests__/words.guard.test.ts +93 -0
  55. package/src-next/face/artifacts.ts +248 -0
  56. package/src-next/face/board-view.ts +652 -0
  57. package/src-next/face/capsule.ts +163 -0
  58. package/src-next/face/cli.ts +1028 -0
  59. package/src-next/face/declare.ts +323 -0
  60. package/src-next/face/gate.ts +171 -0
  61. package/src-next/face/graph-view.ts +74 -0
  62. package/src-next/face/host.ts +302 -0
  63. package/src-next/face/lifecycle.ts +725 -0
  64. package/src-next/face/preview.ts +151 -0
  65. package/src-next/face/projection.ts +285 -0
  66. package/src-next/face/route-render.ts +185 -0
  67. package/src-next/face/termination.ts +573 -0
  68. package/src-next/face/words.ts +314 -0
  69. package/src-next/infra/__tests__/infra.test.ts +333 -0
  70. package/src-next/infra/__tests__/root.test.ts +56 -0
  71. package/src-next/infra/config.ts +42 -0
  72. package/src-next/infra/doc-roots.ts +29 -0
  73. package/src-next/infra/git.ts +39 -0
  74. package/src-next/infra/process.ts +34 -0
  75. package/src-next/infra/root.ts +73 -0
  76. package/src-next/infra/runtime.ts +132 -0
  77. package/src-next/infra/workspace.ts +322 -0
  78. package/src-next/render/__tests__/render.test.ts +550 -0
  79. package/src-next/render/__tests__/skeleton.test.ts +684 -0
  80. package/src-next/render/brief.ts +121 -0
  81. package/src-next/render/issue-body.ts +162 -0
  82. package/src-next/render/skeleton.ts +502 -0
  83. package/src-next/render/templates.ts +645 -0
  84. package/src-next/session/__tests__/graph.test.ts +277 -0
  85. package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
  86. package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
  87. package/src-next/session/__tests__/ledger.test.ts +745 -0
  88. package/src-next/session/__tests__/next.test.ts +460 -0
  89. package/src-next/session/__tests__/preflight.test.ts +545 -0
  90. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  91. package/src-next/session/__tests__/run.test.ts +1026 -0
  92. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
  93. package/src-next/session/__tests__/wave.test.ts +476 -0
  94. package/src-next/session/faces.ts +110 -0
  95. package/src-next/session/graph.ts +411 -0
  96. package/src-next/session/handoff-schema.ts +373 -0
  97. package/src-next/session/ledger.ts +1076 -0
  98. package/src-next/session/next.ts +293 -0
  99. package/src-next/session/preflight.ts +271 -0
  100. package/src-next/session/round-naming.ts +84 -0
  101. package/src-next/session/run.ts +610 -0
  102. package/src-next/session/state.ts +30 -0
  103. package/src-next/session/wave.ts +139 -0
  104. package/templates/report/issue-body.json +17 -65
  105. package/dist/chunks/branch.mjs +0 -480
  106. package/dist/chunks/docs.mjs +0 -253
  107. package/dist/chunks/task.mjs +0 -913
  108. package/dist/cli.mjs +0 -5457
  109. package/dist/documents/schema/add-phase-protocol.json +0 -126
  110. package/dist/documents/schema/overall.json +0 -361
  111. package/dist/documents/schema/phase-spec.json +0 -145
  112. package/dist/documents/schema/plan.json +0 -191
  113. package/dist/documents/schema/skill-anatomy.json +0 -233
  114. package/dist/resources/harness-registry.json +0 -49
  115. package/dist/shared/cdd-engine.liioziig.mjs +0 -184
  116. package/templates/engine-config.json +0 -302
  117. package/templates/schema/cache-profile-schema.json +0 -23
  118. package/templates/schema/docs-handoff-schema.json +0 -129
  119. package/templates/schema/task-handoff-schema.json +0 -332
  120. package/templates/template-contract.json +0 -231
package/README.md CHANGED
@@ -2,15 +2,15 @@
2
2
 
3
3
  [English](README.md) | [中文](README.zh-CN.md)
4
4
 
5
- CDD engine CLI — the task runner, document/branch reviewer, and harness dispatcher behind the osuperpowers `cli-driven-development` skill. Published as a standalone package so the engine (`cdd`) can be installed and invoked on its own.
5
+ CDD engine CLI — the task runner, document/branch reviewer, and harness dispatcher behind the kairos `cdd-dev` skill. Published as a standalone package so the engine (`cdd`) can be installed and invoked on its own.
6
6
 
7
7
  ## What this package is
8
8
 
9
- The engine runs the implement / review / fix phases of the CDD workflow against a plan file, writes the dispatch's handoff artifacts, reads and writes the `base-branch` artifact, and dispatches each phase to the host harness CLI through its embedded harness registry. It is consumed by the [osuperpowers plugin](https://www.npmjs.com/package/@oscaner-skills/osuperpowers)'s `cli-driven-development` skill and is also usable directly from the command line.
9
+ The engine runs the implement / review / fix phases of the CDD workflow against a plan file, writes the dispatch's handoff artifacts, reads and writes the `base` artifact, and dispatches each phase to the host harness CLI through its embedded harness registry. It is consumed by the [kairos plugin](https://www.npmjs.com/package/@oscaner-skills/kairos)'s `cdd-dev` skill and is also usable directly from the command line.
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,30 +22,31 @@ 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
  |------------|-------|---------|
29
29
  | `implement` | `cdd implement --tasks=<n> [--plan=<path>]` | Run the task implement phase |
30
30
  | `review` | `cdd review --type=<task\|branch\|spec\|plan>` | Run a review — task, branch, spec, or plan |
31
31
  | `fix` | `cdd fix --type=<task\|branch\|spec\|plan>` | Fix review findings — task, branch, spec, or plan |
32
- | `base-branch` | `cdd base-branch set\|get` | Read/write the `base-branch.json` artifact (single CDD `--plan` target) |
32
+ | `base` | `cdd base set\|get` | Read/write the `base.json` artifact (single CDD `--plan` target) |
33
33
  | `schema` | `cdd schema get <type>` | Print the canonical doc-structure schema (discovery-only, zero enforcement) |
34
34
  | `issue` | `cdd issue render` | Render an aggregate issue body from stdin findings (pure rendering, zero enforcement) |
35
+ | `board` | `cdd board <slug>` | Render the slug progress board (overall/spec/plan/wave/branch; pure read, zero enforcement) |
35
36
 
36
- Use `cdd <command> --help` for a command's full option list (for example `cdd review --tasks` / `--base` / `--head` / `--spec` / `--round`).
37
+ Use `cdd <command> --help` for a command's full option list (for example `cdd review --tasks` / `--spec` / `--plan` / `--round`).
37
38
 
38
39
  ## Development
39
40
 
40
- The package lives in the [Oscaner/skills](https://github.com/Oscaner/skills) monorepo at `packages/cdd-engine` (TypeScript, built with unbuild, tested with vitest; tests are colocated at `src/**/__tests__/**/*.test.ts`).
41
+ The package lives in the [Oscaner/skills](https://github.com/Oscaner/skills) monorepo at `packages/cdd-engine` (TypeScript, emitted with `tsc -p tsconfig.build.json`, tested with vitest; tests are colocated at `src-next/**/__tests__/**/*.test.ts`).
41
42
 
42
43
  ```bash
43
- pnpm --filter @oscaner-skills/cdd-engine dev:stub # rebuild the jiti immediate-load dev stub
44
- node packages/cdd-engine/dist/cli.mjs schema get plan # invoke the engine from the working tree
44
+ node packages/cdd-engine/src-next/bin.ts schema get plan # invoke the engine source-direct from the working tree (Node ≥22.18 native type stripping)
45
45
  pnpm --filter @oscaner-skills/cdd-engine test # run the engine test suite
46
+ pnpm --filter @oscaner-skills/cdd-engine build # tsc-emit the published dist/bin.js
46
47
  ```
47
48
 
48
- During repository development the engine is invoked straight from the working tree (`dist/cli.mjs`) — never through a global install or link, which can go stale.
49
+ During repository development the engine is invoked straight on the source entry (`node packages/cdd-engine/src-next/bin.ts`) — never through a global install or link, which can go stale.
49
50
 
50
51
  ## License
51
52
 
package/README.zh-CN.md CHANGED
@@ -4,15 +4,15 @@
4
4
 
5
5
  [English](README.md) | [中文](README.zh-CN.md)
6
6
 
7
- CDD 引擎 CLI——osuperpowers `cli-driven-development` 技能背后的任务运行器、文档/分支评审器与 harness 派发器。以独立包发布,使引擎(`cdd`)可单独安装与调用。
7
+ CDD 引擎 CLI——kairos `cdd-dev` 技能背后的任务运行器、文档/分支评审器与 harness 派发器。以独立包发布,使引擎(`cdd`)可单独安装与调用。
8
8
 
9
9
  ## 包定位
10
10
 
11
- 引擎针对计划文件运行 CDD 工作流的 implement / review / fix 阶段,写出派发的 handoff 产物,读写 `base-branch` 产物,并通过其内嵌的 harness 注册表将每个阶段派发给宿主 harness CLI。它被 [osuperpowers 插件](https://www.npmjs.com/package/@oscaner-skills/osuperpowers)的 `cli-driven-development` 技能消费,也可直接从命令行使用。
11
+ 引擎针对计划文件运行 CDD 工作流的 implement / review / fix 阶段,写出派发的 handoff 产物,读写 `base` 产物,并通过其内嵌的 harness 注册表将每个阶段派发给宿主 harness CLI。它被 [kairos 插件](https://www.npmjs.com/package/@oscaner-skills/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,30 +24,31 @@ 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
  |--------|------|------|
31
31
  | `implement` | `cdd implement --tasks=<n> [--plan=<path>]` | 运行任务 implement 阶段 |
32
32
  | `review` | `cdd review --type=<task\|branch\|spec\|plan>` | 运行评审——task、branch、spec 或 plan |
33
33
  | `fix` | `cdd fix --type=<task\|branch\|spec\|plan>` | 修复评审发现——task、branch、spec 或 plan |
34
- | `base-branch` | `cdd base-branch set\|get` | 读写 `base-branch.json` 产物(单一 CDD `--plan` 目标) |
34
+ | `base` | `cdd base set\|get` | 读写 `base.json` 产物(单一 CDD `--plan` 目标) |
35
35
  | `schema` | `cdd schema get <type>` | 打印 canonical 文档结构 schema(发现型、零执法) |
36
36
  | `issue` | `cdd issue render` | 依据 stdin 发现渲染聚合 issue 正文(纯渲染、零执法) |
37
+ | `board` | `cdd board <slug>` | 渲染 slug 进度板(overall/spec/plan/wave/branch;纯读、零执法) |
37
38
 
38
- 用 `cdd <command> --help` 查看某命令的完整选项列表(例如 `cdd review --tasks` / `--base` / `--head` / `--spec` / `--round`)。
39
+ 用 `cdd <command> --help` 查看某命令的完整选项列表(例如 `cdd review --tasks` / `--spec` / `--plan` / `--round`)。
39
40
 
40
41
  ## 开发说明
41
42
 
42
- 包位于 [Oscaner/skills](https://github.com/Oscaner/skills) monorepo 的 `packages/cdd-engine`(TypeScript,unbuild 构建,vitest 测试;测试与源码同地放置于 `src/**/__tests__/**/*.test.ts`)。
43
+ 包位于 [Oscaner/skills](https://github.com/Oscaner/skills) monorepo 的 `packages/cdd-engine`(TypeScript,`tsc -p tsconfig.build.json` 发布构建,vitest 测试;测试与源码同地放置于 `src-next/**/__tests__/**/*.test.ts`)。
43
44
 
44
45
  ```bash
45
- pnpm --filter @oscaner-skills/cdd-engine dev:stub # 重建 jiti 即时加载开发 stub
46
- node packages/cdd-engine/dist/cli.mjs schema get plan # 从工作树直接调用引擎
46
+ node packages/cdd-engine/src-next/bin.ts schema get plan # 从工作树源面直接调用引擎(Node ≥22.18 原生类型剥离)
47
47
  pnpm --filter @oscaner-skills/cdd-engine test # 运行引擎测试套件
48
+ pnpm --filter @oscaner-skills/cdd-engine build # tsc 构建发布产物 dist/bin.js
48
49
  ```
49
50
 
50
- 仓库开发期间引擎须从工作树直接调用(`dist/cli.mjs`)——绝不要经全局安装或链接,可能过期。
51
+ 仓库开发期间引擎须从源面直调(`node packages/cdd-engine/src-next/bin.ts`)——绝不要经全局安装或链接,可能过期。
51
52
 
52
53
  ## 许可
53
54
 
package/package.json CHANGED
@@ -1,40 +1,34 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "1.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": {
7
- "node": ">=22.12.0"
7
+ "node": ">=24"
8
8
  },
9
9
  "files": [
10
- "dist/",
10
+ "src-next/",
11
11
  "templates/"
12
12
  ],
13
- "main": "./dist/cli.mjs",
13
+ "main": "./src-next/bin.ts",
14
14
  "exports": {
15
- ".": "./dist/cli.mjs",
15
+ ".": "./src-next/bin.ts",
16
16
  "./package.json": "./package.json"
17
17
  },
18
18
  "bin": {
19
- "cdd": "./dist/cli.mjs"
19
+ "cdd": "./src-next/bin.ts"
20
20
  },
21
21
  "dependencies": {
22
- "ajv": "^8.20.0",
23
- "citty": "^0.2.2",
24
- "consola": "^3.4.2",
25
- "execa": "^10.0.1",
26
- "handlebars": "^4.7.9",
27
- "hookable": "^6.1.2",
28
- "semver": "^7.8.5",
29
- "simple-git": "^3.36.0",
30
- "tinyglobby": "^0.2.17"
22
+ "commander": "^15.0.0",
23
+ "execa": "^10.1.1",
24
+ "jsonc-parser": "^3.3.1",
25
+ "simple-git": "^4.0.2",
26
+ "yaml": "^2.9.1"
31
27
  },
32
28
  "devDependencies": {
33
- "@types/node": "^26.6.2",
34
- "@typescript/typescript6": "^6.0.2",
29
+ "@types/node": "^24.19.2",
35
30
  "typescript": "^7.0.2",
36
- "unbuild": "^3.6.1",
37
- "vitest": "^5.0.1"
31
+ "vitest": "^5.0.5"
38
32
  },
39
33
  "repository": {
40
34
  "type": "git",
@@ -43,9 +37,9 @@
43
37
  },
44
38
  "license": "MIT",
45
39
  "scripts": {
46
- "build": "unbuild",
47
- "dev:stub": "unbuild --stub",
40
+ "build": "rm -rf dist && tsc -p tsconfig.build.json",
48
41
  "test": "vitest run",
49
- "test:watch": "vitest"
42
+ "test:watch": "vitest",
43
+ "smoke": "vitest run src-next/__tests__/smoke.integration.test.ts"
50
44
  }
51
45
  }
@@ -0,0 +1,128 @@
1
+ // packages/cdd-engine/src-next/__tests__/bin.test.ts
2
+ // T13 — the bin-bootstrap face, black-box: the thin entry's cli-load + exit-code
3
+ // plumbing exercised exactly the way the checkable runs it (`node src-next/bin.ts …`).
4
+ // Spawns the source entry straight (Node >=22.18 native type stripping — the dev
5
+ // face; the test asserts through the steady exit-code table — 0 = OK · 2 = usage —
6
+ // not through anything imported in-process: the bin is only ever executed, never
7
+ // imported).
8
+
9
+ import { spawnSync } from "node:child_process";
10
+ import { readFileSync } from "node:fs";
11
+ import process from "node:process";
12
+ import { fileURLToPath } from "node:url";
13
+ import { describe, expect, it } from "vitest";
14
+
15
+ const BIN = fileURLToPath(new URL("../bin.ts", import.meta.url));
16
+
17
+ /** One spawned bin run — fail-open (a non-zero child rides the code, never a throw;
18
+ * the child's streams are piped, never inherited into the reporter). */
19
+ const run = (
20
+ args: readonly string[],
21
+ opts: { cwd?: string; input?: string } = {},
22
+ ): { code: number; stdout: string; stderr: string } => {
23
+ const result = spawnSync(process.execPath, [BIN, ...args], {
24
+ encoding: "utf8",
25
+ cwd: opts.cwd ?? process.cwd(),
26
+ input: opts.input,
27
+ stdio: ["pipe", "pipe", "pipe"],
28
+ });
29
+ return {
30
+ code: result.status ?? (result.error !== undefined ? 1 : 0),
31
+ stdout: result.stdout ?? "",
32
+ stderr: result.stderr ?? "",
33
+ };
34
+ };
35
+
36
+ describe("the T9 deliberate pin — the NodeEnvGuard + Cli.create entry (the class-face boot)", () => {
37
+ it("the entry is the NodeEnvGuard class member + the Cli.create factory — zero module-level functions in bin.ts", () => {
38
+ // bin.ts is only ever executed, never imported, so the entry form is pinned
39
+ // from its source: the environment pre-flight is a class static judgement and
40
+ // the CLI face boots through the Cli.create static factory — a regression to a
41
+ // module-level `bootEnvironmentProblem`/`cli` function trips this pin.
42
+ const src = readFileSync(BIN, "utf8");
43
+ expect(src).not.toMatch(/^(export )?(async )?function /m);
44
+ expect(src).toMatch(/class NodeEnvGuard/);
45
+ expect(src).toMatch(/NodeEnvGuard\.problem\(\)/);
46
+ expect(src).toMatch(/const \{ Cli \} = await import\("\.\/face\/cli\.ts"\)/);
47
+ expect(src).toMatch(/Cli\.create\(\)\.runArgv/);
48
+ });
49
+
50
+ it("the environment guard's message + exit bytes are pinned (the below-floor word face)", () => {
51
+ const src = readFileSync(BIN, "utf8");
52
+ // The byte message is produced from the NODE_FLOOR row — both the floor and the
53
+ // template production are pinned so the below-floor word face cannot drift.
54
+ expect(src).toContain("const NODE_FLOOR = { major: 22, minor: 18 } as const;");
55
+ expect(src).toMatch(
56
+ /cdd requires Node >= \$\{NODE_FLOOR\.major\}\.\$\{NODE_FLOOR\.minor\} \(native type stripping\) — installed: \$\{process\.versions\.node\}/,
57
+ );
58
+ expect(src).toContain("process.exit(1)");
59
+ });
60
+ });
61
+
62
+ describe("the bin bootstrap — cli load + exit-code plumbing (black-box)", () => {
63
+ it("`node src-next/bin.ts schema get plan` prints the derived plan schema + exits 0 (the T13 checkable)", () => {
64
+ const result = run(["schema", "get", "plan"]);
65
+ expect(result.code).toBe(0);
66
+ const parsed = JSON.parse(result.stdout) as {
67
+ docType: string;
68
+ $schema: string;
69
+ properties: Record<string, unknown>;
70
+ };
71
+ // The derived doc-structure schema — the registration-derived face, never a
72
+ // hand-written second schema.
73
+ expect(parsed.docType).toBe("plan");
74
+ expect(parsed.$schema).toContain("json-schema.org");
75
+ expect(parsed.properties).toBeTypeOf("object");
76
+ expect(Object.keys(parsed.properties).length).toBeGreaterThan(0);
77
+ });
78
+
79
+ it("an unknown flag exits 2 with commander's unknown-option byte + the native did-you-mean (the guardArgs semantics ride the bin)", () => {
80
+ // the required flags must be satisfied first — commander's missing-required
81
+ // check fires before the unknown-option scan, so the typo surfaces only with
82
+ // --tasks/--plan present
83
+ const result = run(["implement", "--tasks", "2", "--plan", "p.md", "--taks"]);
84
+ expect(result.code).toBe(2);
85
+ expect(result.stderr).toContain("error: unknown option '--taks'");
86
+ expect(result.stderr).toContain("(Did you mean --tasks?)");
87
+ });
88
+
89
+ it("an unknown command exits 2 with commander's unknown-command byte", () => {
90
+ const result = run(["bogus"]);
91
+ expect(result.code).toBe(2);
92
+ expect(result.stderr).toContain("error: unknown command 'bogus'");
93
+ });
94
+
95
+ it("a missing required flag exits 2 with the .requiredOption() byte (base get's required --plan)", () => {
96
+ const result = run(["base", "get"]);
97
+ expect(result.code).toBe(2);
98
+ expect(result.stderr).toContain("error: required option '--plan <path>' not specified");
99
+ });
100
+
101
+ it("`node src-next/bin.ts issue render` renders the aggregate body from stdin + exits 0", () => {
102
+ const input = JSON.stringify({
103
+ harness: "claude",
104
+ findings: [
105
+ {
106
+ type: "bug",
107
+ lang: "en",
108
+ context: "c",
109
+ problem: "p",
110
+ impact: "i",
111
+ suggestedFix: "f",
112
+ meta: { skill: "tdd", step: "loop" },
113
+ },
114
+ ],
115
+ });
116
+ const result = run(["issue", "render"], { input });
117
+ expect(result.code).toBe(0);
118
+ expect(result.stdout).toContain("# CDD aggregate issue");
119
+ expect(result.stdout).toContain("## Context");
120
+ expect(result.stdout).toContain("- Skill: tdd");
121
+ });
122
+
123
+ it("issue render rejects malformed input JSON with exit 1 (the input-value failure surface)", () => {
124
+ const result = run(["issue", "render"], { input: "not json" });
125
+ expect(result.code).toBe(1);
126
+ expect(result.stderr).toContain("invalid input JSON");
127
+ });
128
+ });
@@ -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
+ });