@oscaner-skills/cdd-engine 3.0.0 → 3.1.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 (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +149 -0
  15. package/dist/face/cli.js +893 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +702 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +504 -0
  25. package/dist/face/words.js +258 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +453 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. package/src-next/session/wave.ts +0 -139
@@ -1,323 +0,0 @@
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
-
23
- import { InvalidArgumentError } from "commander";
24
-
25
- import type { DocKey } from "../contract/project.ts";
26
- import { ENGINE_DOC_ROOTS } from "../infra/doc-roots.ts";
27
-
28
- /** The component-value types of the argv channel (the CLI parse validates by these). */
29
- export type ChannelValueType = "string" | "path" | "int-list" | "enum" | "int" | "bool";
30
-
31
- /** One argv-channel row — the flag/type/enum declaration of one CLI key. */
32
- export interface ChannelArgRow {
33
- /** The `--flag` spelling. */
34
- flag: string;
35
- /** The complement alias (help's `-h`), when the channel declares one. */
36
- alias?: string;
37
- /** The component-value type the CLI parse validates by. */
38
- type: ChannelValueType;
39
- /** The enum domain, when the type is enum. */
40
- values?: readonly string[];
41
- /** The program-scope marker (dry-run/help — accepted at any position). */
42
- scope?: "program";
43
- /** The flag-level help line — the commander option description (one global key
44
- * text, single-sourced at the channel). */
45
- help?: string;
46
- }
47
-
48
- /** The argv channel table — the CLI flag/type/enum single source (the engine-config
49
- * argv channel verbatim: flag spellings, value types and enum domains ride these
50
- * rows, and the command declarations + the channel audit read them from here). The
51
- * `help` rows are the flag-level descriptions of the commander Options face (one
52
- * text per key, shared by every command that declares it). */
53
- export const ARGV_CHANNEL = {
54
- plan: { flag: "--plan", type: "path", help: "the CDD plan document path" },
55
- spec: { flag: "--spec", type: "path", help: "the design-spec document path" },
56
- reviews: {
57
- flag: "--reviews",
58
- type: "path",
59
- help: "the source review handoff JSON path",
60
- },
61
- tasks: {
62
- flag: "--tasks",
63
- type: "int-list",
64
- help: "the task ids of the wave group (comma-separated)",
65
- },
66
- type: {
67
- flag: "--type",
68
- type: "enum",
69
- values: ["wave", "branch", "spec", "plan"],
70
- help: "the target face of the round",
71
- },
72
- base: { flag: "--base", type: "string", help: "the base artifact branch name" },
73
- round: { flag: "--round", type: "int", help: "the review/fix round number" },
74
- source: {
75
- flag: "--source",
76
- type: "enum",
77
- values: ["plan-field", "branch-upstream", "conversation-context", "user-confirmed"],
78
- help: "the base artifact's source channel",
79
- },
80
- force: { flag: "--force", type: "bool", help: "override the existing base artifact" },
81
- dryRun: {
82
- flag: "--dry-run",
83
- type: "bool",
84
- scope: "program",
85
- help: "preview the next dispatch step and its expected artifacts — zero repo writes, no round consumed (implement/review/fix only)",
86
- },
87
- help: {
88
- flag: "--help",
89
- alias: "-h",
90
- type: "bool",
91
- scope: "program",
92
- help: "show this help",
93
- },
94
- output: {
95
- flag: "--output",
96
- type: "enum",
97
- values: ["json", "skeleton"],
98
- help: "the schema render face — json (the derived declaration, default) or skeleton (the scaffold written into <target>)",
99
- },
100
- } as const satisfies Readonly<Record<string, ChannelArgRow>>;
101
-
102
- /** The shaped channel subset — the value-domain-validated channel types
103
- * (string/path/bool carry no parser — the unshaped faces register absent). */
104
- export type ShapedChannelValueType = "enum" | "int-list" | "int";
105
-
106
- /** The value-domain shapes — the parsed raw's check + normalization per shaped
107
- * channel type: the parseArg family's single executor source (§4.1). Each rule
108
- * validates the raw against the row's declared domain and returns the normalized
109
- * value; a non-conforming raw throws commander.InvalidArgumentError with the
110
- * pinned error bytes (the value-domain error messages are a pinned surface —
111
- * zero byte drift across the retired method family). The enum rule reads the
112
- * row's declared `values`; the int-list normalization rewrites the consumed
113
- * shape, never the run face's own normalization. Data rows, never bare
114
- * functions — one executor reads them (face/projection.ts #parseArgOf). */
115
- export const VALUE_SHAPES: Readonly<
116
- Record<ShapedChannelValueType, { parse(raw: string, row: ChannelArgRow): string }>
117
- > = {
118
- enum: {
119
- parse(raw, row) {
120
- if (!(row.values ?? []).includes(raw)) {
121
- throw new InvalidArgumentError(`must be one of ${(row.values ?? []).join(" | ")}`);
122
- }
123
- return raw;
124
- },
125
- },
126
- "int-list": {
127
- parse(raw) {
128
- const parts = raw.split(",").map((part) => part.trim());
129
- const invalid = parts.find((part) => !/^\d+$/.test(part));
130
- if (invalid !== undefined) {
131
- throw new InvalidArgumentError(
132
- `--tasks <n|n,n,…> — must be comma-separated integers: ${invalid}`,
133
- );
134
- }
135
- return [...new Set(parts.map(Number))].sort((a, b) => a - b).join(",");
136
- },
137
- },
138
- int: {
139
- parse(raw) {
140
- if (!/^\d+$/.test(raw)) {
141
- throw new InvalidArgumentError("must be an integer");
142
- }
143
- return raw;
144
- },
145
- },
146
- };
147
-
148
- /** The seven subcommand words — the CLI command face (implement · review · fix ·
149
- * schema · issue · base · board). */
150
- export type CliVerb = "implement" | "review" | "fix" | "schema" | "issue" | "base" | "board";
151
-
152
- /** The nested leaf words — the sub-command surfaces of the pure commands. */
153
- export type CliLeafName = "get" | "set" | "render";
154
-
155
- /** A per-command value-type override — a declared key whose value shape differs
156
- * from the channel's global typing for that key (base set's `--base` carries a
157
- * branch name — the branch-domain display token/help). */
158
- export type CliValueOverride = "branch";
159
-
160
- /** One declared arg of a command — the key + how strictly the run requires it. */
161
- export interface CliArgSpec {
162
- /** The canonical engine-config argv-channel key. */
163
- key: string;
164
- /** Whether the run requires the value (enforced at parse — .requiredOption() /
165
- * a required .argument()). */
166
- required?: boolean;
167
- /** The value-type override (only where the command's use differs from the channel). */
168
- valueType?: CliValueOverride;
169
- }
170
-
171
- /** One nested leaf command (base set|get · schema get · issue render). */
172
- export interface CliLeafSpec {
173
- name: CliLeafName;
174
- description: string;
175
- keys: readonly CliArgSpec[];
176
- positionals?: readonly CliArgSpec[];
177
- }
178
-
179
- /** One subcommand declaration — the command face's data row. */
180
- export interface CliCommandSpec {
181
- name: CliVerb;
182
- description: string;
183
- keys: readonly CliArgSpec[];
184
- positionals?: readonly CliArgSpec[];
185
- leaves?: readonly CliLeafSpec[];
186
- /** One minimal runnable example (the help face's Examples section — projected by
187
- * the builder's .addHelpText(); the P1 example sentences). */
188
- example?: string;
189
- }
190
-
191
- /** The seven subcommand declarations — implement, review, fix (the lifecycle work
192
- * commands) plus the pure base / schema / issue artifact commands and the board
193
- * observability command. */
194
- export const CLI_COMMANDS: readonly CliCommandSpec[] = [
195
- {
196
- name: "implement",
197
- description: "run the task implement phase",
198
- example: `cdd implement --tasks 1,2 --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
199
- keys: [
200
- { key: "tasks", required: true },
201
- { key: "plan", required: true },
202
- ],
203
- },
204
- {
205
- name: "review",
206
- description: "run a review — task | branch | spec | plan",
207
- example: `cdd review --type spec --spec ${ENGINE_DOC_ROOTS.specs}/p3-design.md`,
208
- keys: [
209
- { key: "type", required: true },
210
- { key: "tasks" },
211
- { key: "plan" },
212
- { key: "spec" },
213
- { key: "round" },
214
- ],
215
- },
216
- {
217
- name: "fix",
218
- description: "fix review findings — task | branch | spec | plan",
219
- example: "cdd fix --type wave --tasks 1 --reviews tasks-1-review-1.json",
220
- keys: [
221
- { key: "type", required: true },
222
- { key: "tasks" },
223
- { key: "reviews" },
224
- { key: "spec" },
225
- { key: "plan" },
226
- ],
227
- },
228
- {
229
- name: "base",
230
- description: "read/write base.json (single CDD --plan target)",
231
- example: `cdd base set --plan ${ENGINE_DOC_ROOTS.plans}/p3.md --base develop --source plan-field`,
232
- keys: [],
233
- leaves: [
234
- {
235
- name: "set",
236
- description: "write the base artifact",
237
- keys: [
238
- { key: "plan", required: true },
239
- { key: "base", required: true, valueType: "branch" },
240
- { key: "source", required: true },
241
- { key: "force" },
242
- ],
243
- },
244
- {
245
- name: "get",
246
- description: "read the base artifact",
247
- keys: [{ key: "plan", required: true }],
248
- },
249
- ],
250
- },
251
- {
252
- name: "schema",
253
- description: "read canonical doc-structure schemas (discovery, zero enforcement)",
254
- example: "cdd schema get phase-spec",
255
- keys: [{ key: "plan" }],
256
- leaves: [
257
- {
258
- name: "get",
259
- description:
260
- "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)",
261
- keys: [{ key: "plan" }, { key: "output" }],
262
- positionals: [{ key: "type", required: true }, { key: "target" }],
263
- },
264
- ],
265
- },
266
- {
267
- name: "issue",
268
- description: "aggregate issue-body rendering (cdd issue render, zero enforcement)",
269
- example: "cdd issue render < findings.json",
270
- keys: [],
271
- leaves: [
272
- {
273
- name: "render",
274
- description: "render the aggregate issue body (stdin findings JSON → stdout)",
275
- keys: [],
276
- },
277
- ],
278
- },
279
- {
280
- name: "board",
281
- description: "render the slug progress board (overall/spec/plan/wave/branch)",
282
- example: "cdd board 2026-10-10-engine-doc-tooling-p7",
283
- keys: [],
284
- positionals: [{ key: "slug", required: true }],
285
- },
286
- ];
287
-
288
- /** The schema `<type>` vocabulary — the get leaf's ONE table (spec §5.3): the
289
- * primary DocKey spellings (overall-spec | plan | phase-spec | single-spec) plus
290
- * the legacy `phaseSpec` alias row normalized to the kebab key. One normalizing
291
- * vocabulary, never a second hand-written list — the builder's #parseTypeKey
292
- * validates through it. */
293
- export const SCHEMA_TYPE_KEYS: Readonly<Record<string, DocKey>> = {
294
- "overall-spec": "overall-spec",
295
- plan: "plan",
296
- "phase-spec": "phase-spec",
297
- "single-spec": "single-spec",
298
- phaseSpec: "phase-spec",
299
- };
300
-
301
- /** The conditional required group per work verb + target type — the preAction hook's
302
- * data face (spec §4.2): review `{plan}` / `{spec}` / `{plan}` · fix `{plan}` /
303
- * `{spec}` / `{findings, plan}` — every branch face carries the `--plan` workspace
304
- * identity (the branch line holds no commit ref: the review judges the live tree,
305
- * the scope anchor BASE_BRANCH is engine-injected at dispatch). Keyed by declared
306
- * flag spelling; non-exclusive — a round declaring both `--plan` and `--spec`
307
- * stays accepted (no mutual-exclusion rejection). */
308
- export const REQUIRED_GROUPS: Readonly<
309
- Record<"review" | "fix", Readonly<Record<string, readonly string[]>>>
310
- > = {
311
- review: {
312
- wave: ["--plan"],
313
- spec: ["--spec"],
314
- plan: ["--plan"],
315
- branch: ["--plan"],
316
- },
317
- fix: {
318
- wave: ["--plan"],
319
- spec: ["--spec"],
320
- plan: ["--plan"],
321
- branch: ["--reviews", "--plan"],
322
- },
323
- };
@@ -1,171 +0,0 @@
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
-
11
- import { readFileSync } from "node:fs";
12
- import { FrontMatterExtractor } from "../contract/frontmatter.ts";
13
- import { BriefRenderer } from "../render/brief.ts";
14
- import type { DispatchPhase } from "../session/faces.ts";
15
- import type { DocRevisionRef } from "../session/ledger.ts";
16
- import { RoundNaming } from "../session/round-naming.ts";
17
- import type { RunInput, WorkScene } from "./cli.ts";
18
-
19
- /**
20
- * CliGate — the target/line gate family (the split contract's gate face): the
21
- * readiness judgments the work commands consult before dispatching a round. The
22
- * instance's methods take the per-invocation scene; the gate holds only the stable
23
- * collaborators it needs (the brief renderer). The verdict-bearing methods return
24
- * their ruling + message — the root renders, never re-judges.
25
- */
26
- export class CliGate {
27
- readonly #brief: BriefRenderer;
28
-
29
- constructor(opts: { brief?: BriefRenderer } = {}) {
30
- this.#brief = opts.brief ?? new BriefRenderer();
31
- }
32
-
33
- /** The single-target line's current open phase plus the doc-line verdict the gate
34
- * judged — the {phase, verdict} pair IS the gate's ruling: the revision-aware
35
- * BLOCK renders only the "same" verdict the gate returned, the pending-fix note
36
- * only the derived pending face, never a recomputed one. The task face holds no
37
- * separate gate here: the WaveGate's wrong-phase verdict (the pre-flight) IS the
38
- * task-face phase authority — the wave gate is the single phase authority. A
39
- * doc line's gate is the reviewGate method family (T8 · §3.5 · judgment order =
40
- * doc revision FIRST, shared by the lifecycle's frame phase so an opened gate
41
- * dispatches): a moved doc opens the review lead whatever the round/route state
42
- * says (fix after · backfill after · user-decision after are the SAME case — the
43
- * stuck "next round is fix after an aborted fix" never freezes a revised doc),
44
- * an unchanged doc yields the gate's "same" verdict — the pending fix DERIVED
45
- * from the latest review's non-APPROVED conclusion opens only the fix phase,
46
- * while the no-pending face falls back to the legacy rounds/routes judgment: a
47
- * completed-fix line reopens the review lead through its fix round's C5-1 route
48
- * (the lifecycle's own fall-through — an open gate and a dispatchable frame
49
- * agree), a truly closed line keeps the revision-aware BLOCK. An unbound line
50
- * (no identity on record / an unreadable doc) keeps the legacy round/route
51
- * judgment + the generic closed message (only present facts land). */
52
- lineGate(scene: WorkScene): {
53
- phase: DispatchPhase | null;
54
- verdict: "same" | "pending-fix" | null;
55
- reviewed: DocRevisionRef | null;
56
- } {
57
- if (scene.target?.kind === "plan" || scene.target?.kind === "spec") {
58
- const key = this.#lineKey(scene);
59
- if (key === null) return { phase: null, verdict: null, reviewed: null };
60
- const verdict = scene.ledger.reviewGate(key, scene.target.doc, scene.face.type);
61
- if (verdict.kind === "open") {
62
- return { phase: scene.face.product.reviewLead, verdict: null, reviewed: null };
63
- }
64
- if (verdict.kind === "same") {
65
- if (verdict.pending) {
66
- return { phase: "fix", verdict: "pending-fix", reviewed: verdict.reviewed };
67
- }
68
- // same + no pending fix — the legacy rounds/routes judgment (the lifecycle's
69
- // own fall-through): a completed-fix line reopens the review lead through its
70
- // fix round's C5-1 route; a truly closed line keeps the revision-aware BLOCK.
71
- const open = this.#linePhase(scene);
72
- return open !== null
73
- ? { phase: open, verdict: null, reviewed: null }
74
- : { phase: null, verdict: "same", reviewed: verdict.reviewed };
75
- }
76
- }
77
- const open = this.#linePhase(scene);
78
- return { phase: open, verdict: null, reviewed: null };
79
- }
80
-
81
- /** The doc line's revision-aware BLOCK message (T7/T8) — the unchanged-approved
82
- * face: "{plan|spec} already reviewed at vX.Y (doc-hash …) — target revision
83
- * unchanged; amend body/version to open a new review". Renders ONLY on the
84
- * gate's "same" verdict — the approved identity the gate judged, whose reviewed
85
- * ref the message names: the block consumes the verdict's identity, never a
86
- * second ledger lookup (the face's judgment read points converge to the
87
- * method family). Null off that face or with no identity ("target revision
88
- * unchanged" is a present fact only there). */
89
- docLineBlock(scene: WorkScene, reviewed: DocRevisionRef | null): string | null {
90
- if (reviewed === null || (scene.target?.kind !== "plan" && scene.target?.kind !== "spec"))
91
- return null;
92
- const version = this.#docVersionOf(this.#docContent(scene.target.doc));
93
- return `${scene.type} already reviewed at ${version ?? "the current version"} (doc-hash ${reviewed.doc_hash.slice(0, 12)}…) — target revision unchanged; amend body/version to open a new review`;
94
- }
95
-
96
- /** The doc line's derived pending-fix note (T8) — the unchanged + non-APPROVED
97
- * face: "the pending fix applies to the unchanged doc (doc-hash …) — run cdd
98
- * fix first". Renders ONLY for the gate's "pending-fix" verdict — the derived
99
- * fix-awaited face (a same-doc re-review stays refused until its fix lands,
100
- * Review Convergence anti-spin); the message names the reviewed identity the
101
- * gate judged. */
102
- pendingFixBlock(scene: WorkScene, reviewed: DocRevisionRef | null): string | null {
103
- if (reviewed === null || (scene.target?.kind !== "plan" && scene.target?.kind !== "spec"))
104
- return null;
105
- return `the pending fix applies to the unchanged doc (doc-hash ${reviewed.doc_hash.slice(0, 12)}…) — run cdd fix first`;
106
- }
107
-
108
- /** The requested group ints — the normalized tasks value split. */
109
- tasksOf(parsed: RunInput): number[] {
110
- return (parsed.args.tasks ?? "").split(",").map((part) => Number(part));
111
- }
112
-
113
- /** Render the task group brief into the workspace (the implement dispatch's input)
114
- * — the brief mirrors the current plan (its task sections + the `## Constraints`
115
- * section, re-extracted at every dispatch). */
116
- renderBrief(scene: WorkScene, parsed: RunInput): string {
117
- const tasks = this.tasksOf(parsed);
118
- const content = this.#brief.render(scene.planText!, tasks);
119
- // The real run's workspace is built by the single write point (`Cli#runWork`'s
120
- // ensure, P11 · §4.2) BEFORE this render; the write still rides the workspace's
121
- // own text-write face (the `writeJson` mkdir-before-write pattern), never a
122
- // second explicit `ensure()` — no bare `writeFileSync` into a possibly absent dir.
123
- const name = new RoundNaming(scene.workspace).briefName(parsed.args.tasks ?? "");
124
- return scene.workspace.writeText(name, content);
125
- }
126
-
127
- /** The single-target line's current open phase — fix-awaits / re-review / closure
128
- * read from the ledger's SINGLE line-phase judge (`Ledger#linePhase`, D40 — the
129
- * retired gate twin): the gate and the lifecycle's frame frontier now read ONE
130
- * source, never a second walk. */
131
- #linePhase(scene: WorkScene): DispatchPhase | null {
132
- const key = this.#lineKey(scene);
133
- if (key === null) return null;
134
- return scene.ledger.linePhase(key, scene.face.type);
135
- }
136
-
137
- /** The line key of a fixed-target face — the line's STABLE key (find #9 · spec
138
- * §6.5/§3.7 — `"branch"` per workspace for the branch line; the doc line keys by
139
- * its line-type constant `"spec"`/`"plan"` — never the argv path: a moved argv
140
- * string must not fork the same line into two ledger rows, resetting its round),
141
- * the lifecycle's own key derivation (run.ts #lineKey). */
142
- #lineKey(scene: WorkScene): string | null {
143
- if (scene.target?.kind === "branch") return "branch";
144
- if (scene.target?.kind === "plan" || scene.target?.kind === "spec") return scene.face.type;
145
- return null;
146
- }
147
-
148
- /** The doc's live content — readable doc else null. This helper backs the face's
149
- * one remaining doc read site, the revision-aware BLOCK's version token — a read
150
- * fired only when the BLOCK message actually renders (the version is raw doc
151
- * grammar — zero parse dependence: the revision hash is a raw-content digest).
152
- * The gate's own doc read lives in the ledger (Ledger#docLineVerdict — one read
153
- * per reviewGate, the shared comparison). A BLOCK render is a run-failure prose
154
- * channel — never a usage face — so the read is guarded here (null on unreadable),
155
- * not routed through the artifacts readText's usage error. */
156
- #docContent(doc: string): string | null {
157
- try {
158
- return readFileSync(doc, "utf8");
159
- } catch {
160
- return null;
161
- }
162
- }
163
-
164
- /** The doc's `v<major>.<minor>` version token — the front-matter `version:`
165
- * scalar (the T6 read point: the header version facts ride the typed head
166
- * record — the fence split + `yaml` engine, never a line scan). */
167
- #docVersionOf(content: string | null): string | null {
168
- if (content === null) return null;
169
- return FrontMatterExtractor.split(content).head.version;
170
- }
171
- }
@@ -1,74 +0,0 @@
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
-
15
- import type { TaskGraphReport } from "../session/graph.ts";
16
-
17
- /** The progress-marker glyph set — the ONE display vocabulary both the wave board
18
- * (per-task markers) and the slug board (wave-level markers) render: ✔ done ·
19
- * ▶ current · ○ pending. Single-sourced here so the two faces share one home,
20
- * never a second declaration kept aligned by convention. */
21
- export const PROGRESS_MARKERS = { done: "✔", current: "▶", pending: "○" } as const;
22
-
23
- /** The progress-marker legend tail lines — one per face scope, the scope word
24
- * (`current` vs `current wave`) the ONE deliberate difference between the two
25
- * boards (the graph's tasks sit inside a wave; the slug board's wave-less scopes
26
- * carry no wave). The glyphs ride PROGRESS_MARKERS so the vocabulary has exactly
27
- * one home. */
28
- export const PROGRESS_LEGEND: Readonly<Record<"board" | "graph", string>> = {
29
- board: `progress: ${PROGRESS_MARKERS.done} done · ${PROGRESS_MARKERS.current} current · ${PROGRESS_MARKERS.pending} pending`,
30
- graph: `progress: ${PROGRESS_MARKERS.done} done · ${PROGRESS_MARKERS.current} current wave · ${PROGRESS_MARKERS.pending} pending`,
31
- };
32
-
33
- /** GraphView — the wave-board display: one deterministic row per derived wave, the
34
- * band's tasks inline with progress markers, the incoming source bands noted.
35
- * v1.20 — the in-wave marker mix: the done set rides `closedWaves()` (the report's
36
- * done projection, never "any ledger row"), and a current-wave task that is already
37
- * done shows ✔, never a swallowed whole-row ▶. */
38
- export class GraphView {
39
- /** render(report, title) → the wave-board + the legend (the plan read and the
40
- * pre-flight display call the same face). */
41
- render(report: TaskGraphReport, title: string): string {
42
- const done = new Set(report.done);
43
- const currentIndex = report.waves.findIndex((wave) => wave.some((id) => !done.has(id)));
44
- const markers = new Map<number, string>();
45
- for (const [index, wave] of report.waves.entries()) {
46
- for (const id of wave) {
47
- // The per-task marker, done first: a completed task shows ✔ even inside the
48
- // current wave (the mix), a not-done current-wave task shows ▶, the rest ○.
49
- markers.set(
50
- id,
51
- done.has(id)
52
- ? PROGRESS_MARKERS.done
53
- : index === currentIndex
54
- ? PROGRESS_MARKERS.current
55
- : PROGRESS_MARKERS.pending,
56
- );
57
- }
58
- }
59
- const rows = report.waves
60
- .map((wave, index) => {
61
- const tasks = wave
62
- .map((id) => `T${id}${markers.get(id) ?? PROGRESS_MARKERS.pending}`)
63
- .join(" · ");
64
- // find #6 (user 2026-10-09: "W1 fits the agent mindset better"): the board label = the
65
- // derived wave index + 1 (W1 · W2 · …) with no zero-padding — the plan's
66
- // execution-order labels reference this derived label verbatim (display
67
- // layer only; the wave derivation itself is unchanged).
68
- const line = ` W${index + 1} ${tasks}`;
69
- return index === currentIndex ? `${line} ← in-flight` : line;
70
- })
71
- .join("\n");
72
- return `${title}\n\nwave board:\n${rows}\n\n${PROGRESS_LEGEND.graph}`;
73
- }
74
- }