@oscaner-skills/cdd-engine 4.2.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 (55) hide show
  1. package/README.md +38 -9
  2. package/README.zh-CN.md +43 -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 +116 -35
  27. package/dist/face/declare.js +36 -18
  28. package/dist/face/gate.js +117 -40
  29. package/dist/face/init.js +1 -1
  30. package/dist/face/lifecycle.js +540 -123
  31. package/dist/face/preview.js +43 -10
  32. package/dist/face/route-render.js +51 -21
  33. package/dist/face/termination.js +135 -261
  34. package/dist/face/words.js +134 -12
  35. package/dist/infra/atomic.js +15 -0
  36. package/dist/infra/git.js +25 -0
  37. package/dist/infra/proc.js +150 -0
  38. package/dist/infra/round-log.js +104 -0
  39. package/dist/infra/runtime.js +16 -4
  40. package/dist/infra/workspace.js +7 -2
  41. package/dist/render/brief.js +15 -17
  42. package/dist/render/skeleton.js +41 -28
  43. package/dist/render/templates.js +128 -84
  44. package/dist/session/faces.js +47 -20
  45. package/dist/session/graph.js +13 -37
  46. package/dist/session/handoff-schema.js +16 -8
  47. package/dist/session/inflight.js +282 -0
  48. package/dist/session/ledger.js +581 -136
  49. package/dist/session/line-identity.js +33 -0
  50. package/dist/session/next.js +138 -80
  51. package/dist/session/preflight.js +276 -68
  52. package/dist/session/round-naming.js +56 -8
  53. package/dist/session/run.js +317 -78
  54. package/dist/session/wave.js +94 -14
  55. package/package.json +13 -3
@@ -1,26 +1,33 @@
1
1
  // packages/cdd-engine/src-next/face/capsule.ts
2
- // T10 — the single capsule face (design spec §3.2: the `status · blocker · handoff
3
- // · next:` word-face steady state). Capsule#emit renders the ALL-OP single stdout
4
- // face — the capsule the orchestrator greps / routes on without opening the handoff:
2
+ // T10 — the single capsule face (design spec §3.2: the `status · handoff · next:`
3
+ // word-face steady state; P22 §10: the output face's closeout). Capsule#emit
4
+ // renders the ALL-OP single stdout face — the capsule the orchestrator greps /
5
+ // routes on without opening the handoff:
5
6
  //
6
- // status: <status> · blocker: <blocker> · handoff: <handoff> (success statuses)
7
- // status: <status> [· handoff: <crash>] (TIMEOUT / BLOCKED)
7
+ // status: <status> · handoff: <handoff> (success statuses)
8
+ // status: <status> [· handoff: <crash>] (TIMEOUT / BLOCKED)
9
+ // fixed N · rejected M (fix rounds only — between the status line and `next:`)
8
10
  // next: <suggestion> (optional — the C5 route / a caller-rendered text)
9
11
  //
10
- // The key set is the word table's single source (`Words.capsuleKeys(status,
11
- // withHandoff)`) — a failure status drops the blocker cell whose value would be a
12
- // filler, and keeps the handoff cell only when the round wrote a crash record.
12
+ // The `blocker` cell is retired: its whole information content — the blocker count —
13
+ // is derivable from `status` (any blocker ⇒ CHANGES_REQUESTED, warn/nit-only ⇒
14
+ // REVIEW_FIX, empty ⇒ APPROVED, a failure round prints no cell at all), and that
15
+ // count is exactly the number the review criterion rules undisplayed. The key set is
16
+ // still the word table's single source (`Words.capsuleKeys(status, withHandoff)`) —
17
+ // a failure status keeps the handoff cell only when the round wrote a crash record.
18
+ // The fix round's disposition summary rides the SAME render, placed so the
19
+ // dispatchable `next:` literal closes the output: `status` → summary → `next:`.
13
20
  //
14
- // The byte face is v1-pinned: the key words (status · blocker · handoff) are
15
- // pin-enforced by the CapsuleKey type and the emit signature — a data-only change
16
- // cannot reshape them. What rides the injected Words table (the single word-table
17
- // instance) is the `·` separator, the `next:` station anchor and the route/status
18
- // vocabulary — a second table is excluded by construction. The `next:` value is
21
+ // The byte face is v1-pinned: the key words (status · handoff) are pin-enforced by
22
+ // the CapsuleKey type and the emit signature — a data-only change cannot reshape
23
+ // them. What rides the injected Words table (the single word-table instance) is the
24
+ // `·` separator, the `next:` station anchor and the route/status vocabulary — a
25
+ // second table is excluded by construction. The `next:` value is
19
26
  // either a caller-rendered string or the C5 Route rendered through the route-word
