@oscaner-skills/cdd-engine 1.0.0 → 2.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 (99) hide show
  1. package/README.md +9 -8
  2. package/README.zh-CN.md +9 -8
  3. package/package.json +15 -22
  4. package/src-next/__tests__/bin.test.ts +128 -0
  5. package/src-next/__tests__/smoke.integration.test.ts +202 -0
  6. package/src-next/__tests__/zero-dep.test.ts +134 -0
  7. package/src-next/bin.ts +61 -0
  8. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +238 -0
  9. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +153 -0
  10. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +173 -0
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +89 -0
  12. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +225 -0
  13. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +155 -0
  14. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +175 -0
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +85 -0
  16. package/src-next/contract/__tests__/declare.test.ts +242 -0
  17. package/src-next/contract/__tests__/doc.test.ts +358 -0
  18. package/src-next/contract/__tests__/judge.test.ts +873 -0
  19. package/src-next/contract/__tests__/lint.test.ts +314 -0
  20. package/src-next/contract/__tests__/project.test.ts +419 -0
  21. package/src-next/contract/__tests__/translate.test.ts +96 -0
  22. package/src-next/contract/declare.ts +983 -0
  23. package/src-next/contract/doc.ts +753 -0
  24. package/src-next/contract/invariants.ts +1268 -0
  25. package/src-next/contract/judge.ts +142 -0
  26. package/src-next/contract/lint.ts +275 -0
  27. package/src-next/contract/project.ts +596 -0
  28. package/src-next/contract/skill-anatomy.ts +273 -0
  29. package/src-next/contract/translate.ts +113 -0
  30. package/src-next/face/__tests__/board-view.test.ts +948 -0
  31. package/src-next/face/__tests__/capsule.test.ts +276 -0
  32. package/src-next/face/__tests__/channel-closure.guard.test.ts +102 -0
  33. package/src-next/face/__tests__/cli.test.ts +4643 -0
  34. package/src-next/face/__tests__/face.test.ts +289 -0
  35. package/src-next/face/__tests__/graph-view.test.ts +61 -0
  36. package/src-next/face/__tests__/host.test.ts +24 -0
  37. package/src-next/face/__tests__/negation.ts +6 -0
  38. package/src-next/face/__tests__/projection.test.ts +301 -0
  39. package/src-next/face/__tests__/sync-runner.test.ts +70 -0
  40. package/src-next/face/__tests__/words.guard.test.ts +93 -0
  41. package/src-next/face/artifacts.ts +195 -0
  42. package/src-next/face/board-view.ts +662 -0
  43. package/src-next/face/capsule.ts +149 -0
  44. package/src-next/face/cli.ts +819 -0
  45. package/src-next/face/declare.ts +326 -0
  46. package/src-next/face/gate.ts +170 -0
  47. package/src-next/face/graph-view.ts +74 -0
  48. package/src-next/face/host.ts +326 -0
  49. package/src-next/face/lifecycle.ts +700 -0
  50. package/src-next/face/projection.ts +282 -0
  51. package/src-next/face/route-render.ts +160 -0
  52. package/src-next/face/words.ts +296 -0
  53. package/src-next/infra/__tests__/infra.test.ts +287 -0
  54. package/src-next/infra/config.ts +42 -0
  55. package/src-next/infra/git.ts +39 -0
  56. package/src-next/infra/process.ts +34 -0
  57. package/src-next/infra/runtime.ts +185 -0
  58. package/src-next/infra/workspace.ts +232 -0
  59. package/src-next/render/__tests__/render.test.ts +499 -0
  60. package/src-next/render/__tests__/skeleton.test.ts +466 -0
  61. package/src-next/render/brief.ts +121 -0
  62. package/src-next/render/issue-body.ts +159 -0
  63. package/src-next/render/skeleton.ts +437 -0
  64. package/src-next/render/templates.ts +650 -0
  65. package/src-next/session/__tests__/graph.test.ts +270 -0
  66. package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
  67. package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
  68. package/src-next/session/__tests__/ledger.test.ts +744 -0
  69. package/src-next/session/__tests__/next.test.ts +368 -0
  70. package/src-next/session/__tests__/preflight.test.ts +491 -0
  71. package/src-next/session/__tests__/run.test.ts +1014 -0
  72. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
  73. package/src-next/session/__tests__/wave.test.ts +469 -0
  74. package/src-next/session/faces.ts +110 -0
  75. package/src-next/session/graph.ts +411 -0
  76. package/src-next/session/handoff-schema.ts +373 -0
  77. package/src-next/session/ledger.ts +1004 -0
  78. package/src-next/session/next.ts +192 -0
  79. package/src-next/session/preflight.ts +240 -0
  80. package/src-next/session/run.ts +606 -0
  81. package/src-next/session/state.ts +30 -0
  82. package/src-next/session/wave.ts +139 -0
  83. package/templates/report/issue-body.json +18 -20
  84. package/dist/chunks/branch.mjs +0 -480
  85. package/dist/chunks/docs.mjs +0 -253
  86. package/dist/chunks/task.mjs +0 -913
  87. package/dist/cli.mjs +0 -5457
  88. package/dist/documents/schema/add-phase-protocol.json +0 -126
  89. package/dist/documents/schema/overall.json +0 -361
  90. package/dist/documents/schema/phase-spec.json +0 -145
  91. package/dist/documents/schema/plan.json +0 -191
  92. package/dist/documents/schema/skill-anatomy.json +0 -233
  93. package/dist/resources/harness-registry.json +0 -49
  94. package/dist/shared/cdd-engine.liioziig.mjs +0 -184
  95. package/templates/engine-config.json +0 -302
  96. package/templates/schema/cache-profile-schema.json +0 -23
  97. package/templates/schema/docs-handoff-schema.json +0 -129
  98. package/templates/schema/task-handoff-schema.json +0 -332
  99. package/templates/template-contract.json +0 -231
