@oscaner-skills/cdd-engine 2.0.0 → 3.0.1

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 (127) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/{src-next/bin.ts → dist/bin.js} +18 -21
  4. package/dist/contract/declare.js +998 -0
  5. package/dist/contract/doc.js +565 -0
  6. package/dist/contract/frontmatter.js +209 -0
  7. package/dist/contract/home-extractors.js +379 -0
  8. package/dist/contract/invariants.js +1030 -0
  9. package/dist/contract/judge.js +109 -0
  10. package/dist/contract/lint.js +206 -0
  11. package/dist/contract/project.js +371 -0
  12. package/dist/contract/skill-anatomy.js +156 -0
  13. package/dist/contract/translate.js +85 -0
  14. package/dist/face/artifacts.js +189 -0
  15. package/dist/face/board-view.js +522 -0
  16. package/dist/face/capsule.js +141 -0
  17. package/dist/face/cli.js +891 -0
  18. package/dist/face/declare.js +241 -0
  19. package/dist/face/gate.js +158 -0
  20. package/dist/face/graph-view.js +66 -0
  21. package/dist/face/host.js +211 -0
  22. package/dist/face/lifecycle.js +603 -0
  23. package/dist/face/preview.js +136 -0
  24. package/dist/face/projection.js +259 -0
  25. package/dist/face/route-render.js +162 -0
  26. package/dist/face/termination.js +482 -0
  27. package/dist/face/words.js +220 -0
  28. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  29. package/dist/infra/doc-roots.js +19 -0
  30. package/dist/infra/git.js +37 -0
  31. package/dist/infra/process.js +22 -0
  32. package/dist/infra/root.js +62 -0
  33. package/dist/infra/runtime.js +85 -0
  34. package/dist/infra/workspace.js +276 -0
  35. package/dist/render/brief.js +82 -0
  36. package/dist/render/issue-body.js +129 -0
  37. package/dist/render/skeleton.js +434 -0
  38. package/dist/render/templates.js +520 -0
  39. package/dist/session/faces.js +38 -0
  40. package/dist/session/graph.js +309 -0
  41. package/dist/session/handoff-schema.js +295 -0
  42. package/dist/session/ledger.js +762 -0
  43. package/dist/session/next.js +211 -0
  44. package/dist/session/preflight.js +194 -0
  45. package/dist/session/round-naming.js +73 -0
  46. package/dist/session/run.js +441 -0
  47. package/dist/session/state.js +8 -0
  48. package/dist/session/wave.js +92 -0
  49. package/package.json +8 -7
  50. package/templates/report/issue-body.json +0 -46
  51. package/src-next/__tests__/bin.test.ts +0 -128
  52. package/src-next/__tests__/smoke.integration.test.ts +0 -202
  53. package/src-next/__tests__/zero-dep.test.ts +0 -134
  54. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -238
  55. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -153
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -173
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -89
  58. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -225
  59. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -155
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -175
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -85
  62. package/src-next/contract/__tests__/declare.test.ts +0 -242
  63. package/src-next/contract/__tests__/doc.test.ts +0 -358
  64. package/src-next/contract/__tests__/judge.test.ts +0 -873
  65. package/src-next/contract/__tests__/lint.test.ts +0 -314
  66. package/src-next/contract/__tests__/project.test.ts +0 -419
  67. package/src-next/contract/__tests__/translate.test.ts +0 -96
  68. package/src-next/contract/declare.ts +0 -983
  69. package/src-next/contract/doc.ts +0 -753
  70. package/src-next/contract/invariants.ts +0 -1268
  71. package/src-next/contract/judge.ts +0 -142
  72. package/src-next/contract/lint.ts +0 -275
  73. package/src-next/contract/project.ts +0 -596
  74. package/src-next/contract/skill-anatomy.ts +0 -273
  75. package/src-next/contract/translate.ts +0 -113
  76. package/src-next/face/__tests__/board-view.test.ts +0 -948
  77. package/src-next/face/__tests__/capsule.test.ts +0 -276
  78. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -102
  79. package/src-next/face/__tests__/cli.test.ts +0 -4643
  80. package/src-next/face/__tests__/face.test.ts +0 -289
  81. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  82. package/src-next/face/__tests__/host.test.ts +0 -24
  83. package/src-next/face/__tests__/negation.ts +0 -6
  84. package/src-next/face/__tests__/projection.test.ts +0 -301
  85. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
  86. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  87. package/src-next/face/artifacts.ts +0 -195
  88. package/src-next/face/board-view.ts +0 -662
  89. package/src-next/face/capsule.ts +0 -149
  90. package/src-next/face/cli.ts +0 -819
  91. package/src-next/face/declare.ts +0 -326
  92. package/src-next/face/gate.ts +0 -170
  93. package/src-next/face/graph-view.ts +0 -74
  94. package/src-next/face/host.ts +0 -326
  95. package/src-next/face/lifecycle.ts +0 -700
  96. package/src-next/face/projection.ts +0 -282
  97. package/src-next/face/route-render.ts +0 -160
  98. package/src-next/face/words.ts +0 -296
  99. package/src-next/infra/__tests__/infra.test.ts +0 -287
  100. package/src-next/infra/git.ts +0 -39
  101. package/src-next/infra/process.ts +0 -34
  102. package/src-next/infra/runtime.ts +0 -185
  103. package/src-next/infra/workspace.ts +0 -232
  104. package/src-next/render/__tests__/render.test.ts +0 -499
  105. package/src-next/render/__tests__/skeleton.test.ts +0 -466
  106. package/src-next/render/brief.ts +0 -121
  107. package/src-next/render/issue-body.ts +0 -159
  108. package/src-next/render/skeleton.ts +0 -437
  109. package/src-next/render/templates.ts +0 -650
  110. package/src-next/session/__tests__/graph.test.ts +0 -270
  111. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  112. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  113. package/src-next/session/__tests__/ledger.test.ts +0 -744
  114. package/src-next/session/__tests__/next.test.ts +0 -368
  115. package/src-next/session/__tests__/preflight.test.ts +0 -491
  116. package/src-next/session/__tests__/run.test.ts +0 -1014
  117. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  118. package/src-next/session/__tests__/wave.test.ts +0 -469
  119. package/src-next/session/faces.ts +0 -110
  120. package/src-next/session/graph.ts +0 -411
  121. package/src-next/session/handoff-schema.ts +0 -373
  122. package/src-next/session/ledger.ts +0 -1004
  123. package/src-next/session/next.ts +0 -192
  124. package/src-next/session/preflight.ts +0 -240
  125. package/src-next/session/run.ts +0 -606
  126. package/src-next/session/state.ts +0 -30
  127. package/src-next/session/wave.ts +0 -139