20
27
  // table as a COMPLETE EXECUTABLE command (P4.1 T4 — the v1.39 semantic-literal
21
- // reversal): `implement --plan <path> --tasks 17` · `review --type spec --spec
22
- // <path>` · `fix --type spec --spec <path> --reviews <handoff> (read file back to
23
- // confirm)` · `done` (the bare terminal word) · the soft-cap message verbatim.
28
+ // reversal): `implement --plan <path> --tasks 17` · `review --type phase-spec --spec
29
+ // <path>` · `fix --type phase-spec --spec <path> --reviews <handoff>` + the readback
30
+ // suffix · `done` (the bare terminal word) · the soft-cap message verbatim.
24
31
  // The argv is composed from the frame facts (the RouteTarget's type + id + plan)
25
32
  // through the argv-channel flag spellings (the same channel the CLI parse reads —
26
33
  // the render source is the declared channel, never a second hard-coded format
@@ -31,28 +38,30 @@
31
38
  // message — rides declared constants from session/next.ts, rendered by reference,
32
39
  // never restated.
33
40
  //
34
- // D40 — the render delegates to the shared `RouteRenderer` (the ONE route →
35
- // `next:` literal face, also consumed by the board); the capsule adds only the
36
- // `done` face's doc-class discrimination (a spec doc's declared class decides the
37
- // pipeline entry — or the BLOCKED face when the declaration is absent, spec §12).
41
+ // D40 · P22 §5.2 — the render delegates to the shared `RouteRenderer` (the ONE
42
+ // route → `next:` literal face, also consumed by the board). The capsule reads the
43
+ // INJECTED `NextHop` — the ONE object every read face renders — and adds no
44
+ // judgment of its own: the doc-class discrimination that picks the pipeline station
45
+ // belongs to the derivation's injected seam (`BoardView.docClassOf`), never here.
46
+ // A `NextHop` that is ABSENT (the BLOCKED / TIMEOUT failure face) prints no `next:`
47
+ // line; a present hop with `hop: null` (`done` · `soft-cap` · the doc-class
48
+ // `terminal` / `blocked` rows) still prints its frozen line.
38
49
  //
39
50
  // The class satisfies the session/run.ts CapsuleFace seam (T8's interaction point) —
40
51
  // the capsule plugs into the lifecycle's attachCapsule contact, byte-identically.
41
52
  // Module-level exports are the class — zero behavior-carrying bare functions.
42
- import { RepoRoot } from "../infra/root.js";
43
- import { NextStepRouter } from "../session/next.js";
44
- import { BoardView } from "./board-view.js";
45
53
  import { RouteRenderer } from "./route-render.js";
46
54
  /**
47
- * Capsule — the single capsule output face. emit(status, blocker, handoff, next)
48
- * renders one round's facts into the byte-pinned `status · blocker · handoff` line
49
- * plus the optional `next:` line. The key words are the CapsuleKey literals the
50
- * kind loop renders (pin-enforced by the emit signature); the separator, station
51
- * and route/status words ride the injected Words instance. The complete executable
52
- * `next:` literal composes its full argv from the route + the additive optional
53
- * RouteTarget (the frame's own facts) through the argv-channel flag spellings
54
- * (P4.1 T4; same channel source parse reads — the 4-param signature stays
55
- * byte-pinned, the target is an optional 5th, the channel an optional 2nd).
55
+ * Capsule — the single capsule output face. emit(status, handoff, hop?,
56
+ * withHandoff?, summary?) renders one round's facts into the byte-pinned `status ·
57
+ * handoff` line, the fix round's optional disposition summary, and the optional
58
+ * `next:` line LAST (the dispatchable literal closes the output). The key words are
59
+ * the CapsuleKey literals the kind loop renders (pin-enforced by the emit
60
+ * signature); the separator, station and route/status words ride the injected Words
61
+ * instance. The complete executable `next:` literal composes its full argv from the
62
+ * injected `NextHop`'s route + target through the argv-channel flag spellings (P4.1
63
+ * T4; same channel source the parse reads — the hop is optional, the channel an
64
+ * optional 2nd constructor argument).
56
65
  */