@@ -0,0 +1,282 @@
1
+ // packages/cdd-engine/src-next/face/projection.ts
2
+ // §2.1 — the single projection class: the declare single surface (face/declare.ts
3
+ // — the argv channel + the seven-command rows + REQUIRED_GROUPS) assembles the
4
+ // commander command tree, ENTIRELY in the constructor (the constructor-is-the-
5
+ // assembly stance · §2.1/§2.3):
6
+ // the top-level `cdd` program · the seven commands with their descriptions · the
7
+ // nested leaves (base set|get · schema get|gen · issue render) · the binding rules
8
+ // (command keys → .option()/.requiredOption() · positionals → .argument() ·
9
+ // bool rows single-spelling · the program scope merged into every node · the help
10
+ // channel row un-projected — the built-in helpOption) · the parseArg value-domain
11
+ // validation (commander.InvalidArgumentError · §4.1 · the retired validator) ·
12
+ // the program-level preAction conditional-required hook (REQUIRED_GROUPS · §4.2)
13
+ // · the help injections (§5.1 — Examples + the --dry-run tail note).
14
+ //
15
+ // The class's one exit is `readonly program: Command` — the T3 composition root
16
+ // parses through it and Its help/usage bytes are the commander-native product (the
17
+ // self-built usage corpus never existed here). Zero module-level behavior-
18
+ // carrying bare functions — the projection algorithm lives in the single
19
+ // CommandTreeBuilder class; the value-domain rules are declaration data
20
+ // (declare.ts VALUE_SHAPES), read by the builder's one table-driven executor
21
+ // (the plan's zero-bare-function discipline).
22
+
23
+ import { Command, InvalidArgumentError } from "commander";
24
+
25
+ import {
26
+ ARGV_CHANNEL,
27
+ type ChannelArgRow,
28
+ CLI_COMMANDS,
29
+ type CliArgSpec,
30
+ type CliCommandSpec,
31
+ type CliLeafSpec,
32
+ type CliValueOverride,
33
+ REQUIRED_GROUPS,
34
+ SCHEMA_TYPE_KEYS,
35
+ VALUE_SHAPES,
36
+ } from "./declare.ts";
37
+
38
+ /** The primary schema <type> spellings — the self-mapping vocabulary rows (the
39
+ * argument description's value list; derived from the one table, never a
40
+ * hand-written second list). */
41
+ const SCHEMA_PRIMARY_KEYS: readonly string[] = Object.entries(SCHEMA_TYPE_KEYS)
42
+ .filter(([spelling, key]) => spelling === key)
43
+ .map(([spelling]) => spelling);
44
+
45
+ /** The channel table widened to its record face — the literal const stays the
46
+ * declaration's data source (its `satisfies` pins the row type at declare.ts);
47
+ * the projection indexes it by declared key at runtime. */
48
+ const CHANNEL_TABLE: Readonly<Record<string, ChannelArgRow>> = ARGV_CHANNEL;
49
+
50
+ /** The value-domain table widened to its lookup face — the literal const stays
51
+ * the declaration's data source; the projection indexes it by the row's
52
+ * declared type and absence (the string/path/bool faces) registers no parser. */
53
+ const SHAPE_TABLE: Readonly<
54
+ Record<string, { parse(raw: string, row: ChannelArgRow): string } | undefined>
55
+ > = VALUE_SHAPES;
56
+
57
+ /**
58
+ * CommandTreeBuilder — the declaration → commander projection. The constructor
59
+ * performs the whole assembly; `program` is the complete tree (parse + help +
60
+ * validation + the preAction groups all wired). The value-domain rejections throw
61
+ * commander.InvalidArgumentError (the composed pipeline names the option + value
62
+ * with the commander-native bytes — the usage domain's exit 2 is the run face's
63
+ * normalization, §3.1).
64
+ */
65
+ export class CommandTreeBuilder {
66
+ /** The assembled commander program — the composition root's parse + help face. */
67
+ readonly program: Command;
68
+
69
+ constructor() {
70
+ this.program = new Command("cdd");
71
+ // The exit override is wired FIRST — every .command() copies the inherited
72
+ // settings (incl. the callback), so a parse rejection anywhere in the tree
73
+ // throws the CommanderError instead of process.exit (the discrimination face
74
+ // of §3.1: err.code + err.exitCode). The projection tests assert through the
75
+ // same thrown errors.
76
+ this.program.exitOverride();
77
+ this.program.description("the CDD engine's command line");
78
+ this.program.addHelpText("afterAll", "program flags (accepted at any position): --dry-run");
79
+ this.#bindProgramScopes(this.program);
80
+ this.#injectProgramExamples();
81
+ for (const spec of CLI_COMMANDS) this.#projectCommand(spec);
82
+ this.program.hook("preAction", (_thisCommand, actionCommand) =>
83
+ this.#assertRequiredGroups(actionCommand),
84
+ );
85
+ }
86
+
87
+ // ---------------------------------------------------------------------------
88
+ // the command-tree projection
89
+ // ---------------------------------------------------------------------------
90
+
91
+ /** One command node — the description + the option/argument binding + the
92
+ * program scopes + the Examples injection + the nested leaves. */
93
+ #projectCommand(spec: CliCommandSpec): void {
94
+ const node = this.program.command(spec.name);
95
+ node.description(spec.description);
96
+ this.#bindOptions(node, spec.keys);
97
+ this.#bindArguments(node, spec.positionals);
98
+ this.#bindProgramScopes(node);
99
+ if (spec.example !== undefined) {
100
+ node.addHelpText("after", `Examples:\n ${spec.example}`);
101
+ }
102
+ for (const leaf of spec.leaves ?? []) this.#projectLeaf(node, leaf);
103
+ }
104
+
105
+ /** One leaf node (base set|get · schema get|gen · issue render) — the leaf
106
+ * granularity is structural: each leaf binds its OWN declared keys (the §5.3
107
+ * did-you-mean candidate sets follow the errored node, never a sibling's). */
108
+ #projectLeaf(parent: Command, leaf: CliLeafSpec): void {
109
+ const node = parent.command(leaf.name);
110
+ node.description(leaf.description);
111
+ this.#bindOptions(node, leaf.keys);
112
+ this.#bindArguments(node, leaf.positionals);
113
+ this.#bindProgramScopes(node);
114
+ }
115
+
116
+ /** The option binding — the surface's declared keys → .option() /
117
+ * .requiredOption() (the row's flag + the value-domain token + the channel
118
+ * help text; the required rows ride .requiredOption()). */
119
+ #bindOptions(node: Command, keys: readonly CliArgSpec[]): void {
120
+ for (const declared of keys) {
121
+ const row = CHANNEL_TABLE[declared.key];
122
+ // The channel audit (guard §2.2) closes every declared key — an absent row
123
+ // here is structurally unreachable; the guard stays the single check.
124
+ if (row === undefined) continue;
125
+ this.#registerOption(node, declared, row);
126
+ }
127
+ }
128
+
129
+ /** One option registration on a node — the flags string (the value-domain token
130
+ * rides the option's own suffix, §5.2), the channel description (+ the
131
+ * required marker) and the value-domain parseArg (when the type validates). */
132
+ #registerOption(node: Command, declared: CliArgSpec, row: ChannelArgRow): void {
133
+ const token = this.#valueToken(row, declared.valueType);
134
+ const flags = `${row.flag}${token === "" ? "" : ` ${token}`}`;
135
+ const help = `${this.#optionHelp(row, declared.valueType)}${declared.required === true ? " (required)" : ""}`;
136
+ const parseArg = this.#parseArgOf(row, declared.valueType);
137
+ if (declared.required === true) {
138
+ if (parseArg === undefined) node.requiredOption(flags, help);
139
+ else node.requiredOption(flags, help, parseArg);
140
+ } else if (parseArg === undefined) {
141
+ node.option(flags, help);
142
+ } else {
143
+ node.option(flags, help, parseArg);
144
+ }
145
+ }
146
+
147
+ /** The positional binding — one .argument() per declared positional (required →
148
+ * `<name>`, optional → `[name]`; the schema <type> argument validates through
149
+ * the typeKey vocabulary). */
150
+ #bindArguments(node: Command, positionals: readonly CliArgSpec[] | undefined): void {
151
+ for (const positional of positionals ?? []) {
152
+ const raw = positional.key;
153
+ const bracket = positional.required === true ? `<${raw}>` : `[${raw}]`;
154
+ const description = this.#argumentDescription(raw);
155
+ const parseArg = raw === "type" ? (value: string) => this.#parseTypeKey(value) : undefined;
156
+ if (parseArg === undefined) {
157
+ if (description === "") node.argument(bracket);
158
+ else node.argument(bracket, description);
159
+ } else {
160
+ node.argument(bracket, description, parseArg);
161
+ }
162
+ }
163
+ }
164
+
165
+ /** The program-scope merge — every `scope: "program"` channel row registers on
166
+ * the node (the any-position program-flag semantics, §2.1 cli.test.ts pins
167
+ * 494/698); the help row is skipped (the built-in helpOption face — never
168
+ * re-registered). Each node registers its own copy once (never re-registered). */
169
+ #bindProgramScopes(node: Command): void {
170
+ for (const [key, row] of Object.entries(CHANNEL_TABLE)) {
171
+ if (row.scope !== "program") continue;
172
+ if (key === "help") continue;
173
+ this.#registerOption(node, { key, required: false }, row);
174
+ }
175
+ }
176
+
177
+ // ---------------------------------------------------------------------------
178
+ // the value-domain validation (parseArg · commander.InvalidArgumentError · §4.1)
179
+ // ---------------------------------------------------------------------------
180
+
181
+ /** The value-domain token of one option — the display suffix (`<path>` ·
182
+ * `<n|n,n,…>` · `<a|b|c>` · `<n>`); the branch value-type override carries its
183
+ * own domain, the bool/string faces carry none. */
184
+ #valueToken(row: ChannelArgRow, override: CliValueOverride | undefined): string {
185
+ if (override === "branch") return "<branch>";
186
+ switch (row.type) {
187
+ case "path":
188
+ return "<path>";
189
+ case "int-list":
190
+ return "<n|n,n,…>";
191
+ case "enum":
192
+ return `<${[...(row.values ?? [])].join("|")}>`;
193
+ case "int":
194
+ return "<n>";
195
+ default:
196
+ // bool / string — the flag alone carries the value domain face.
197
+ return "";
198
+ }
199
+ }
200
+
201
+ /** The option's help text — the channel row's single-source flag-level line;
202
+ * the branch value-type override swaps it for its own domain (the base-set
203
+ * face names the branch — the same override family as #valueToken's `<branch>`
204
+ * token). */
205
+ #optionHelp(row: ChannelArgRow, override: CliValueOverride | undefined): string {
206
+ if (override === "branch") return "the base branch name";
207
+ return row.help ?? "";
208
+ }
209
+
210
+ /** The option's custom parser — the value-domain check of the validated
211
+ * types, table-driven from the declaration's VALUE_SHAPES (the branch
212
+ * override and the string/path/bool faces register none — a row without a
213
+ * shape gets no parser; absence is the registered face). */
214
+ #parseArgOf(
215
+ row: ChannelArgRow,
216
+ override: CliValueOverride | undefined,
217
+ ): ((value: string) => string) | undefined {
218
+ if (override === "branch") return undefined;
219
+ const shape = SHAPE_TABLE[row.type];
220
+ if (shape === undefined) return undefined;
221
+ return (value) => shape.parse(value, row);
222
+ }
223
+
224
+ /** The schema `<type>` vocabulary check — the primary spellings validate and
225
+ * normalize to themselves, the legacy `phaseSpec` alias normalizes to the kebab
226
+ * key, an out-of-vocabulary type rejects (spec §5.3). */
227
+ #parseTypeKey(raw: string): string {
228
+ const key = SCHEMA_TYPE_KEYS[raw];
229
+ if (key === undefined) {
230
+ throw new InvalidArgumentError(
231
+ `unknown schema type: ${raw} (available: ${SCHEMA_PRIMARY_KEYS.join(", ")})`,
232
+ );
233
+ }
234
+ return key;
235
+ }
236
+
237
+ /** The argument's help description — the schema <type> face names its primary
238
+ * vocabulary (single-sourced at SCHEMA_TYPE_KEYS). */
239
+ #argumentDescription(raw: string): string {
240
+ if (raw === "type") return `the schema type — ${SCHEMA_PRIMARY_KEYS.join(" | ")}`;
241
+ return "";
242
+ }
243
+
244
+ // ---------------------------------------------------------------------------
245
+ // the conditional-required groups (preAction · §4.2)
246
+ // ---------------------------------------------------------------------------
247
+
248
+ /** The preAction assertion — the review/fix work commands' REQUIRED_GROUPS
249
+ * data: the target type's required face must be present on the action command's
250
+ * opts; a missing face throws the same InvalidArgumentError pipeline as a
251
+ * parseArg rejection (the run face normalizes it into the usage domain's exit
252
+ * 2). Non-exclusive — both `--plan` and `--spec` stay accepted together
253
+ * (no mutual-exclusion rejection). */
254
+ #assertRequiredGroups(actionCommand: Command): void {
255
+ const verb = actionCommand.name();
256
+ if (verb !== "review" && verb !== "fix") return;
257
+ const type = actionCommand.opts().type as string | undefined;
258
+ if (type === undefined) return;
259
+ const group = REQUIRED_GROUPS[verb][type];
260
+ if (group === undefined) return;
261
+ const missing = group.filter((flag) => actionCommand.opts()[flag.slice(2)] === undefined);
262
+ if (missing.length > 0) {
263
+ throw new InvalidArgumentError(`${missing.join(" ")} required when --type ${type}`);
264
+ }
265
+ }
266
+
267
+ // ---------------------------------------------------------------------------
268
+ // the help injections (§5.1 — Examples + the --dry-run tail note)
269
+ // ---------------------------------------------------------------------------
270
+
271
+ /** The program face's Examples section — the rows' example lines (the P1
272
+ * sentences, single-sourced at the CLI_COMMANDS `example` fields). */
273
+ #injectProgramExamples(): void {
274
+ const examples: string[] = [];
275
+ for (const spec of CLI_COMMANDS) {
276
+ if (spec.example !== undefined) examples.push(` ${spec.example}`);
277
+ }
278
+ if (examples.length > 0) {
279
+ this.program.addHelpText("after", `Examples:\n${examples.join("\n")}`);
280
+ }
281
+ }
282
+ }
@@ -0,0 +1,160 @@
1
+ // packages/cdd-engine/src-next/face/route-render.ts
2
+ // D40 — the ONE route → `next:` literal renderer (the shared render point): both
3
+ // the Capsule (a round's own line) and the board (a line's frontier) render the
4
+ // exact same Route into the exact same literal through this single class, so the
5
+ // board's `next:` and the engine's `next:` are byte-identical by construction
6
+ // (the retired board `#entryText` / capsule `#doneText` pair — one renderer now).
7
+ //
8
+ // · an active C5 hop (`implement` / `review` / `fix` / `soft-cap`) renders the
9
+ // complete executable argv composed from the frame facts (the RouteTarget's
10
+ // type + id + plan) through the argv-channel flag spellings — the same channel
11
+ // the CLI parse reads (never a second hard-coded format string);
12
+ // · the face-to-face `handoff` renders the pipeline entry: a `ref` resolves
13
+ // REFS[ref][host] (the `""` host falls back to the claude form — never a bare
14
+ // plugin guess), a `literal` fills its `<plan>` slot, a `done` entry the bare
15
+ // terminal word;
16
+ // · the bare `done` is the terminal word (its no-target face).
17
+ //
18
+ // The route-borne prose (the fix readback suffix · the soft-cap message) rides
19
+ // declared constants from session/next.ts, rendered by reference, never restated.
20
+ // Module-level exports are the class — zero behavior-carrying bare functions.
21
+
22
+ import type { RouteTarget } from "../session/faces.ts";
23
+ import { FIX_READBACK_SUFFIX, type Route } from "../session/next.ts";
24
+ import { REFS } from "./host.ts";
25
+ import type { Words } from "./words.ts";
26
+
27
+ /** The argv-channel flag row the renderer reads (structural — the engine's channel
28
+ * rows carry the `flag` spelling; the default `--<key>` covers a row-less key so the
29
+ * render never hard-codes a spelling). */
30
+ export interface RouteChannelRow {
31
+ flag?: string;
32
+ }
33
+
34
+ /**
35
+ * RouteRenderer — the single route → `next:` literal face (D40). One instance holds
36
+ * the render facts the literal needs (the word table · the argv-channel spellings ·
37
+ * the host harness id); render() turns a Route (+ the frame's own RouteTarget) into
38
+ * the `next:` value. The Capsule and the board both delegate here — no second
39
+ * renderer.
40
+ */
41
+ export class RouteRenderer {
42
+ /** The single word table — the literal's whole vocabulary source. */
43
+ readonly #words: Words;
44
+ /** The argv-channel flag spellings — the declared render source (parse's own). */
45
+ readonly #channels: Readonly<Record<string, RouteChannelRow>>;
46
+ /** The host harness id — the skill-ref resolution key of the handoff/`done`
47
+ * pipeline lookup (REFS[ref][host]; `""` falls back to the claude form). */
48
+ readonly #host: string;
49
+
50
+ constructor(words: Words, channels: Readonly<Record<string, RouteChannelRow>> = {}, host = "") {
51
+ this.#words = words;
52
+ this.#channels = channels;
53
+ this.#host = host;
54
+ }
55
+
56
+ /** render(route, target) → the `next:` value: the complete executable command (a
57
+ * C5 hop), the pipeline entry (a `handoff`), or the bare terminal word (`done`).
58
+ * The additive optional RouteTarget supplies the frame's own type + id + plan for
59
+ * the executable literal; without it the route renders its bare classifier
60
+ * fallbacks. */
61
+ render(route: Route, target?: RouteTarget | null): string {
62
+ switch (route.kind) {
63
+ case "done":
64
+ return this.#words.routeWord("done");
65
+ case "handoff":
66
+ return this.#handoffText(route, target);
67
+ case "next-wave":
68
+ return `${this.#words.routeWord("implement")} ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("tasks")} ${route.tasks}`;
69
+ case "review":
70
+ return this.#reviewText(target);
71
+ case "fix":
72
+ return this.#fixText(route, target);
73
+ case "soft-cap":
74
+ return route.message;
75
+ }
76
+ }
77
+
78
+ /** The declared flag spelling of one channel key — the argv channel the CLI parse
79
+ * itself resolves (never a hard-coded format string; `--<key>` for a row-less key). */
80
+ #flag(key: string): string {
81
+ return this.#channels[key]?.flag ?? `--${key}`;
82
+ }
83
+
84
+ /** The plan path of the literal — the frame's plan fact (the implement literal's
85
+ * required `--plan`), the `<plan>` placeholder when the fact is absent (the bare
86
+ * fallback face — the mirror of the crash-resume's `<plan>` seed). */
87
+ #planOf(target?: RouteTarget | null): string {
88
+ return target?.plan ?? "<plan>";
89
+ }
90
+
91
+ /** The review hop's literal — `review --type <wave|spec|plan|branch> <type-arg>`
92
+ * (`--type` renders only where the verb's type discriminates — review/fix are
93
+ * multi-type, so they always carry it; absent target → the bare verb). */
94
+ #reviewText(target?: RouteTarget | null): string {
95
+ const verb = this.#words.routeWord("review");
96
+ const type = target?.type ?? null;
97
+ if (type === "wave") {
98
+ // The wave review literal carries its runtime-required `--plan` — the same
99
+ // assembly the implement/next-wave and fix→wave branches share (a missing flag
100
+ // parses green yet refuses the dispatch at run time).
101
+ return `${verb} ${this.#flag("type")} wave ${this.#flag("tasks")} ${target!.id} ${this.#flag("plan")} ${this.#planOf(target)}`;
102
+ }
103
+ if (type === "spec") {
104
+ return `${verb} ${this.#flag("type")} spec ${this.#flag("spec")} ${target!.id}`;
105
+ }
106
+ if (type === "plan") {
107
+ return `${verb} ${this.#flag("type")} plan ${this.#flag("plan")} ${target!.id}`;
108
+ }
109
+ if (type === "branch") {
110
+ // The branch re-review literal carries only the workspace-identity `--plan` —
111
+ // the review judges the live tree, so no range rides the command (the scope
112
+ // anchor BASE_BRANCH is engine-injected at dispatch).
113
+ return `${verb} ${this.#flag("type")} branch ${this.#flag("plan")} ${this.#planOf(target)}`;
114
+ }
115
+ return verb;
116
+ }
117
+
118
+ /** The one-way fix hop's literal — `fix --type <type> <type-arg> --findings <path>
119
+ * <readback>` (the readback suffix the declared constant, rendered by reference). */
120
+ #fixText(route: Extract<Route, { kind: "fix" }>, target?: RouteTarget | null): string {
121
+ if (route.findings === undefined) return this.#words.routeWord("fix");
122
+ const verb = this.#words.routeWord("fix");
123
+ const type = target?.type ?? null;
124
+ const id = target?.id ?? "";
125
+ if (type === "wave") {
126
+ return `${verb} ${this.#flag("type")} wave ${this.#flag("tasks")} ${id} ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("findings")} ${route.findings} ${FIX_READBACK_SUFFIX}`;
127
+ }
128
+ if (type === "spec") {
129
+ return `${verb} ${this.#flag("type")} spec ${this.#flag("spec")} ${id} ${this.#flag("findings")} ${route.findings} ${FIX_READBACK_SUFFIX}`;
130
+ }
131
+ if (type === "plan") {
132
+ return `${verb} ${this.#flag("type")} plan ${this.#flag("plan")} ${id} ${this.#flag("findings")} ${route.findings} ${FIX_READBACK_SUFFIX}`;
133
+ }
134
+ if (type === "branch") {
135
+ // The branch fix literal carries the workspace-identity `--plan` (isomorphic
136
+ // with the wave fix branch — a plan-less target resolves to the empty
137
+ // ref.short() directory, the workspace double identity).
138
+ return `${verb} ${this.#flag("type")} branch ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("findings")} ${route.findings} ${FIX_READBACK_SUFFIX}`;
139
+ }
140
+ return `${verb} ${this.#flag("findings")} ${route.findings} ${FIX_READBACK_SUFFIX}`;
141
+ }
142
+
143
+ /** The face-to-face handoff render — the pipeline entry: a `ref` resolves
144
+ * REFS[ref][host] (the `""` host falls back to the claude form), a `literal`
145
+ * fills its `<plan>` slot with the frame's plan fact, a `done` entry renders the
146
+ * bare word. Never a hard-coded plugin spelling. */
147
+ #handoffText(route: Extract<Route, { kind: "handoff" }>, target?: RouteTarget | null): string {
148
+ const entry = route.entry;
149
+ if (entry.kind === "done") return this.#words.routeWord("done");
150
+ if (entry.kind === "literal") return entry.literal.replace("<plan>", this.#planOf(target));
151
+ // The ref table read over a dynamic ref key — the local's shape (`string → per-host
152
+ // form`) is the HostReferenceTable contract, so the lookup needs no key cast.
153
+ const table: Readonly<
154
+ Record<string, Readonly<Record<string, string | undefined>> | undefined>
155
+ > = REFS;
156
+ const row = table[entry.ref];
157
+ if (row === undefined) return this.#words.routeWord("done");
158
+ return row[this.#host] ?? row.claude ?? this.#words.routeWord("done");
159
+ }
160
+ }