@oscaner-skills/cdd-engine 4.1.0 → 4.3.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 (59) hide show
  1. package/README.md +39 -9
  2. package/README.zh-CN.md +44 -9
  3. package/dist/contract/completion-criterion.js +351 -0
  4. package/dist/contract/declare.js +181 -43
  5. package/dist/contract/doc.js +84 -271
  6. package/dist/contract/frontmatter.js +2 -1
  7. package/dist/contract/home-extractors.js +49 -316
  8. package/dist/contract/invariants.js +400 -296
  9. package/dist/contract/judge.js +74 -49
  10. package/dist/contract/lint.js +3 -2
  11. package/dist/contract/liveness-signal.js +103 -0
  12. package/dist/contract/markdown-document.js +410 -0
  13. package/dist/contract/markdown-tree-types.js +6 -0
  14. package/dist/contract/markdown-tree.js +137 -0
  15. package/dist/contract/project.js +1 -1
  16. package/dist/contract/rules.js +106 -0
  17. package/dist/contract/selector-engine.js +332 -0
  18. package/dist/contract/selector-spec.js +74 -0
  19. package/dist/contract/skill-anatomy.js +29 -1
  20. package/dist/contract/task-block-grammar.js +285 -0
  21. package/dist/contract/task-blocks.js +65 -0
  22. package/dist/contract/translate.js +21 -0
  23. package/dist/contract/wave-width.js +15 -0
  24. package/dist/face/board-view.js +401 -131
  25. package/dist/face/capsule.js +66 -89
  26. package/dist/face/cli.js +174 -48
  27. package/dist/face/declare.js +59 -23
  28. package/dist/face/gate.js +117 -40
  29. package/dist/face/host.js +9 -35
  30. package/dist/face/init.js +108 -0
  31. package/dist/face/lifecycle.js +540 -123
  32. package/dist/face/plugins.js +73 -0
  33. package/dist/face/preview.js +43 -10
  34. package/dist/face/projection.js +3 -3
  35. package/dist/face/route-render.js +51 -21
  36. package/dist/face/termination.js +135 -261
  37. package/dist/face/words.js +134 -12
  38. package/dist/infra/atomic.js +15 -0
  39. package/dist/infra/git.js +25 -0
  40. package/dist/infra/proc.js +150 -0
  41. package/dist/infra/round-log.js +104 -0
  42. package/dist/infra/runtime.js +16 -4
  43. package/dist/infra/workspace.js +7 -2
  44. package/dist/render/brief.js +15 -17
  45. package/dist/render/skeleton.js +41 -28
  46. package/dist/render/templates.js +128 -84
  47. package/dist/session/faces.js +47 -20
  48. package/dist/session/graph.js +13 -37
  49. package/dist/session/handoff-schema.js +16 -8
  50. package/dist/session/inflight.js +282 -0
  51. package/dist/session/ledger.js +581 -136
  52. package/dist/session/line-identity.js +33 -0
  53. package/dist/session/next.js +138 -80
  54. package/dist/session/preflight.js +276 -68
  55. package/dist/session/round-naming.js +56 -8
  56. package/dist/session/run.js +317 -78
  57. package/dist/session/wave.js +94 -14
  58. package/package.json +13 -3
  59. package/dist/infra/process.js +0 -22
@@ -1,5 +1,5 @@
1
1
  // packages/cdd-engine/src-next/face/declare.ts
2
- // §2.4 — the CLI declaration single surface: the argv channel table, the seven-command
2
+ // §2.4 — the CLI declaration single surface: the argv channel table, the eight-command
3
3
  // declarations, every CLI face type and the conditional-required group table cohere
4
4
  // in ONE file (the user ruling 2026-10-11: the declaration was scattered across
5
5
  // runtime/registry/argv → one surface). The migration converges:
@@ -20,7 +20,9 @@
20
20
  // bare functions (the plan's zero-bare-function discipline); the projection
21
21
  // algorithm lives in the single CommandTreeBuilder class (face/projection.ts).
22
22
  import { InvalidArgumentError } from "commander";
23
+ import { MAX_TASKS_PER_WAVE } from "../contract/wave-width.js";
23
24
  import { ENGINE_DOC_ROOTS } from "../infra/doc-roots.js";