57
66
  export class Capsule {
58
67
  /** The single word table — the capsule's whole vocabulary source. */
@@ -68,24 +77,29 @@ export class Capsule {
68
77
  this.#root = root;
69
78
  this.#route = new RouteRenderer(words, channels, host, root);
70
79
  }
71
- /** emit(status, blocker, handoff, next, target, withHandoff) → the capsule stdout
72
- * lines: the status-class key set from the word table (a success status renders
73
- * `status · blocker · handoff`; a failure status renders `status`, plus `handoff`
74
- * only when the round wrote a crash record), then the optional `next:` line (a
75
- * caller-rendered text, a C5 Route rendered as the complete executable command, or
76
- * null/absent → no line). The additive optional RouteTarget supplies the frame's
77
- * own type + id + plan for the executable literal (P4.1 T4); without it the route
78
- * renders its bare classifier fallbacks (the 4-param signature stays byte-pinned).
79
- * `withHandoff` is the caller's crash-record fact — the key set remains the table's
80
- * single source (this render adds no status special case). */
81
- emit(status, blocker, handoff, next, target, withHandoff = false) {
80
+ /** emit(status, handoff, hop, withHandoff, summary) → the capsule stdout lines:
81
+ * the status-class key set from the word table (a success status renders
82
+ * `status · handoff`; a failure status renders `status`, plus `handoff` only when
83
+ * the round wrote a crash record), then the fix round's optional summary line,
84
+ * then the optional `next:` line LAST — the dispatchable literal is the output's
85
+ * close. `hop` is the ONE injected `NextHop` object — its ABSENCE (null: the
86
+ * BLOCKED / TIMEOUT failure face) prints no `next:` line at all, while a present
87
+ * object renders through the shared hop face (`RouteRenderer#renderHop`: the
88
+ * soft-cap message · the in-line hop · the face-to-face station · the BLOCKED
89
+ * face · the terminal word). `withHandoff` is the caller's crash-record fact — the
90
+ * key set remains the table's single source (this render adds no status special
91
+ * case).
92
+ *
93
+ * Five parameters is one over the flat-signature limit: the positional face IS the
94
+ * pinned contract (the seam's emit signature), so it stays flat rather than boxed
95
+ * into a parameter object. */
96
+ emit(status, handoff, hop, withHandoff = false, summary) {
82
97
  const words = this.#words;
83
98
  // The `handoff:` cell is a path value — normalized to the repoRoot-relative
84
99
  // shape through the ONE value object (D47 · the ONE basis; `handoffPath` sources
85
100
  // it absolute).
86
101
  const cells = {
87
102
  status,
88
- blocker,
89
103
  handoff: this.#rel(handoff),
90
104
  };
91
105
  const capsuleLine = words
@@ -93,56 +107,19 @@ export class Capsule {
93
107
  .map((kind) => `${kind}: ${cells[kind]}`)
94
108
  .join(words.capsuleSeparator());
95
109
  const lines = [capsuleLine];
96
- if (next !== undefined && next !== null) {
97
- const text = typeof next === "string" ? next : this.#routeText(next, target);
98
- lines.push(`${words.station("next")} ${text}`);
99
- }
110
+ if (summary !== undefined)
111
+ lines.push(summary);
112
+ const next = this.#route.renderHop(hop ?? null);
113
+ if (next !== null)
114
+ lines.push(`${words.station("next")} ${next}`);
100
115
  return lines;
101
116
  }
102
- /** The route → `next:` text render — the shared RouteRenderer (D40) unless the
103
- * `done` face's doc-class discrimination fires (a spec doc's declared class decides
104
- * the pipeline entry — or the BLOCKED face when the declaration is absent, spec
105
- * §12 · D34). The capsule resolves the doc-class, then hands the resulting Route
106
- * (a `handoff` carrying the entry, or the bare `done`) to the same renderer. */
107
- #routeText(route, target) {
108
- if (route.kind === "done" && target != null) {
109
- const verdict = this.#docClassOf(target);
110
- if (verdict === "blocked") {
111
- return `${this.#words.station("blocked")} ${this.#words.routeWord("docType")}`;
112
- }
113
- // The declared doc-class (or a bare terminal) picks the pipeline entry — the
114
- // same resolver + renderer the board consumes.
115
- const key = verdict === "terminal" ? null : verdict;
116
- return this.#route.render(NextStepRouter.resolve({ kind: "done" }, key), target);
117
- }
118
- return this.#route.render(route, target);
119
- }
120
- /** The target → doc-class verdict of the unified next face — the doc-class
121
- * discrimination face (D33): the spec doc's class reads its DECLARED type (the
122
- * front-matter `doc-type:` key, spec §12 · D34 — BoardView.readDocType,
123
- * the one declaration reading face), never the filename suffix; the task-face
124
- * targets key by type. `blocked` — the key is missing (the caller
125
- * renders the BLOCKED face); `terminal` — no pipeline seam carries the declared
126
- * class (`single-spec`, the table's five keys exclude it — the bare word). */
127
- #docClassOf(target) {
128
- if (target.type === "spec") {
129
- // The read face takes the value object + the repoRoot-relative id (T4 §2.2);
130
- // a `null` root (the hermetic default) keeps the value as its own basis. The
131
- // `#rel` branded return needs no cast here (F3).
132
- const declared = BoardView.readDocType(this.#root ?? new RepoRoot(""), this.#rel(target.id));
133
- return declared === null ? "blocked" : declared === "single-spec" ? "terminal" : declared;
134
- }
135
- if (target.type === "plan")
136
- return "plan";
137
- if (target.type === "wave")
138
- return "wave";
139
- return "branch";
140
- }
141
117
  /** One path value normalized to the branded repoRoot-relative `RepoPath` through
142
118
  * the ONE value object (D47); a `null` root (the hermetic default) passes the
143
119
  * value through as its own basis. The branded return type carries the §2.2 brand
144
- * to the read face (`BoardView.readDocType`) with NO call-site cast (branch-
145
- * review-1 F3). */
120
+ * to the render face with NO call-site cast (branch-review-1 F3); the board's doc
121
+ * cell and its `docClassOf` discrimination are the sibling read faces that
122
+ * resolve the same branded form. */
146
123
  #rel(value) {
147
124
  return this.#root === null ? value : this.#root.relativize(value);
148
125
  }
package/dist/face/cli.js CHANGED
@@ -60,14 +60,15 @@ import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
60
60
  import { BriefRenderer } from "../render/brief.js";
61
61
  import { IssueBodyRenderer } from "../render/issue-body.js";
62
62
  import { TemplateAssembler } from "../render/templates.js";
63
- import { targetFaces } from "../session/faces.js";
63
+ import { TargetFaceTable, targetFaces } from "../session/faces.js";
64
64
  import { TaskGraph } from "../session/graph.js";
65
+ import { HoldingError, InFlight } from "../session/inflight.js";
65
66
  import { Ledger } from "../session/ledger.js";
66
67
  import { NextStepRouter } from "../session/next.js";
67
68
  import { PreFlight } from "../session/preflight.js";
68
69
  import { EMPTY_RUN_STATE, Lifecycle } from "../session/run.js";
69
70
  import { CliArtifacts } from "./artifacts.js";
70
- import { BoardView } from "./board-view.js";
71
+ import { BoardNext, BoardView } from "./board-view.js";
71
72
  import { Capsule } from "./capsule.js";
72
73
  import { ARGV_CHANNEL } from "./declare.js";
73
74
  import { CliGate } from "./gate.js";
@@ -104,8 +105,8 @@ export class Cli {
104
105
  /** The pre-flight board face (the blocked-dispatch wave hint). */
105
106
  #graphView;
106
107
  /** The lifecycle pre-flight seam (P4.1 T1) — the single dispatch gate the work
107
- * commands consult before ANY child dispatch (tree-clean → graph → wave →
108
- * doc-contract; the CLI orchestrates the call + the render, never a re-type). */
108
+ * commands consult before ANY child dispatch (tree-clean → in-flight → graph →
109
+ * plan-ledger → wave → doc-contract; the CLI orchestrates, never a re-type). */
109
110
  #preflight;
110
111
  /** The contract coordinator — the doc-contract judgment face the pre-flight's
111
112
  * doc gate reads (the single interpreter entry; spec §12 · D34 retired the
@@ -353,7 +354,15 @@ export class Cli {
353
354
  if (entry === null)
354
355
  return 2;
355
356
  const host = HostDetect.detect(process.env);
356
- const board = BoardView.render(index, entry, repoRoot, this.#words, host, ARGV_CHANNEL);
357
+ // The in-flight fact is TREE-level: the board inspects it (read-only — the gate
358
+ // and the board share `InFlight.inspect()`, never a second liveness judgment).
359
+ const inflight = new InFlight(new WorkspaceRoot(repoRoot, this.#config.handoffNamespace().workspaceRoot), entry.slug ?? "");
360
+ // The board's `next:` line renders ONE injected `NextHop` (P22 §5.2): the
361
+ // pipeline OBSERVATION comes from the board face, the four face-order rules and
362
+ // the ONE derivation from this assembly point (`BoardNext`) — the board itself
363
+ // holds no ledger for the next line and judges nothing.
364
+ const next = BoardNext.of(index, entry, root);
365
+ const board = BoardView.render(index, entry, repoRoot, this.#words, host, ARGV_CHANNEL, await inflight.inspect(), next);
357
366
  for (const line of board.lines)
358
367
  this.#io.stdout(`${line}\n`);
359
368
  return board.exitCode;
@@ -451,9 +460,9 @@ export class Cli {
451
460
  if (scene === null)
452
461
  return 1;
453
462
  // THE pre-flight seam (P4.1 T1 · design §1): the single dispatch gate —
454
- // tree-clean → graph → wave → doc-contract — ONE call, the whole sequence
455
- // lives in the seam (session/preflight.ts), the CLI only orchestrates the call
456
- // + the verdict render (zero re-implemented gate here). A refused verdict
463
+ // tree-clean → in-flight → graph → plan-ledger → wave → doc-contract — ONE call,
464
+ // the whole sequence lives in the seam (session/preflight.ts), the CLI orchestrates
465
+ // the call + the verdict render (zero re-implemented gate here). A refused verdict
457
466
  // returns before any brief/lifecycle: no child dispatch ever runs. The
458
467
  // dirty-tree / doc-contract refusals ride the CDD_BLOCKED channel; the
459
468
  // graph / wave refusals keep the pre-existing refusal face. The doc-face read
@@ -466,6 +475,10 @@ export class Cli {
466
475
  const docRel = root.relativize(scene.target !== null && (scene.target.kind === "plan" || scene.target.kind === "spec")
467
476
  ? scene.target.doc
468
477
  : "");
478
+ // The in-flight handle of this tree — ONE instance per invocation, built at the
479
+ // tree root (not the slug workspace: the collision domain is the tree). The gate
480
+ // only inspects it; the lifecycle's real dispatch path acquires it after the gate.
481
+ const inflight = new InFlight(scene.workspace.root, scene.workspace.slug);
469
482
  const preflight = await this.#preflight.vet({
470
483
  verb: verb,
471
484
  type,
@@ -473,21 +486,40 @@ export class Cli {
473
486
  planText: scene.planText,
474
487
  tasks: type === "wave" ? new Set(this.#gate.tasksOf(parsed)) : null,
475
488
  ledger: scene.ledger,
476
- doc: type === "spec" || type === "plan"
489
+ doc: TargetFaceTable.isDocShape(type)
477
490
  ? {
478
- // The ONE declaration reading face (spec §12 · D34) — both the spec and
479
- // the plan dispatch read the doc's front-matter `doc-type:` key;
491
+ // The ONE declaration reading face (spec §12 · D34) — every doc shape
492
+ // dispatch reads the doc's front-matter `doc-type:` key;
480
493
  // a key-less doc reads null and the seam BLOCKs (zero command-type
481
494
  // carve-out, zero filename-suffix fallback).
482
495
  docKey: BoardView.readDocType(root, docRel),
483
496
  path: docRel,
484
497
  }
485
498
  : null,
499
+ inflight,
500
+ // The explicit takeover flag — VOID under --dry-run: the preview face never
501
+ // acquires, so a takeover there would have no write channel at all. The
502
+ // preview still judges the same gate, sees the same holder facts, and exits 1.
503
+ stealStale: !parsed.dryRun && parsed.args.stealStale === "true",
486
504
  });
487
505
  if (!preflight.ok) {
506
+ if (parsed.dryRun && preflight.gate === "in-flight" && preflight.holding !== undefined) {
507
+ // The preview's read-only held face: the SAME gate verdict, rendered as the
508
+ // lock row + the takeover hint, exit 1. Zero write (the preview never
509
+ // acquires / steals / releases).
510
+ for (const line of new Preview({ scene, words: this.#words }).heldBlock(verb, preflight.holding))
511
+ this.#io.stdout(`${line}\n`);
512
+ // The checked face rides the SAME stdout stream here: every dry-run shape
513
+ // (pass / dirty / held / blocked) reports which gates ran.
514
+ this.#renderChecked(preflight, (text) => this.#io.stdout(text));
515
+ return 1;
516
+ }
488
517
  this.#renderPreflightBlocked(verb, preflight, scene);
489
518
  return 1;
490
519
  }
520
+ // The approved path's checked face (P21 §3.4): the SAME rows the refusal path
521
+ // renders — every dispatch reports which rules ran, not only the blocked ones.
522
+ this.#renderChecked(preflight);
491
523
  // The real run's first write point (P11 · §4.2): the workspace — and the
492
524
  // namespace's `.gitignore` keep-out marker — is built HERE, after the
493
525
  // pre-flight verdict and before the brief render / the child dispatch, for
@@ -555,6 +587,10 @@ export class Cli {
555
587
  target: scene.target ?? undefined,
556
588
  capsule: new Capsule(this.#words, ARGV_CHANNEL, HostDetect.detect(process.env), scene.workspace.root.basis),
557
589
  planPath: scene.planPath,
590
+ // The hop derivation's pipeline-station discrimination (§5.2) — the ONE
591
+ // declaration-reading judgment, injected so the session plane never imports a
592
+ // face class.
593
+ docClassOf: (candidate) => BoardView.docClassOf(scene.workspace.root.basis, candidate),
558
594
  });
559
595
  // The requested-phase gate — the line faces (branch/spec/plan) keep the
560
596
  // line-phase readiness check; the task face needs no second gate (the WaveGate's
@@ -564,7 +600,15 @@ export class Cli {
564
600
  if (open !== expected) {
565
601
  const pendingBlock = verdict === "pending-fix" ? this.#gate.pendingFixBlock(scene, reviewed) : null;
566
602
  const docBlock = open === null ? this.#gate.docLineBlock(scene, reviewed) : null;
567
- this.#io.stderr(`cdd ${verb}: cannot dispatch a ${expected} round — ${pendingBlock ?? docBlock ?? (open === null ? "the line holds no open round" : `the next round is ${open}${this.#phaseHint(open)}`)}\n`);
603
+ // The generic refusal renders the SAME `NextHop` the capsule / board /
604
+ // frontier read (P22 §5.2 · the ONE message shape): `<reason> · the next
605
+ // round is <hop>` · `<reason> · next: <station>` · the bare reason. The two
606
+ // identity-aware block messages above own their facts (`reviewed` has no
607
+ // Home in `NextHop`) and stay verbatim.
608
+ const reject = pendingBlock ??
609
+ docBlock ??
610
+ this.#gate.lineHopMessage(scene, this.#gate.lineHop(scene), this.#words);
611
+ this.#io.stderr(`cdd ${verb}: cannot dispatch a ${expected} round — ${reject}\n`);
568
612
  return 1;
569
613
  }
570
614
  }
@@ -580,15 +624,22 @@ export class Cli {
580
624
  let latest = [];
581
625
  let lastStatus = null;
582
626
  for (;;) {
583
- const frame = run.peekNext();
584
- if (frame === null)
627
+ const peeked = run.peekNext();
628
+ if (peeked === null)
585
629
  break;
630
+ const frame = peeked.frame;
586
631
  const waveTasks = frame.target.kind === "wave" ? frame.target.tasks : null;
587
632
  const mismatch = frame.phase !== expected ||
588
633
  (group !== null && (waveTasks === null || !waveTasks.every((id) => group.has(id))));
589
634
  if (mismatch) {
590
635
  if (dispatched === 0) {
591
- this.#io.stderr(`cdd ${verb}: cannot dispatch a ${expected} round — the next round is ${frame.phase}${waveTasks !== null ? ` for wave ${waveTasks.join(",")}` : ""}${this.#phaseHint(frame.phase)}\n`);
636
+ // The lookahead refusal renders the SAME `NextHop` the frame's line just
637
+ // derived (`peekNext`), through the ONE message shape — so one command can
638
+ // never print two different "next round" answers (the gate refusal above
639
+ // and this one name one object). The wave key stays an added clause.
640
+ const waveContext = waveTasks !== null ? ` for wave ${waveTasks.join(",")}` : "";
641
+ const reject = `${this.#gate.lineHopMessage(scene, peeked.hop, this.#words)}${waveContext}`;
642
+ this.#io.stderr(`cdd ${verb}: cannot dispatch a ${expected} round — ${reject}\n`);
592
643
  return 1;
593
644
  }
594
645
  break;
@@ -603,7 +654,19 @@ export class Cli {
603
654
  this.#io.stdout(`${line}\n`);
604
655
  return 0;
605
656
  }
606
- const step = await run.advance();
657
+ // The gate→acquire race: another dispatch took the lock between the in-flight
658
+ // gate's read and this dispatch's acquire. `HoldingError` carries the holder's
659
+ // facts and renders the SAME held BLOCK message the gate renders.
660
+ let step;
661
+ try {
662
+ step = await run.advance();
663
+ }
664
+ catch (error) {
665
+ if (!(error instanceof HoldingError))
666
+ throw error;
667
+ this.#renderHeld(error);
668
+ return 1;
669
+ }
607
670
  if (step === null)
608
671
  break;
609
672
  // The dispatch-entry gate's refusal (the lifecycle's hard child zero-dispatch wiring —
@@ -677,6 +740,9 @@ export class Cli {
677
740
  overallLink: scene.overallLink,
678
741
  },
679
742
  reviews: parsed.paths.reviews,
743
+ // The explicit takeover flag (`--steal-stale`): the ONLY path that displaces a
744
+ // standing in-flight record — and only when its holder is dead.
745
+ stealStale: parsed.args.stealStale === "true",
680
746
  });
681
747
  return harness.step();
682
748
  }
@@ -689,18 +755,6 @@ export class Cli {
689
755
  const artifact = read.kind === "ok" ? read.value : null;
690
756
  return typeof artifact?.base === "string" ? artifact.base : "";
691
757
  }
692
- /** The phase-mismatch hint — what to run instead. */
693
- #phaseHint(phase) {
694
- switch (phase) {
695
- case "implement":
696
- return " — run cdd implement first";
697
- case "review":
698
- case "branch-review":
699
- return " — run cdd review first";
700
- default:
701
- return " — run cdd fix first";
702
- }
703
- }
704
758
  /** Render a refused pre-flight verdict — the work command's BLOCK face (P4.1 T1).
705
759
  * The dirty-tree / doc-contract refusals ride the CDD_BLOCKED channel (the
706
760
  * commit/discard guidance + the named structural findings); the graph / wave
@@ -708,10 +762,13 @@ export class Cli {
708
762
  * wave gate's split row — its done face rides the SAME closedWaves() read the gate
709
763
  * judged, one closed set, one source). */
710
764
  #renderPreflightBlocked(verb, verdict, scene) {
711
- if (verdict.gate === "tree-clean" || verdict.gate === "doc-contract") {
765
+ if (verdict.gate === "tree-clean" ||
766
+ verdict.gate === "in-flight" ||
767
+ verdict.gate === "doc-contract") {
712
768
  this.#io.stderr(`${this.#words.station("blocked")} ${verdict.message ?? ""}\n`);
713
769
  for (const detail of verdict.details ?? [])
714
770
  this.#io.stderr(` ${detail}\n`);
771
+ this.#renderChecked(verdict);
715
772
  return;
716
773
  }
717
774
  this.#io.stderr(`cdd ${verb}: ${verdict.message ?? "the dispatch gate refused the request"}\n`);
@@ -729,6 +786,27 @@ export class Cli {
729
786
  .split("\n"))
730
787
  this.#io.stderr(` ${line}\n`);
731
788
  }
789
+ this.#renderChecked(verdict);
790
+ }
791
+ /** Render the acquire race's held BLOCK — the in-flight gate's own message face
792
+ * (`Words.inFlightBlocked`, one filler for both call sites), exit 1 at the caller. */
793
+ #renderHeld(error) {
794
+ const message = this.#words.inFlightBlocked(error.record, true);
795
+ this.#io.stderr(`${this.#words.station("blocked")} ${message}\n`);
796
+ }
797
+ /** Render the checked face — the pre-flight's per-gate / per-rule rows, derived by
798
+ * the seam from the ONE rule declaration surface (P21 §3.4). It renders on BOTH
799
+ * pre-flight paths (approved and refused) into the diagnostic channel by default;
800
+ * the dry-run held preview passes its stdout writer so every dry-run shape reports
801
+ * the same face: "which rule ran, and what it judged" is a production read face,
802
+ * never a test-only field. The heading and the outcome words come from the word
803
+ * table (zero CLI literal), and the rows indent exactly like the details face
804
+ * above them. */
805
+ #renderChecked(verdict, write) {
806
+ const out = write ?? ((text) => this.#io.stderr(text));
807
+ out(`${this.#words.checkedWords().heading}\n`);
808
+ for (const row of verdict.checked)
809
+ out(` ${row}\n`);
732
810
  }
