@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
@@ -23,6 +23,7 @@
23
23
  import { InvalidArgumentError } from "commander";
24
24
 
25
25
  import type { DocKey } from "../contract/project.ts";
26
+ import { ENGINE_DOC_ROOTS } from "../infra/doc-roots.ts";
26
27
 
27
28
  /** The component-value types of the argv channel (the CLI parse validates by these). */
28
29
  export type ChannelValueType = "string" | "path" | "int-list" | "enum" | "int" | "bool";
@@ -52,8 +53,8 @@ export interface ChannelArgRow {
52
53
  export const ARGV_CHANNEL = {
53
54
  plan: { flag: "--plan", type: "path", help: "the CDD plan document path" },
54
55
  spec: { flag: "--spec", type: "path", help: "the design-spec document path" },
55
- findings: {
56
- flag: "--findings",
56
+ reviews: {
57
+ flag: "--reviews",
57
58
  type: "path",
58
59
  help: "the source review handoff JSON path",
59
60
  },
@@ -81,7 +82,7 @@ export const ARGV_CHANNEL = {
81
82
  flag: "--dry-run",
82
83
  type: "bool",
83
84
  scope: "program",
84
- help: "synthetic dispatch — book the round without a child spawn",
85
+ help: "preview the next dispatch step and its expected artifacts — zero repo writes, no round consumed (implement/review/fix only)",
85
86
  },
86
87
  help: {
87
88
  flag: "--help",
@@ -90,11 +91,6 @@ export const ARGV_CHANNEL = {
90
91
  scope: "program",
91
92
  help: "show this help",
92
93
  },
93
- root: {
94
- flag: "--root",
95
- type: "path",
96
- help: "the repository root (default: the current git top level)",
97
- },
98
94
  output: {
99
95
  flag: "--output",
100
96
  type: "enum",
@@ -199,39 +195,40 @@ export const CLI_COMMANDS: readonly CliCommandSpec[] = [
199
195
  {
200
196
  name: "implement",
201
197
  description: "run the task implement phase",
202
- example: "cdd implement --tasks 1,2 --plan docs/kairos/plans/p3.md",
203
- keys: [{ key: "tasks", required: true }, { key: "plan", required: true }, { key: "root" }],
198
+ example: `cdd implement --tasks 1,2 --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
199
+ keys: [
200
+ { key: "tasks", required: true },
201
+ { key: "plan", required: true },
202
+ ],
204
203
  },
205
204
  {
206
205
  name: "review",
207
206
  description: "run a review — task | branch | spec | plan",
208
- example: "cdd review --type spec --spec docs/kairos/specs/p3-design.md",
207
+ example: `cdd review --type spec --spec ${ENGINE_DOC_ROOTS.specs}/p3-design.md`,
209
208
  keys: [
210
209
  { key: "type", required: true },
211
210
  { key: "tasks" },
212
211
  { key: "plan" },
213
212
  { key: "spec" },
214
213
  { key: "round" },
215
- { key: "root" },
216
214
  ],
217
215
  },
218
216
  {
219
217
  name: "fix",
220
218
  description: "fix review findings — task | branch | spec | plan",
221
- example: "cdd fix --type wave --tasks 1 --findings tasks-1-review-1.json",
219
+ example: "cdd fix --type wave --tasks 1 --reviews tasks-1-review-1.json",
222
220
  keys: [
223
221
  { key: "type", required: true },
224
222
  { key: "tasks" },
225
- { key: "findings" },
223
+ { key: "reviews" },
226
224
  { key: "spec" },
227
225
  { key: "plan" },
228
- { key: "root" },
229
226
  ],
230
227
  },
231
228
  {
232
229
  name: "base",
233
230
  description: "read/write base.json (single CDD --plan target)",
234
- example: "cdd base set --plan docs/kairos/plans/p3.md --base develop --source plan-field",
231
+ example: `cdd base set --plan ${ENGINE_DOC_ROOTS.plans}/p3.md --base develop --source plan-field`,
235
232
  keys: [],
236
233
  leaves: [
237
234
  {
@@ -283,7 +280,7 @@ export const CLI_COMMANDS: readonly CliCommandSpec[] = [
283
280
  name: "board",
284
281
  description: "render the slug progress board (overall/spec/plan/wave/branch)",
285
282
  example: "cdd board 2026-10-10-engine-doc-tooling-p7",
286
- keys: [{ key: "root" }],
283
+ keys: [],
287
284
  positionals: [{ key: "slug", required: true }],
288
285
  },
289
286
  ];
@@ -321,6 +318,6 @@ export const REQUIRED_GROUPS: Readonly<
321
318
  wave: ["--plan"],
322
319
  spec: ["--spec"],
323
320
  plan: ["--plan"],
324
- branch: ["--findings", "--plan"],
321
+ branch: ["--reviews", "--plan"],
325
322
  },
326
323
  };
@@ -8,11 +8,12 @@
8
8
  // members moved verbatim — behavior bytes identical; the root Cli holds the gate
9
9
  // instance and composes through it via its .action thin shells (zero bare functions).
10
10
 
11
- import { readFileSync, writeFileSync } from "node:fs";
12
- import { MarkdownPrimitives } from "../contract/doc.ts";
11
+ import { readFileSync } from "node:fs";
12
+ import { FrontMatterExtractor } from "../contract/frontmatter.ts";
13
13
  import { BriefRenderer } from "../render/brief.ts";
14
14
  import type { DispatchPhase } from "../session/faces.ts";
15
15
  import type { DocRevisionRef } from "../session/ledger.ts";
16
+ import { RoundNaming } from "../session/round-naming.ts";
16
17
  import type { RunInput, WorkScene } from "./cli.ts";
17
18
 
18
19
  /**
@@ -53,7 +54,7 @@ export class CliGate {
53
54
  verdict: "same" | "pending-fix" | null;
54
55
  reviewed: DocRevisionRef | null;
55
56
  } {
56
- if (scene.target?.kind === "doc") {
57
+ if (scene.target?.kind === "plan" || scene.target?.kind === "spec") {
57
58
  const key = this.#lineKey(scene);
58
59
  if (key === null) return { phase: null, verdict: null, reviewed: null };
59
60
  const verdict = scene.ledger.reviewGate(key, scene.target.doc, scene.face.type);
@@ -86,7 +87,8 @@ export class CliGate {
86
87
  * method family). Null off that face or with no identity ("target revision
87
88
  * unchanged" is a present fact only there). */
88
89
  docLineBlock(scene: WorkScene, reviewed: DocRevisionRef | null): string | null {
89
- if (reviewed === null || scene.target?.kind !== "doc") return null;
90
+ if (reviewed === null || (scene.target?.kind !== "plan" && scene.target?.kind !== "spec"))
91
+ return null;
90
92
  const version = this.#docVersionOf(this.#docContent(scene.target.doc));
91
93
  return `${scene.type} already reviewed at ${version ?? "the current version"} (doc-hash ${reviewed.doc_hash.slice(0, 12)}…) — target revision unchanged; amend body/version to open a new review`;
92
94
  }
@@ -98,7 +100,8 @@ export class CliGate {
98
100
  * Review Convergence anti-spin); the message names the reviewed identity the
99
101
  * gate judged. */
100
102
  pendingFixBlock(scene: WorkScene, reviewed: DocRevisionRef | null): string | null {
101
- if (reviewed === null || scene.target?.kind !== "doc") return null;
103
+ if (reviewed === null || (scene.target?.kind !== "plan" && scene.target?.kind !== "spec"))
104
+ return null;
102
105
  return `the pending fix applies to the unchanged doc (doc-hash ${reviewed.doc_hash.slice(0, 12)}…) — run cdd fix first`;
103
106
  }
104
107
 
@@ -113,9 +116,12 @@ export class CliGate {
113
116
  renderBrief(scene: WorkScene, parsed: RunInput): string {
114
117
  const tasks = this.tasksOf(parsed);
115
118
  const content = this.#brief.render(scene.planText!, tasks);
116
- const briefPath = scene.workspace.resolve(`tasks-${parsed.args.tasks}-brief.md`);
117
- writeFileSync(briefPath, content, "utf8");
118
- return briefPath;
119
+ // The real run's workspace is built by the single write point (`Cli#runWork`'s
120
+ // ensure, P11 · §4.2) BEFORE this render; the write still rides the workspace's
121
+ // own text-write face (the `writeJson` mkdir-before-write pattern), never a
122
+ // second explicit `ensure()` — no bare `writeFileSync` into a possibly absent dir.
123
+ const name = new RoundNaming(scene.workspace).briefName(parsed.args.tasks ?? "");
124
+ return scene.workspace.writeText(name, content);
119
125
  }
120
126
 
121
127
  /** The single-target line's current open phase — fix-awaits / re-review / closure
@@ -135,7 +141,7 @@ export class CliGate {
135
141
  * the lifecycle's own key derivation (run.ts #lineKey). */
136
142
  #lineKey(scene: WorkScene): string | null {
137
143
  if (scene.target?.kind === "branch") return "branch";
138
- if (scene.target?.kind === "doc") return scene.face.type;
144
+ if (scene.target?.kind === "plan" || scene.target?.kind === "spec") return scene.face.type;
139
145
  return null;
140
146
  }
141
147
 
@@ -155,16 +161,11 @@ export class CliGate {
155
161
  }
156
162
  }
157
163
 
158
- /** The doc's `v<major>.<minor>` version token — the first token on the
159
- * `**Version**` header line (the shared version-token grammar's one home —
160
- * MarkdownPrimitives.versionTokensOf · contract/doc.ts). */
164
+ /** The doc's `v<major>.<minor>` version token — the front-matter `version:`
165
+ * scalar (the T6 read point: the header version facts ride the typed head
166
+ * record — the fence split + `yaml` engine, never a line scan). */
161
167
  #docVersionOf(content: string | null): string | null {
162
168
  if (content === null) return null;
163
- for (const line of content.split("\n")) {
164
- if (line.trimStart().startsWith("- **Version**:")) {
165
- return MarkdownPrimitives.versionTokensOf(line)[0] ?? null;
166
- }
167
- }
168
- return null;
169
+ return FrontMatterExtractor.split(content).head.version;
169
170
  }
170
171
  }
@@ -5,7 +5,7 @@
5
5
  // imported, never parsed:
6
6
  //
7
7
  // · HOSTS — the per-harness rows (cli / invoke / promptForm / output / ship /
8
- // detect / install / cache). The host-marker closure is single-sourced HERE: the
8
+ // detect / install). The host-marker closure is single-sourced HERE: the
9
9
  // detect rows are the only copy of the marker env keys (the channel audit derives
10
10
  // the env whitelist from them — never a second declaration). The promptForm
11
11
  // column (§3.5) is the prompt-position semantics data contract — how the
@@ -43,22 +43,6 @@ export interface HostDetectSpec {
43
43
  aiAgentPrefix?: string;
44
44
  }
45
45
 
46
- /** One host-cache row — the prompt-cache mechanism facts. */
47
- export interface HostCacheSpec {
48
- /** The cache mechanism (explicit hints / auto-prefix). */
49
- mechanism: string;
50
- /** The minimum token threshold; the `pending` literal is the not-yet-known marker. */
51
- minTokens: number | "pending";
52
- /** Explicit-hint face: the read/write budget multipliers + TTL (claude only). */
53
- readMultiplier?: number;
54
- /** Explicit-hint face: the write-budget multiplier (claude only). */
55
- writeMultiplier?: number;
56
- /** Explicit-hint face: the cache TTL in minutes (claude only). */
57
- ttlMinutes?: number;
58
- /** Whether the cache is observable to the engine. */
59
- observable: boolean;
60
- }
61
-
62
46
  /** The prompt-position semantics of a harness — HOW the skill-ref enters the child
63
47
  * prompt (the §3.5 data contract, resolved by #childPrompt — the from-code-assumed
64
48
  * prompt assembly becomes a per-host row). `ref-prefixed`: the slash ref prefixes
@@ -92,8 +76,6 @@ export interface HostRow {
92
76
  /** The per-package install banners (kairos self-install + upstream plugins);
93
77
  * `"pending"` is the literal not-yet-known command. */
94
78
  install: Readonly<Record<string, readonly string[] | "pending">>;
95
- /** The prompt-cache facts. */
96
- cache: HostCacheSpec;
97
79
  /** The capability facts — the tested dispatch-face columns (T25). */
98
80
  capabilities: HostCapabilities;
99
81
  }
@@ -135,7 +117,11 @@ export interface HostContract {
135
117
  }
136
118
 
137
119
  /** The per-harness install banners — the kairos self-install + the upstream plugin
138
- * install commands (the README upstream dependency table renders from these rows). */
120
+ * install commands. The `packages/kairos/README.md` upstream dependency table (and
121
+ * its zh mirror) renders from these rows; the engine-suite gate
122
+ * (face/__tests__/install-rows.guard.test.ts) pins each README row's Claude Code cell
123
+ * to `INSTALL_ROWS[key].join(";")` and the row key set to these keys — a README
124
+ * install-command drift fails there, never silently. */
139
125
  export const INSTALL_ROWS = {
140
126
  kairos: [
141
127
  "claude plugin marketplace add oscaner/skills",
@@ -165,14 +151,6 @@ export const HOSTS = {
165
151
  ship: "full",
166
152
  detect: { env: "CLAUDE_CODE_SESSION_ID", aiAgentPrefix: "claude-code" },
167
153
  install: INSTALL_ROWS,
168
- cache: {
169
- mechanism: "explicit",
170
- minTokens: 512,
171
- readMultiplier: 0.1,
172
- writeMultiplier: 1.25,
173
- ttlMinutes: 5,
174
- observable: true,
175
- },
176
154
  capabilities: { parallel: true },
177
155
  },
178
156
  cursor: {
@@ -188,7 +166,6 @@ export const HOSTS = {
188
166
  "mattpocock-skills": "pending",
189
167
  impeccable: "pending",
190
168
  },
191
- cache: { mechanism: "auto-prefix", minTokens: "pending", observable: false },
192
169
  capabilities: { parallel: "pending" },
193
170
  },
194
171
  pi: {
@@ -204,7 +181,6 @@ export const HOSTS = {
204
181
  "mattpocock-skills": ["pi install git:github.com/mattpocock/skills"],
205
182
  impeccable: ["npx impeccable install --providers=pi --scope=global -y"],
206
183
  },
207
- cache: { mechanism: "auto-prefix", minTokens: "pending", observable: false },
208
184
  capabilities: { parallel: "pending" },
209
185
  },
210
186
  } as const satisfies Readonly<Record<HostId, HostRow>>;