@@ -0,0 +1,241 @@
1
+ // packages/cdd-engine/src-next/face/declare.ts
2
+ // §2.4 — the CLI declaration single surface: the argv channel table, the seven-command
3
+ // declarations, every CLI face type and the conditional-required group table cohere
4
+ // in ONE file (the user ruling 2026-10-11: the declaration was scattered across
5
+ // runtime/registry/argv → one surface). The migration converges:
6
+ //
7
+ // · ARGV_CHANNEL / ChannelValueType / ChannelArgRow — from infra/runtime.ts (the
8
+ // engine-config face keeps only the version + the handoff-namespace facts).
9
+ // · CliVerb / CliLeafName / CliValueOverride / CliArgSpec / CliLeafSpec /
10
+ // CliCommandSpec / CLI_COMMANDS — from face/registry.ts (the registry file is
11
+ // deleted; the rows drop the `usage` field — the usage semantics merge into the
12
+ // projection's .description(), and the six-line usage corpus retires here).
13
+ // · REQUIRED_GROUPS — from face/validate.ts (the preAction data face; the
14
+ // retired validator component retires — the value-domain semantics move to the
15
+ // builder's parseArg method family).
16
+ // · SCHEMA_TYPE_KEYS — from face/argv.ts (the schema <type> vocabulary; consumed
17
+ // by the builder's #parseTypeKey — the argv.ts parse channel died at T6).
18
+ //
19
+ // Module-level exports are types / declared constant data — zero behavior-carrying
20
+ // bare functions (the plan's zero-bare-function discipline); the projection
21
+ // algorithm lives in the single CommandTreeBuilder class (face/projection.ts).
22
+ import { InvalidArgumentError } from "commander";
23
+ import { ENGINE_DOC_ROOTS } from "../infra/doc-roots.js";
24
+ /** The argv channel table — the CLI flag/type/enum single source (the engine-config
25
+ * argv channel verbatim: flag spellings, value types and enum domains ride these
26
+ * rows, and the command declarations + the channel audit read them from here). The
27
+ * `help` rows are the flag-level descriptions of the commander Options face (one
28
+ * text per key, shared by every command that declares it). */
29
+ export const ARGV_CHANNEL = {
30
+ plan: { flag: "--plan", type: "path", help: "the CDD plan document path" },
31
+ spec: { flag: "--spec", type: "path", help: "the design-spec document path" },
32
+ reviews: {
33
+ flag: "--reviews",
34
+ type: "path",
35
+ help: "the source review handoff JSON path",
36
+ },
37
+ tasks: {
38
+ flag: "--tasks",
39
+ type: "int-list",
40
+ help: "the task ids of the wave group (comma-separated)",
41
+ },
42
+ type: {
43
+ flag: "--type",
44
+ type: "enum",
45
+ values: ["wave", "branch", "spec", "plan"],
46
+ help: "the target face of the round",
47
+ },
48
+ base: { flag: "--base", type: "string", help: "the base artifact branch name" },
49
+ round: { flag: "--round", type: "int", help: "the review/fix round number" },
50
+ source: {
51
+ flag: "--source",
52
+ type: "enum",
53
+ values: ["plan-field", "branch-upstream", "conversation-context", "user-confirmed"],
54
+ help: "the base artifact's source channel",
55
+ },
56
+ force: { flag: "--force", type: "bool", help: "override the existing base artifact" },
57
+ dryRun: {
58
+ flag: "--dry-run",
59
+ type: "bool",
60
+ scope: "program",
61
+ help: "preview the next dispatch step and its expected artifacts — zero repo writes, no round consumed (implement/review/fix only)",
62
+ },
63
+ help: {
64
+ flag: "--help",
65
+ alias: "-h",
66
+ type: "bool",
67
+ scope: "program",
68
+ help: "show this help",
69
+ },
70
+ output: {
71
+ flag: "--output",
72
+ type: "enum",
73
+ values: ["json", "skeleton"],
74
+ help: "the schema render face — json (the derived declaration, default) or skeleton (the scaffold written into <target>)",
75
+ },
76
+ };
77
+ /** The value-domain shapes — the parsed raw's check + normalization per shaped
78
+ * channel type: the parseArg family's single executor source (§4.1). Each rule
79
+ * validates the raw against the row's declared domain and returns the normalized
80
+ * value; a non-conforming raw throws commander.InvalidArgumentError with the
81
+ * pinned error bytes (the value-domain error messages are a pinned surface —
82
+ * zero byte drift across the retired method family). The enum rule reads the
83
+ * row's declared `values`; the int-list normalization rewrites the consumed
84
+ * shape, never the run face's own normalization. Data rows, never bare
85
+ * functions — one executor reads them (face/projection.ts #parseArgOf). */
86
+ export const VALUE_SHAPES = {
87
+ enum: {
88
+ parse(raw, row) {
89
+ if (!(row.values ?? []).includes(raw)) {
90
+ throw new InvalidArgumentError(`must be one of ${(row.values ?? []).join(" | ")}`);
91
+ }
92
+ return raw;
93
+ },
94
+ },
95
+ "int-list": {
96
+ parse(raw) {
97
+ const parts = raw.split(",").map((part) => part.trim());
98
+ const invalid = parts.find((part) => !/^\d+$/.test(part));
99
+ if (invalid !== undefined) {
100
+ throw new InvalidArgumentError(`--tasks <n|n,n,…> — must be comma-separated integers: ${invalid}`);
101
+ }
102
+ return [...new Set(parts.map(Number))].sort((a, b) => a - b).join(",");
103
+ },
104
+ },
105
+ int: {
106
+ parse(raw) {
107
+ if (!/^\d+$/.test(raw)) {
108
+ throw new InvalidArgumentError("must be an integer");
109
+ }
110
+ return raw;
111
+ },
112
+ },
113
+ };
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. */
117
+ export const CLI_COMMANDS = [
118
+ {
119
+ name: "implement",
120
+ description: "run the task implement phase",
121
+ example: `cdd implement --tasks 1,2 --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
122
+ keys: [
123
+ { key: "tasks", required: true },
124
+ { key: "plan", required: true },
125
+ ],
126
+ },
127
+ {
128
+ 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`,
131
+ keys: [
132
+ { key: "type", required: true },
133
+ { key: "tasks" },
134
+ { key: "plan" },
135
+ { key: "spec" },
136
+ { key: "round" },
137
+ ],
138
+ },
139
+ {
140
+ name: "fix",
141
+ description: "fix review findings — task | branch | spec | plan",
142
+ example: "cdd fix --type wave --tasks 1 --reviews tasks-1-review-1.json",
143
+ keys: [
144
+ { key: "type", required: true },
145
+ { key: "tasks" },
146
+ { key: "reviews" },
147
+ { key: "spec" },
148
+ { key: "plan" },
149
+ ],
150
+ },
151
+ {
152
+ name: "base",
153
+ description: "read/write base.json (single CDD --plan target)",
154
+ example: `cdd base set --plan ${ENGINE_DOC_ROOTS.plans}/p3.md --base develop --source plan-field`,
155
+ keys: [],
156
+ leaves: [
157
+ {
158
+ name: "set",
159
+ description: "write the base artifact",
160
+ keys: [
161
+ { key: "plan", required: true },
162
+ { key: "base", required: true, valueType: "branch" },
163
+ { key: "source", required: true },
164
+ { key: "force" },
165
+ ],
166
+ },
167
+ {
168
+ name: "get",
169
+ description: "read the base artifact",
170
+ keys: [{ key: "plan", required: true }],
171
+ },
172
+ ],
173
+ },
174
+ {
175
+ name: "schema",
176
+ description: "read canonical doc-structure schemas (discovery, zero enforcement)",
177
+ example: "cdd schema get phase-spec",
178
+ keys: [{ key: "plan" }],
179
+ leaves: [
180
+ {
181
+ name: "get",
182
+ description: "print the derived doc-structure schema for <type> (the --output json face, default) or render the derived doc skeleton into <target> (the --output skeleton face)",
183
+ keys: [{ key: "plan" }, { key: "output" }],
184
+ positionals: [{ key: "type", required: true }, { key: "target" }],
185
+ },
186
+ ],
187
+ },
188
+ {
189
+ name: "issue",
190
+ description: "aggregate issue-body rendering (cdd issue render, zero enforcement)",
191
+ example: "cdd issue render < findings.json",
192
+ keys: [],
193
+ leaves: [
194
+ {
195
+ name: "render",
196
+ description: "render the aggregate issue body (stdin findings JSON → stdout)",
197
+ keys: [],
198
+ },
199
+ ],
200
+ },
201
+ {
202
+ name: "board",
203
+ description: "render the slug progress board (overall/spec/plan/wave/branch)",
204
+ example: "cdd board 2026-10-10-engine-doc-tooling-p7",
205
+ keys: [],
206
+ positionals: [{ key: "slug", required: true }],
207
+ },
208
+ ];
209
+ /** The schema `<type>` vocabulary — the get leaf's ONE table (spec §5.3): the
210
+ * primary DocKey spellings (overall-spec | plan | phase-spec | single-spec) plus
211
+ * the legacy `phaseSpec` alias row normalized to the kebab key. One normalizing
212
+ * vocabulary, never a second hand-written list — the builder's #parseTypeKey
213
+ * validates through it. */
214
+ export const SCHEMA_TYPE_KEYS = {
215
+ "overall-spec": "overall-spec",
216
+ plan: "plan",
217
+ "phase-spec": "phase-spec",
218
+ "single-spec": "single-spec",
219
+ phaseSpec: "phase-spec",
220
+ };
221
+ /** The conditional required group per work verb + target type — the preAction hook's
222
+ * data face (spec §4.2): review `{plan}` / `{spec}` / `{plan}` · fix `{plan}` /
223
+ * `{spec}` / `{findings, plan}` — every branch face carries the `--plan` workspace
224
+ * identity (the branch line holds no commit ref: the review judges the live tree,
225
+ * the scope anchor BASE_BRANCH is engine-injected at dispatch). Keyed by declared
226
+ * flag spelling; non-exclusive — a round declaring both `--plan` and `--spec`
227
+ * stays accepted (no mutual-exclusion rejection). */
228
+ export const REQUIRED_GROUPS = {
229
+ review: {
230
+ wave: ["--plan"],
231
+ spec: ["--spec"],
232
+ plan: ["--plan"],
233
+ branch: ["--plan"],
234
+ },
235
+ fix: {
236
+ wave: ["--plan"],
237
+ spec: ["--spec"],
238
+ plan: ["--plan"],
239
+ branch: ["--reviews", "--plan"],
240
+ },
241
+ };
@@ -0,0 +1,158 @@
1
+ // packages/cdd-engine/src-next/face/gate.ts
2
+ // T8 — the split contract's gate face (§6.2: face/gate.ts — the target/line gate
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).
10
+ import { readFileSync } from "node:fs";
11
+ import { FrontMatterExtractor } from "../contract/frontmatter.js";
12
+ import { BriefRenderer } from "../render/brief.js";
13
+ import { RoundNaming } from "../session/round-naming.js";
14
+ /**
15
+ * CliGate — the target/line gate family (the split contract's gate face): the
16
+ * readiness judgments the work commands consult before dispatching a round. The
17
+ * instance's methods take the per-invocation scene; the gate holds only the stable
18
+ * collaborators it needs (the brief renderer). The verdict-bearing methods return
19
+ * their ruling + message — the root renders, never re-judges.
20
+ */
21
+ export class CliGate {
22
+ #brief;
23
+ constructor(opts = {}) {
24
+ this.#brief = opts.brief ?? new BriefRenderer();
25
+ }
26
+ /** The single-target line's current open phase plus the doc-line verdict the gate
27
+ * judged — the {phase, verdict} pair IS the gate's ruling: the revision-aware
28
+ * BLOCK renders only the "same" verdict the gate returned, the pending-fix note
29
+ * only the derived pending face, never a recomputed one. The task face holds no
30
+ * separate gate here: the WaveGate's wrong-phase verdict (the pre-flight) IS the
31
+ * 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). */
45
+ 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 };
65
+ }
66
+ }
67
+ const open = this.#linePhase(scene);
68
+ return { phase: open, verdict: null, reviewed: null };
69
+ }
70
+ /** The doc line's revision-aware BLOCK message (T7/T8) — the unchanged-approved
71
+ * face: "{plan|spec} already reviewed at vX.Y (doc-hash …) — target revision
72
+ * unchanged; amend body/version to open a new review". Renders ONLY on the
73
+ * gate's "same" verdict — the approved identity the gate judged, whose reviewed
74
+ * ref the message names: the block consumes the verdict's identity, never a
75
+ * second ledger lookup (the face's judgment read points converge to the
76
+ * method family). Null off that face or with no identity ("target revision
77
+ * unchanged" is a present fact only there). */
78
+ docLineBlock(scene, reviewed) {
79
+ if (reviewed === null || (scene.target?.kind !== "plan" && scene.target?.kind !== "spec"))
80
+ return null;
81
+ const version = this.#docVersionOf(this.#docContent(scene.target.doc));
82
+ return `${scene.type} already reviewed at ${version ?? "the current version"} (doc-hash ${reviewed.doc_hash.slice(0, 12)}…) — target revision unchanged; amend body/version to open a new review`;
83
+ }
84
+ /** The doc line's derived pending-fix note (T8) — the unchanged + non-APPROVED
85
+ * face: "the pending fix applies to the unchanged doc (doc-hash …) — run cdd
86
+ * fix first". Renders ONLY for the gate's "pending-fix" verdict — the derived
87
+ * fix-awaited face (a same-doc re-review stays refused until its fix lands,
88
+ * Review Convergence anti-spin); the message names the reviewed identity the
89
+ * gate judged. */
90
+ pendingFixBlock(scene, reviewed) {
91
+ if (reviewed === null || (scene.target?.kind !== "plan" && scene.target?.kind !== "spec"))
92
+ return null;
93
+ return `the pending fix applies to the unchanged doc (doc-hash ${reviewed.doc_hash.slice(0, 12)}…) — run cdd fix first`;
94
+ }
95
+ /** The requested group ints — the normalized tasks value split. */
96
+ tasksOf(parsed) {
97
+ return (parsed.args.tasks ?? "").split(",").map((part) => Number(part));
98
+ }
99
+ /** Render the task group brief into the workspace (the implement dispatch's input)
100
+ * — the brief mirrors the current plan (its task sections + the `## Constraints`
101
+ * section, re-extracted at every dispatch). */
102
+ renderBrief(scene, parsed) {
103
+ const tasks = this.tasksOf(parsed);
104
+ const content = this.#brief.render(scene.planText, tasks);
105
+ // The real run's workspace is built by the single write point (`Cli#runWork`'s
106
+ // ensure, P11 · §4.2) BEFORE this render; the write still rides the workspace's
107
+ // own text-write face (the `writeJson` mkdir-before-write pattern), never a
108
+ // second explicit `ensure()` — no bare `writeFileSync` into a possibly absent dir.
109
+ const name = new RoundNaming(scene.workspace).briefName(parsed.args.tasks ?? "");
110
+ return scene.workspace.writeText(name, content);
111
+ }
112
+ /** The single-target line's current open phase — fix-awaits / re-review / closure
113
+ * read from the ledger's SINGLE line-phase judge (`Ledger#linePhase`, D40 — the
114
+ * retired gate twin): the gate and the lifecycle's frame frontier now read ONE
115
+ * source, never a second walk. */
116
+ #linePhase(scene) {
117
+ const key = this.#lineKey(scene);
118
+ if (key === null)
119
+ return null;
120
+ return scene.ledger.linePhase(key, scene.face.type);
121
+ }
122
+ /** 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
125
+ * string must not fork the same line into two ledger rows, resetting its round),
126
+ * the lifecycle's own key derivation (run.ts #lineKey). */
127
+ #lineKey(scene) {
128
+ if (scene.target?.kind === "branch")
129
+ return "branch";
130
+ if (scene.target?.kind === "plan" || scene.target?.kind === "spec")
131
+ return scene.face.type;
132
+ return null;
133
+ }
134
+ /** The doc's live content — readable doc else null. This helper backs the face's
135
+ * one remaining doc read site, the revision-aware BLOCK's version token — a read
136
+ * fired only when the BLOCK message actually renders (the version is raw doc
137
+ * grammar — zero parse dependence: the revision hash is a raw-content digest).
138
+ * The gate's own doc read lives in the ledger (Ledger#docLineVerdict — one read
139
+ * per reviewGate, the shared comparison). A BLOCK render is a run-failure prose
140
+ * channel — never a usage face — so the read is guarded here (null on unreadable),
141
+ * not routed through the artifacts readText's usage error. */
142
+ #docContent(doc) {
143
+ try {
144
+ return readFileSync(doc, "utf8");
145
+ }
146
+ catch {
147
+ return null;
148
+ }
149
+ }
150
+ /** The doc's `v<major>.<minor>` version token — the front-matter `version:`
151
+ * scalar (the T6 read point: the header version facts ride the typed head
152
+ * record — the fence split + `yaml` engine, never a line scan). */
153
+ #docVersionOf(content) {
154
+ if (content === null)
155
+ return null;
156
+ return FrontMatterExtractor.split(content).head.version;
157
+ }
158
+ }
@@ -0,0 +1,66 @@
1
+ // packages/cdd-engine/src-next/face/graph-view.ts
2
+ // The wave-board display (the board face). The engine
3
+ // OWNS the layout: the derived waves (TaskGraph.batches) ARE the display's rows —
4
+ // one wave band per row, the band's tasks inline, the incoming source bands noted.
5
+ // Deterministic, always in wave order, zero third-party layout — the engine renders
6
+ // the node placement and the labels itself, so the board honors the wave order and
7
+ // survives the full plan scale.
8
+ //
9
+ // Two consumers share the report: the pre-flight refusal's blocked-dispatch hint and
10
+ // the board.
11
+ //
12
+ // Module-level exports are the class + the shared progress-marker vocabulary (the
13
+ // glyph set + the legend tails) — zero behavior-carrying bare functions.
14
+ /** The progress-marker glyph set — the ONE display vocabulary both the wave board
15
+ * (per-task markers) and the slug board (wave-level markers) render: ✔ done ·
16
+ * ▶ current · ○ pending. Single-sourced here so the two faces share one home,
17
+ * never a second declaration kept aligned by convention. */
18
+ export const PROGRESS_MARKERS = { done: "✔", current: "▶", pending: "○" };
19
+ /** The progress-marker legend tail lines — one per face scope, the scope word
20
+ * (`current` vs `current wave`) the ONE deliberate difference between the two
21
+ * boards (the graph's tasks sit inside a wave; the slug board's wave-less scopes
22
+ * carry no wave). The glyphs ride PROGRESS_MARKERS so the vocabulary has exactly
23
+ * one home. */
24
+ export const PROGRESS_LEGEND = {
25
+ board: `progress: ${PROGRESS_MARKERS.done} done · ${PROGRESS_MARKERS.current} current · ${PROGRESS_MARKERS.pending} pending`,
26
+ graph: `progress: ${PROGRESS_MARKERS.done} done · ${PROGRESS_MARKERS.current} current wave · ${PROGRESS_MARKERS.pending} pending`,
27
+ };
28
+ /** GraphView — the wave-board display: one deterministic row per derived wave, the
29
+ * band's tasks inline with progress markers, the incoming source bands noted.
30
+ * v1.20 — the in-wave marker mix: the done set rides `closedWaves()` (the report's
31
+ * done projection, never "any ledger row"), and a current-wave task that is already
32
+ * done shows ✔, never a swallowed whole-row ▶. */
33
+ export class GraphView {
34
+ /** render(report, title) → the wave-board + the legend (the plan read and the
35
+ * pre-flight display call the same face). */
36
+ render(report, title) {
37
+ const done = new Set(report.done);
38
+ const currentIndex = report.waves.findIndex((wave) => wave.some((id) => !done.has(id)));
39
+ const markers = new Map();
40
+ for (const [index, wave] of report.waves.entries()) {
41
+ for (const id of wave) {
42
+ // The per-task marker, done first: a completed task shows ✔ even inside the
43
+ // current wave (the mix), a not-done current-wave task shows ▶, the rest ○.
44
+ markers.set(id, done.has(id)
45
+ ? PROGRESS_MARKERS.done
46
+ : index === currentIndex
47
+ ? PROGRESS_MARKERS.current
48
+ : PROGRESS_MARKERS.pending);
49
+ }
50
+ }
51
+ const rows = report.waves
52
+ .map((wave, index) => {
53
+ const tasks = wave
54
+ .map((id) => `T${id}${markers.get(id) ?? PROGRESS_MARKERS.pending}`)
55
+ .join(" · ");
56
+ // find #6 (user 2026-10-09: "W1 fits the agent mindset better"): the board label = the
57
+ // derived wave index + 1 (W1 · W2 · …) with no zero-padding — the plan's
58
+ // execution-order labels reference this derived label verbatim (display
59
+ // layer only; the wave derivation itself is unchanged).
60
+ const line = ` W${index + 1} ${tasks}`;
61
+ return index === currentIndex ? `${line} ← in-flight` : line;
62
+ })
63
+ .join("\n");
64
+ return `${title}\n\nwave board:\n${rows}\n\n${PROGRESS_LEGEND.graph}`;
65
+ }
66
+ }