733
811
  // ---------------------------------------------------------------------------
734
812
  // the work scene — the composition of contract/session/face objects
@@ -775,9 +853,11 @@ export class Cli {
775
853
  slug = resolved;
776
854
  break;
777
855
  }
778
- case "spec": {
856
+ case "phase-spec":
857
+ case "overall":
858
+ case "single-spec": {
779
859
  if (specPath === null || specRel === null)
780
- this.#usage(node, `cdd ${verb} --type spec: missing required --spec <path>`);
860
+ this.#usage(node, `cdd ${verb} --type ${type}: missing required --spec <path>`);
781
861
  // An unreadable target declares no identity: the SAME slug carrier hard-refuses
782
862
  // it (CDD_BLOCKED + exit 1, never a filename-derived key). The T7 null-verdict
783
863
  // face covers the other shape — a document ON DISK that declares no
@@ -787,10 +867,11 @@ export class Cli {
787
867
  return null;
788
868
  slug = resolved;
789
869
  target = { kind: "spec", doc: specPath };
790
- // The judged spec's own `program:` — the parent charter (INPUT_OVERALL) the
791
- // spec-scope reviewer judges the phase against. A spec without `program:`
792
- // (a single-spec) leaves the slot null; an off-disk target reads null here
793
- // and the existing slug-ref invariant reports it (never a second reporter).
870
+ // The judged document's own `program:` — the parent charter (INPUT_OVERALL)
871
+ // the phase-spec reviewer judges the phase against. A document without
872
+ // `program:` (an overall charter or a single-spec) leaves the slot null; an
873
+ // off-disk target reads null here and the existing slug-ref invariant reports
874
+ // it (never a second reporter).
794
875
  const specEntry = index.entryAt(specRel);
795
876
  const overallEntry = specEntry?.program == null ? null : index.overallOf(specEntry.program);
796
877
  overallLink = overallEntry === null ? null : root.relativize(overallEntry.path);
@@ -20,6 +20,7 @@
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";
24
25
  import { HOST_IDS } from "./host.js";
25
26
  /** The argv channel table — the CLI flag/type/enum single source (the engine-config
@@ -29,7 +30,11 @@ import { HOST_IDS } from "./host.js";
29
30
  * text per key, shared by every command that declares it). */
30
31
  export const ARGV_CHANNEL = {
31
32
  plan: { flag: "--plan", type: "path", help: "the CDD plan document path" },
32
- 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
+ },
33
38
  reviews: {
34
39
  flag: "--reviews",
35
40
  type: "path",
@@ -38,12 +43,12 @@ export const ARGV_CHANNEL = {
38
43
  tasks: {
39
44
  flag: "--tasks",
40
45
  type: "int-list",
41
- 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`,
42
47
  },
43
48
  type: {
44
49
  flag: "--type",
45
50
  type: "enum",
46
- values: ["wave", "branch", "spec", "plan"],
51
+ values: ["wave", "branch", "phase-spec", "overall", "plan", "single-spec"],
47
52
  help: "the target face of the round",
48
53
  },
49
54
  base: { flag: "--base", type: "string", help: "the base artifact branch name" },
@@ -55,6 +60,11 @@ export const ARGV_CHANNEL = {
55
60
  help: "the base artifact's source channel",
56
61
  },
57
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
+ },
58
68
  harness: {
59
69
  flag: "--harness",
60
70
  type: "enum",
@@ -129,28 +139,30 @@ export const VALUE_SHAPES = {
129
139
  export const CLI_COMMANDS = [
130
140
  {
131
141
  name: "implement",
132
- description: "run the task implement phase",
142
+ description: `run the task implement phase — at most ${MAX_TASKS_PER_WAVE} tasks per wave`,
133
143
  example: `cdd implement --tasks 1,2 --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
134
144
  keys: [
135
145
  { key: "tasks", required: true },
136
146
  { key: "plan", required: true },
147
+ { key: "stealStale" },
137
148
  ],
138
149
  },
139
150
  {
140
151
  name: "review",
141
- description: "run a review — task | branch | spec | plan",
142
- 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`,
143
154
  keys: [
144
155
  { key: "type", required: true },
145
156
  { key: "tasks" },
146
157
  { key: "plan" },
147
158
  { key: "spec" },
148
159
  { key: "round" },
160
+ { key: "stealStale" },
149
161
  ],
150
162
  },
151
163
  {
152
164
  name: "fix",
153
- description: "fix review findings — task | branch | spec | plan",
165
+ description: "fix review findings — wave | branch | phase-spec | overall | plan | single-spec",
154
166
  example: "cdd fix --type wave --tasks 1 --reviews tasks-1-review-1.json",
155
167
  keys: [
156
168
  { key: "type", required: true },
@@ -158,6 +170,7 @@ export const CLI_COMMANDS = [
158
170
  { key: "reviews" },
159
171
  { key: "spec" },
160
172
  { key: "plan" },
173
+ { key: "stealStale" },
161
174
  ],
162
175
  },
163
176
  {
@@ -212,7 +225,7 @@ export const CLI_COMMANDS = [
212
225
  },
213
226
  {
214
227
  name: "board",
215
- 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)",
216
229
  example: `cdd board --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
217
230
  keys: [{ key: "plan" }, { key: "spec" }],
218
231
  },
@@ -236,23 +249,28 @@ export const SCHEMA_TYPE_KEYS = {
236
249
  phaseSpec: "phase-spec",
237
250
  };
238
251
  /** The conditional required group per work verb + target type — the preAction hook's
239
- * data face (spec §4.2): review `{plan}` / `{spec}` / `{plan}` · fix `{plan}` /
240
- * `{spec}` / `{findings, plan}` — every branch face carries the `--plan` workspace
241
- * identity (the branch line holds no commit ref: the review judges the live tree,
242
- * the scope anchor BASE_BRANCH is engine-injected at dispatch). Keyed by declared
243
- * flag spelling; non-exclusive — a round declaring both `--plan` and `--spec`
244
- * 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). */
245
259
  export const REQUIRED_GROUPS = {
246
260
  review: {
247
261
  wave: ["--plan"],
248
- spec: ["--spec"],
249
- plan: ["--plan"],
250
262
  branch: ["--plan"],
263
+ "phase-spec": ["--spec"],
264
+ overall: ["--spec"],
265
+ plan: ["--plan"],
266
+ "single-spec": ["--spec"],
251
267
  },
252
268
  fix: {
253
269
  wave: ["--plan"],
254
- spec: ["--spec"],
255
- plan: ["--plan"],
256
270
  branch: ["--reviews", "--plan"],
271
+ "phase-spec": ["--spec"],
272
+ overall: ["--spec"],
273
+ plan: ["--plan"],
274
+ "single-spec": ["--spec"],
257
275
  },
258
276
  };