25
+ import { HOST_IDS } from "./host.js";
24
26
  /** The argv channel table — the CLI flag/type/enum single source (the engine-config
25
27
  * argv channel verbatim: flag spellings, value types and enum domains ride these
26
28
  * rows, and the command declarations + the channel audit read them from here). The
@@ -28,7 +30,11 @@ import { ENGINE_DOC_ROOTS } from "../infra/doc-roots.js";
28
30
  * text per key, shared by every command that declares it). */
29
31
  export const ARGV_CHANNEL = {
30
32
  plan: { flag: "--plan", type: "path", help: "the CDD plan document path" },
31
- spec: { flag: "--spec", type: "path", help: "the design-spec document path" },
33
+ spec: {
34
+ flag: "--spec",
35
+ type: "path",
36
+ help: "the document under review — a phase-spec, an overall charter or a single-spec",
37
+ },
32
38
  reviews: {
33
39
  flag: "--reviews",
34
40
  type: "path",
@@ -37,12 +43,12 @@ export const ARGV_CHANNEL = {
37
43
  tasks: {
38
44
  flag: "--tasks",
39
45
  type: "int-list",
40
- help: "the task ids of the wave group (comma-separated)",
46
+ help: `the task ids of the wave group (comma-separated) — at most ${MAX_TASKS_PER_WAVE} tasks per wave`,
41
47
  },
42
48
  type: {
43
49
  flag: "--type",
44
50
  type: "enum",
45
- values: ["wave", "branch", "spec", "plan"],
51
+ values: ["wave", "branch", "phase-spec", "overall", "plan", "single-spec"],
46
52
  help: "the target face of the round",
47
53
  },
48
54
  base: { flag: "--base", type: "string", help: "the base artifact branch name" },
@@ -54,11 +60,27 @@ export const ARGV_CHANNEL = {
54
60
  help: "the base artifact's source channel",
55
61
  },
56
62
  force: { flag: "--force", type: "bool", help: "override the existing base artifact" },
63
+ stealStale: {
64
+ flag: "--steal-stale",
65
+ type: "bool",
66
+ help: "take over a standing in-flight record whose holder is dead (the only takeover path)",
67
+ },
68
+ harness: {
69
+ flag: "--harness",
70
+ type: "enum",
71
+ values: HOST_IDS,
72
+ help: "the harness whose plugin set is installed or updated",
73
+ },
74
+ update: {
75
+ flag: "--update",
76
+ type: "bool",
77
+ help: "update the installed plugin set instead of installing it",
78
+ },
57
79
  dryRun: {
58
80
  flag: "--dry-run",
59
81
  type: "bool",
60
82
  scope: "program",
61
- help: "preview the next dispatch step and its expected artifacts — zero repo writes, no round consumed (implement/review/fix only)",
83
+ help: "preview the next dispatch step and its expected artifacts — zero repo writes, no round consumed (implement/review/fix/init)",
62
84
  },
63
85
  help: {
64
86
  flag: "--help",
@@ -111,34 +133,36 @@ export const VALUE_SHAPES = {
111
133
  },
112
134
  },
113
135
  };
114
- /** The seven subcommand declarations — implement, review, fix (the lifecycle work
115
- * commands) plus the pure base / schema / issue artifact commands and the board
116
- * observability command. */
136
+ /** The eight subcommand declarations — implement, review, fix (the lifecycle work
137
+ * commands) plus the pure base / schema / issue artifact commands, the board
138
+ * observability command and the repo-independent init bootstrap. */
117
139
  export const CLI_COMMANDS = [
118
140
  {
119
141
  name: "implement",
120
- description: "run the task implement phase",
142
+ description: `run the task implement phase — at most ${MAX_TASKS_PER_WAVE} tasks per wave`,
121
143
  example: `cdd implement --tasks 1,2 --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
122
144
  keys: [
123
145
  { key: "tasks", required: true },
124
146
  { key: "plan", required: true },
147
+ { key: "stealStale" },
125
148
  ],
126
149
  },
127
150
  {
128
151
  name: "review",
129
- description: "run a review — task | branch | spec | plan",
130
- example: `cdd review --type spec --spec ${ENGINE_DOC_ROOTS.specs}/p3-design.md`,
152
+ description: "run a review — wave | branch | phase-spec | overall | plan | single-spec",
153
+ example: `cdd review --type phase-spec --spec ${ENGINE_DOC_ROOTS.specs}/p3-design.md`,
131
154
  keys: [
132
155
  { key: "type", required: true },
133
156
  { key: "tasks" },
134
157
  { key: "plan" },
135
158
  { key: "spec" },
136
159
  { key: "round" },
160
+ { key: "stealStale" },
137
161
  ],
138
162
  },
139
163
  {
140
164
  name: "fix",
141
- description: "fix review findings — task | branch | spec | plan",
165
+ description: "fix review findings — wave | branch | phase-spec | overall | plan | single-spec",
142
166
  example: "cdd fix --type wave --tasks 1 --reviews tasks-1-review-1.json",
143
167
  keys: [
144
168
  { key: "type", required: true },
@@ -146,6 +170,7 @@ export const CLI_COMMANDS = [
146
170
  { key: "reviews" },
147
171
  { key: "spec" },
148
172
  { key: "plan" },
173
+ { key: "stealStale" },
149
174
  ],
150
175
  },
151
176
  {
@@ -200,10 +225,16 @@ export const CLI_COMMANDS = [
200
225
  },
201
226
  {
202
227
  name: "board",
203
- description: "render the progress board from a --plan or --spec entry (overall/spec/plan/wave/branch)",
228
+ description: "render the progress board from a --plan or --spec entry (overall/phase-spec/single-spec/plan/wave/branch)",
204
229
  example: `cdd board --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
205
230
  keys: [{ key: "plan" }, { key: "spec" }],
206
231
  },
232
+ {
233
+ name: "init",
234
+ description: "install or update the kairos plugin set for a harness",
235
+ example: "cdd init --harness=claude",
236
+ keys: [{ key: "harness", required: true }, { key: "update" }],
237
+ },
207
238
  ];
208
239
  /** The schema `<type>` vocabulary — the get leaf's ONE table (spec §5.3): the
209
240
  * primary DocKey spellings (overall | plan | phase-spec | single-spec) plus
@@ -218,23 +249,28 @@ export const SCHEMA_TYPE_KEYS = {
218
249
  phaseSpec: "phase-spec",
219
250
  };
220
251
  /** The conditional required group per work verb + target type — the preAction hook's
221
- * data face (spec §4.2): review `{plan}` / `{spec}` / `{plan}` · fix `{plan}` /
222
- * `{spec}` / `{findings, plan}` — every branch face carries the `--plan` workspace
223
- * identity (the branch line holds no commit ref: the review judges the live tree,
224
- * the scope anchor BASE_BRANCH is engine-injected at dispatch). Keyed by declared
225
- * flag spelling; non-exclusive — a round declaring both `--plan` and `--spec`
226
- * stays accepted (no mutual-exclusion rejection). */
252
+ * data face (spec §4.2): one row per `--type` value, keyed by the declared flag
253
+ * spelling. The doc shapes carry the `--spec` document (their declared `doc-type:`
254
+ * picks the contract the pre-flight judges); the wave/plan faces carry `--plan`, and
255
+ * every branch face carries the `--plan` workspace identity (the branch line holds
256
+ * no commit ref: the review judges the live tree, the scope anchor BASE_BRANCH is
257
+ * engine-injected at dispatch). Non-exclusive — a round declaring both `--plan` and
258
+ * `--spec` stays accepted (no mutual-exclusion rejection). */
227
259
  export const REQUIRED_GROUPS = {
228
260
  review: {
229
261
  wave: ["--plan"],
230
- spec: ["--spec"],
231
- plan: ["--plan"],
232
262
  branch: ["--plan"],
263
+ "phase-spec": ["--spec"],
264
+ overall: ["--spec"],
265
+ plan: ["--plan"],
266
+ "single-spec": ["--spec"],
233
267
  },
234
268
  fix: {
235
269
  wave: ["--plan"],
236
- spec: ["--spec"],
237
- plan: ["--plan"],
238
270
  branch: ["--reviews", "--plan"],
271
+ "phase-spec": ["--spec"],
272
+ overall: ["--spec"],
273
+ plan: ["--plan"],
274
+ "single-spec": ["--spec"],
239
275
  },
240
276
  };
package/dist/face/gate.js CHANGED
@@ -1,16 +1,22 @@
1
1
  // packages/cdd-engine/src-next/face/gate.ts
2
2
  // T8 — the split contract's gate face (§6.2: face/gate.ts — the target/line gate
3
3
  // family). The work commands' readiness gates — the single-target line's phase
4
- // derivation (#lineGate/#linePhase/#lineKey/#lineParams/#lineRoundRoute/#lineFixRoute),
5
- // the doc line's revision-aware BLOCK + pending-fix faces (#docLineBlock/
6
- // #pendingFixBlock/#docContent/#docVersionOf) and the group/line helpers
7
- // (#tasksOf/#renderBrief/#refFromHandoff). The method bodies are the pre-split Cli
8
- // members moved verbatim — behavior bytes identical; the root Cli holds the gate
9
- // instance and composes through it via its .action thin shells (zero bare functions).
4
+ // derivation (lineGate/#linePhase/#lineKey), the doc line's revision-aware BLOCK +
5
+ // pending-fix faces (#docLineBlock/#pendingFixBlock/#docContent/#docVersionOf), the
6
+ // ONE line-hop object the CLI refusal renders (lineHop + lineHopMessage, P22 §5.2)
7
+ // and the group/line helpers (#tasksOf/#renderBrief). The method bodies are the
8
+ // pre-split Cli members moved verbatim — behavior bytes identical; the root Cli
9
+ // holds the gate instance and composes through it via its .action thin shells (zero
10
+ // bare functions).
10
11
  import { readFileSync } from "node:fs";
12
+ import process from "node:process";
11
13
  import { FrontMatterExtractor } from "../contract/frontmatter.js";
12
14
  import { BriefRenderer } from "../render/brief.js";
13
15
  import { RoundNaming } from "../session/round-naming.js";
16
+ import { BoardView } from "./board-view.js";
17
+ import { ARGV_CHANNEL } from "./declare.js";
18
+ import { HostDetect } from "./host.js";
19
+ import { RouteRenderer } from "./route-render.js";
14
20
  /**
15
21
  * CliGate — the target/line gate family (the split contract's gate face): the
16
22
  * readiness judgments the work commands consult before dispatching a round. The
@@ -29,40 +35,54 @@ export class CliGate {
29
35
  * only the derived pending face, never a recomputed one. The task face holds no
30
36
  * separate gate here: the WaveGate's wrong-phase verdict (the pre-flight) IS the
31
37
  * task-face phase authority — the wave gate is the single phase authority. A
32
- * doc line's gate is the reviewGate method family (T8 · §3.5 · judgment order =
33
- * doc revision FIRST, shared by the lifecycle's frame phase so an opened gate
34
- * dispatches): a moved doc opens the review lead whatever the round/route state
35
- * says (fix after · backfill after · user-decision after are the SAME case — the
36
- * stuck "next round is fix after an aborted fix" never freezes a revised doc),
37
- * an unchanged doc yields the gate's "same" verdict — the pending fix DERIVED
38
- * from the latest review's non-APPROVED conclusion opens only the fix phase,
39
- * while the no-pending face falls back to the legacy rounds/routes judgment: a
40
- * completed-fix line reopens the review lead through its fix round's C5-1 route
41
- * (the lifecycle's own fall-through — an open gate and a dispatchable frame
42
- * agree), a truly closed line keeps the revision-aware BLOCK. An unbound line
43
- * (no identity on record / an unreadable doc) keeps the legacy round/route
44
- * judgment + the generic closed message (only present facts land). */
38
+ * doc line's gate is the reviewGate method family (T8 · §3.5), shared by the
39
+ * lifecycle's frame phase so an opened gate dispatches: a moved doc reopens the
40
+ * review lead on a line whose C5 hop is on the EXIT side (a closed line, `null`,
41
+ * or a face-to-face station — the ONE `Ledger#docReopens` judgment), while a
42
+ * still-pending fix keeps its hop (drift never outranks it, §5.5 ②) so the gate
43
+ * never refuses the round the ONE derivation names. An unchanged doc yields the
44
+ * gate's "same" verdict — the pending fix DERIVED from the latest review's
45
+ * non-APPROVED conclusion opens only the fix phase, while the no-pending face
46
+ * falls back to the legacy rounds/routes judgment: a completed-fix line reopens
47
+ * the review lead through its fix round's C5-1 route (the lifecycle's own
48
+ * fall-through — an open gate and a dispatchable frame agree), a truly closed line
49
+ * keeps the revision-aware BLOCK. An unbound line (no identity on record / an
50
+ * unreadable doc) keeps the legacy round/route judgment + the generic closed
51
+ * message (only present facts land).
52
+ *
53
+ * The branch line rides the SAME drift leg (its identity document is the PLAN,
54
+ * P21 §3/§4.1 — the very document a branch re-review judges): a plan revision
55
+ * moved past the bound one reopens the branch face onto its `branch-review`
56
+ * lead, so the `next:` a closure hands the user is never a command this gate
57
+ * refuses. An unchanged plan falls through to the SAME derived faces the doc lines
58
+ * reach: a branch review that left findings yields the derived `fix` face
59
+ * (`pending-fix` — no doc-class BLOCK message binds the branch face, so the refusal
60
+ * renders through the ONE line hop), while only a fully closed, drift-free branch
61
+ * line keeps the generic `face-closed` row. */
45
62
  lineGate(scene) {
46
- if (scene.target?.kind === "plan" || scene.target?.kind === "spec") {
47
- const key = this.#lineKey(scene);
48
- if (key === null)
49
- return { phase: null, verdict: null, reviewed: null };
50
- const verdict = scene.ledger.reviewGate(key, scene.target.doc, scene.face.type);
51
- if (verdict.kind === "open") {
52
- return { phase: scene.face.product.reviewLead, verdict: null, reviewed: null };
53
- }
54
- if (verdict.kind === "same") {
55
- if (verdict.pending) {
56
- return { phase: "fix", verdict: "pending-fix", reviewed: verdict.reviewed };
57
- }
58
- // same + no pending fix — the legacy rounds/routes judgment (the lifecycle's
59
- // own fall-through): a completed-fix line reopens the review lead through its
60
- // fix round's C5-1 route; a truly closed line keeps the revision-aware BLOCK.
61
- const open = this.#linePhase(scene);
62
- return open !== null
63
- ? { phase: open, verdict: null, reviewed: null }
64
- : { phase: null, verdict: "same", reviewed: verdict.reviewed };
63
+ const key = this.#lineKey(scene);
64
+ const doc = this.#docOf(scene);
65
+ const verdict = key !== null && doc !== null ? scene.ledger.reviewGate(key, doc, scene.face.type) : null;
66
+ // The drift leg reads the ONE reopen judgment (exit-side routes only): a moved doc
67
+ // reopens the review lead on a line whose C5 hop is gone, while a still-pending
68
+ // fix keeps its own hop — drift never outranks it (§5.1 · §5.5 ②), so this gate
69
+ // always accepts the round the ONE derivation names.
70
+ if (key !== null &&
71
+ verdict !== null &&
72
+ scene.ledger.docReopens(key, scene.face.type, verdict)) {
73
+ return { phase: scene.face.product.reviewLead, verdict: null, reviewed: null };
74
+ }
75
+ if (verdict !== null && verdict.kind === "same") {
76
+ if (verdict.pending) {
77
+ return { phase: "fix", verdict: "pending-fix", reviewed: verdict.reviewed };
65
78
  }
79
+ // same + no pending fix — the legacy rounds/routes judgment (the lifecycle's
80
+ // own fall-through): a completed-fix line reopens the review lead through its
81
+ // fix round's C5-1 route; a truly closed line keeps the revision-aware BLOCK.
82
+ const open = this.#linePhase(scene);
83
+ return open !== null
84
+ ? { phase: open, verdict: null, reviewed: null }
85
+ : { phase: null, verdict: "same", reviewed: verdict.reviewed };
66
86
  }
67
87
  const open = this.#linePhase(scene);
68
88
  return { phase: open, verdict: null, reviewed: null };
@@ -92,6 +112,62 @@ export class CliGate {
92
112
  return null;
93
113
  return `the pending fix applies to the unchanged doc (doc-hash ${reviewed.doc_hash.slice(0, 12)}…) — run cdd fix first`;
94
114
  }
115
+ /** lineHop(scene) — the line's ONE next-hop object (§5.2): the SAME derivation
116
+ * the capsule, the board and the lifecycle frontier read, built from this line's
117
+ * facts through `Ledger#nextHopOf` (the ONE assembly entry: the drift gate + the
118
+ * declaration read). The CLI rejection message renders THIS object's `reason` +
119
+ * hop/station — never a second judgment, never a second shape. The doc-class
120
+ * discrimination is ROOTED in the workspace's own repo basis (the same basis the
121
+ * lifecycle frontier injects), so an engine invoked from a subdirectory reads the
122
+ * same declared `doc-type:` the board does. Null when the scene holds no
123
+ * registered line (no fixed target → there is no line to name). */
124
+ lineHop(scene) {
125
+ const key = this.#lineKey(scene);
126
+ const target = this.#routeTargetOf(scene);
127
+ if (key === null || target === null)
128
+ return null;
129
+ const basis = scene.workspace.root.basis;
130
+ return scene.ledger.nextHopOf({
131
+ type: scene.face.type,
132
+ key,
133
+ route: scene.ledger.lineRoute(key, scene.face.type),
134
+ target,
135
+ doc: this.#docOf(scene),
136
+ docClassOf: (candidate) => BoardView.docClassOf(basis, candidate),
137
+ });
138
+ }
139
+ /** lineHopMessage(scene, hop, words) — the CLI rejection prose of one `NextHop`
140
+ * (P22 §5.2, the ONE message shape): a hop names its verb, a closed face names
141
+ * its handoff station (rendered through the SAME route renderer the `next:` line
142
+ * uses), and neither renders an invented verb slot. */
143
+ lineHopMessage(scene, hop, words) {
144
+ if (hop === null)
145
+ return "the line holds no open round";
146
+ const renderer = new RouteRenderer(words, ARGV_CHANNEL, HostDetect.detect(process.env), scene.workspace.root.basis);
147
+ return scene.router.message(hop, (entry) => renderer.render({ kind: "handoff", entry }, hop.target));
148
+ }
149
+ /** The line's judged document — the doc line's own path, the branch line's plan
150
+ * (its identity document, P21 §4.1); null off the doc faces. */
151
+ #docOf(scene) {
152
+ if (scene.target?.kind === "plan" || scene.target?.kind === "spec")
153
+ return scene.target.doc;
154
+ if (scene.target?.kind === "branch")
155
+ return scene.planPath;
156
+ return null;
157
+ }
158
+ /** The dispatch frame's own render target (§5.2's `target` cell) — the fixed
159
+ * line's type + stable key (+ the plan fact the branch literal needs). A doc shape
160
+ * (the `--spec` channel: phase-spec / overall / single-spec) renders its OWN
161
+ * target-type word, never a folded `spec` spelling. */
162
+ #routeTargetOf(scene) {
163
+ if (scene.target?.kind === "branch")
164
+ return { type: "branch", id: "branch", plan: scene.planPath ?? undefined };
165
+ if (scene.target?.kind === "spec")
166
+ return { type: scene.face.type, id: scene.target.doc };
167
+ if (scene.target?.kind === "plan")
168
+ return { type: "plan", id: scene.target.doc };
169
+ return null;
170
+ }
95
171
  /** The requested group ints — the normalized tasks value split. */
96
172
  tasksOf(parsed) {
97
173
  return (parsed.args.tasks ?? "").split(",").map((part) => Number(part));
@@ -120,8 +196,9 @@ export class CliGate {
120
196
  return scene.ledger.linePhase(key, scene.face.type);
121
197
  }
122
198
  /** The line key of a fixed-target face — the line's STABLE key (find #9 · spec
123
- * §6.5/§3.7 — `"branch"` per workspace for the branch line; the doc line keys by
124
- * its line-type constant `"spec"`/`"plan"` — never the argv path: a moved argv
199
+ * §6.5/§3.7 — `"branch"` per workspace for the branch line; a doc line keys by
200
+ * its target-type word (`"phase-spec"` / `"overall"` / `"plan"` / `"single-spec"`)
201
+ * — never the argv path: a moved argv
125
202
  * string must not fork the same line into two ledger rows, resetting its round),
126
203
  * the lifecycle's own key derivation (run.ts #lineKey). */
127
204
  #lineKey(scene) {
package/dist/face/host.js CHANGED
@@ -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 / env). The host-marker closure is single-sourced HERE: the
8
+ // detect / env). 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
@@ -29,30 +29,11 @@
29
29
  //
30
30
  // Module-level exports are types / the declared constant data — zero behavior-
31
31
  // carrying bare functions (the plan's zero-bare-function discipline).
32
- /** The per-harness install banners — the kairos self-install + the upstream plugin
33
- * install commands. The `packages/kairos/README.md` upstream dependency table (and
34
- * its zh mirror) renders from these rows; the engine-suite gate
35
- * (face/__tests__/install-rows.guard.test.ts) pins each README row's Claude Code cell
36
- * to `INSTALL_ROWS[key].join(";")` and the row key set to these keys — a README
37
- * install-command drift fails there, never silently. */
38
- export const INSTALL_ROWS = {
39
- kairos: [
40
- "claude plugin marketplace add oscaner/skills",
41
- "claude plugin install kairos@oscaner-skills",
42
- ],
43
- superpowers: [
44
- "claude plugin marketplace add obra/superpowers-marketplace",
45
- "claude plugin install superpowers@superpowers-marketplace",
46
- ],
47
- "mattpocock-skills": [
48
- "claude plugin marketplace add mattpocock/skills",
49
- "claude plugin install mattpocock-skills@mattpocock",
50
- ],
51
- impeccable: [
52
- "claude plugin marketplace add pbakaus/impeccable",
53
- "claude plugin install impeccable@impeccable",
54
- ],
55
- };
32
+ /** The harness ids the contract adapts — the runtime companion of `HostId` and the
33
+ * single source of the host vocabulary: `HostId` derives from it, the `HOSTS` key
34
+ * set closes over it, and the `--harness` value range plus the detect walk read it
35
+ * (the production face carries no second copy of the host literal list). */
36
+ export const HOST_IDS = ["claude", "pi"];
56
37
  /** The per-harness host rows — claude / pi adaptation facts. */
57
38
  export const HOSTS = {
58
39
  claude: {
@@ -62,7 +43,6 @@ export const HOSTS = {
62
43
  output: "text",
63
44
  ship: "full",
64
45
  detect: { env: "CLAUDE_CODE_SESSION_ID", aiAgentPrefix: "claude-code" },
65
- install: INSTALL_ROWS,
66
46
  capabilities: { parallel: true },
67
47
  env: { FORCE_PROMPT_CACHING_5M: "1" },
68
48
  },
@@ -73,12 +53,6 @@ export const HOSTS = {
73
53
  output: "text",
74
54
  ship: "full",
75
55
  detect: { env: "AI_AGENT", value: "pi" },
76
- install: {
77
- kairos: ["pi install npm:@oscaner-skills/kairos"],
78
- superpowers: ["pi install git:github.com/obra/superpowers"],
79
- "mattpocock-skills": ["pi install git:github.com/mattpocock/skills"],
80
- impeccable: ["npx impeccable install --providers=pi --scope=global -y"],
81
- },
82
56
  capabilities: { parallel: "pending" },
83
57
  env: { PI_CACHE_RETENTION: "short" },
84
58
  },
@@ -160,13 +134,13 @@ export const HOST_CONTRACT = {
160
134
  * must stay import-clean toward the dispatch face). */
161
135
  // biome-ignore lint/complexity/noStaticOnlyClass: the module-level host-detect surface — the zero-bare-function discipline admits no standalone predicate functions.
162
136
  export class HostDetect {
163
- /** detect(env) — the first host detect row that matches, in the pinned order
164
- * `claude` → `pi` (specific markers first, the generic AI_AGENT
137
+ /** detect(env) — the first host detect row that matches, in the pinned `HOST_IDS`
138
+ * order `claude` → `pi` (specific markers first, the generic AI_AGENT
165
139
  * last). One row detects by its primary marker (a session env, presence/enum —
166
140
  * a UUID CLAUDE_CODE_SESSION_ID is claude by presence) or by the AI_AGENT
167
141
  * prefix (AI_AGENT=claude-code-…); no match returns `""`. */
168
142
  static detect(env) {
169
- for (const id of ["claude", "pi"]) {
143
+ for (const id of HOST_IDS) {
170
144
  const detect = HOSTS[id].detect;
171
145
  if (detect.env !== undefined && detect.env !== "") {
172
146
  const marker = env[detect.env];
@@ -0,0 +1,108 @@
1
+ // packages/cdd-engine/src-next/face/init.ts
2
+ // P20 — the harness plugin bootstrap (`cdd init`): the eighth top-level verb, a
3
+ // repo-independent face that spawns the harness's own install / update sequence.
4
+ //
5
+ // The data plane is the roster (`face/plugins.ts`): one row per package, one column
6
+ // per harness id, two command shapes per column. This module declares zero command
7
+ // bytes — it flattens the requested column in roster order and runs it serially.
8
+ //
9
+ // · StepRunner — the narrow execution seam: one structured argv in, the child's
10
+ // own exit code out (fail-open — a spawn failure is a code, never a throw).
11
+ // · ExecaStepRunner — the production runner: `stdio: "inherit"` on all three
12
+ // standard streams, so the child holds the real terminal (the harness's
13
+ // interactive prompts and TTY judgment see what the human sees) and the
14
+ // consumer watches the harness output live. A missing / non-executable binary
15
+ // rides `SPAWN_FAILURE_CODE` (the shell's command-not-found convention) into
16
+ // the same failure face — zero special-case probing.
17
+ // · CliInit — the face class: per-step header before the spawn (the header seam
18
+ // is the composition root's synchronous writer, so a piped log cannot reorder
19
+ // the header behind the child's own output), first non-zero exit stops the
20
+ // sequence, and a green run closes with one summary line. Its `--dry-run`
21
+ // preview renders the same flattened plan as `would run:` lines and touches no
22
+ // step runner at all — the flatten is single-source, the only branch is whether
23
+ // a step is spawned.
24
+ //
25
+ // The dispatch execution machine (`face/termination.ts` — timeout / budget / group
26
+ // kill / sampling trail / stall judge) is never shared: a bootstrap step has no round,
27
+ // no ceiling and no session state.
28
+ //
29
+ // Module-level exports are types / declared constants / classes — zero
30
+ // behavior-carrying bare functions (the zero-bare-function discipline).
31
+ import { execa } from "execa";
32
+ import { PLUGINS } from "./plugins.js";
33
+ /** The one stdio face of an install step — all three standard streams inherited
34
+ * from the parent process. */
35
+ export const STDIO = "inherit";
36
+ /** The spawn-failure code — the shell's command-not-found convention; a missing
37
+ * harness binary (or any non-executable argv[0]) reports this code through the
38
+ * ordinary failure face. */
39
+ export const SPAWN_FAILURE_CODE = 127;
40
+ /** The production step runner — execa's asynchronous face over the inherited
41
+ * standard streams. */
42
+ export class ExecaStepRunner {
43
+ async run(argv) {
44
+ const [binary = "", ...args] = argv;
45
+ const result = await execa(binary, args, { stdio: STDIO, reject: false });
46
+ // Zero exit codes only exist for a spawned child — an undefined code is the
47
+ // spawn-failure face (ENOENT / EACCES), never a success.
48
+ return result.exitCode ?? SPAWN_FAILURE_CODE;
49
+ }
50
+ }
51
+ /**
52
+ * CliInit — the `cdd init --harness=<id> [--update]` run face. Repo-independent:
53
+ * zero workspace writes, zero ledger, zero document reads — the harness's own
54
+ * command sequence is the only side effect.
55
+ */
56
+ export class CliInit {
57
+ #io;
58
+ #runner;
59
+ #header;
60
+ constructor(opts) {
61
+ this.#io = opts.io;
62
+ this.#runner = opts.runner;
63
+ this.#header = opts.header;
64
+ }
65
+ /** The ordered step plan for one harness + shape — the ONE flatten source the
66
+ * preview and the real run both read. The only branch point between them is
67
+ * whether `StepRunner` is called, so a preview can never drift from the run. */
68
+ #stepsOf(host, update) {
69
+ const steps = [];
70
+ for (const row of PLUGINS) {
71
+ for (const argv of update ? row[host].update : row[host].install) {
72
+ steps.push({ packageName: row.name, argv });
73
+ }
74
+ }
75
+ return steps;
76
+ }
77
+ /** Render the step plan the run would execute — one `would run: <argv join>` line
78
+ * per step, then the summary. Zero spawn, zero write: the runner is never
79
+ * reached on this path (a preview is a rendering, not an execution). */
80
+ preview(host, update) {
81
+ const steps = this.#stepsOf(host, update);
82
+ return [
83
+ ...steps.map((step) => `would run: ${step.argv.join(" ")}`),
84
+ `init: ${steps.length} steps (${host} · ${update ? "update" : "install"}) — dry run, nothing executed`,
85
+ ];
86
+ }
87
+ /** Run the harness's sequence — 0 all green, 1 the first failed step. */
88
+ async run(host, update) {
89
+ const steps = this.#stepsOf(host, update);
90
+ const total = steps.length;
91
+ for (const [index, step] of steps.entries()) {
92
+ const ordinal = index + 1;
93
+ this.#header(`init[${ordinal}/${total}] ${host} · ${step.packageName} · ${step.argv.slice(1).join(" ")}`);
94
+ const code = await this.#runner.run(step.argv);
95
+ if (code !== 0) {
96
+ this.#io.stderr(`init[${ordinal}/${total}] · ${step.argv.join(" ")} · exit ${code}\n`);
97
+ // The hint is conditional wording — the engine parses zero harness output,
98
+ // so it cannot know whether "not installed" caused this failure.
99
+ if (update) {
100
+ this.#io.stderr(`if the package is not installed, run cdd init --harness=${host} without --update first\n`);
101
+ }
102
+ return 1;
103
+ }
104
+ }
105
+ this.#header(`init: ${total} steps ok (${host} · ${update ? "update" : "install"})`);
106
+ return 0;
107
+ }
108
+ }