@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
@@ -1,326 +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
-
27
- /** The component-value types of the argv channel (the CLI parse validates by these). */
28
- export type ChannelValueType = "string" | "path" | "int-list" | "enum" | "int" | "bool";
29
-
30
- /** One argv-channel row — the flag/type/enum declaration of one CLI key. */
31
- export interface ChannelArgRow {
32
- /** The `--flag` spelling. */
33
- flag: string;
34
- /** The complement alias (help's `-h`), when the channel declares one. */
35
- alias?: string;
36
- /** The component-value type the CLI parse validates by. */
37
- type: ChannelValueType;
38
- /** The enum domain, when the type is enum. */
39
- values?: readonly string[];
40
- /** The program-scope marker (dry-run/help — accepted at any position). */
41
- scope?: "program";
42
- /** The flag-level help line — the commander option description (one global key
43
- * text, single-sourced at the channel). */
44
- help?: string;
45
- }
46
-
47
- /** The argv channel table — the CLI flag/type/enum single source (the engine-config
48
- * argv channel verbatim: flag spellings, value types and enum domains ride these
49
- * rows, and the command declarations + the channel audit read them from here). The
50
- * `help` rows are the flag-level descriptions of the commander Options face (one
51
- * text per key, shared by every command that declares it). */
52
- export const ARGV_CHANNEL = {
53
- plan: { flag: "--plan", type: "path", help: "the CDD plan document path" },
54
- spec: { flag: "--spec", type: "path", help: "the design-spec document path" },
55
- findings: {
56
- flag: "--findings",
57
- type: "path",
58
- help: "the source review handoff JSON path",
59
- },
60
- tasks: {
61
- flag: "--tasks",
62
- type: "int-list",
63
- help: "the task ids of the wave group (comma-separated)",
64
- },
65
- type: {
66
- flag: "--type",
67
- type: "enum",
68
- values: ["wave", "branch", "spec", "plan"],
69
- help: "the target face of the round",
70
- },
71
- base: { flag: "--base", type: "string", help: "the base artifact branch name" },
72
- round: { flag: "--round", type: "int", help: "the review/fix round number" },
73
- source: {
74
- flag: "--source",
75
- type: "enum",
76
- values: ["plan-field", "branch-upstream", "conversation-context", "user-confirmed"],
77
- help: "the base artifact's source channel",
78
- },
79
- force: { flag: "--force", type: "bool", help: "override the existing base artifact" },
80
- dryRun: {
81
- flag: "--dry-run",
82
- type: "bool",
83
- scope: "program",
84
- help: "synthetic dispatch — book the round without a child spawn",
85
- },
86
- help: {
87
- flag: "--help",
88
- alias: "-h",
89
- type: "bool",
90
- scope: "program",
91
- help: "show this help",
92
- },
93
- root: {
94
- flag: "--root",
95
- type: "path",
96
- help: "the repository root (default: the current git top level)",
97
- },
98
- output: {
99
- flag: "--output",
100
- type: "enum",
101
- values: ["json", "skeleton"],
102
- help: "the schema render face — json (the derived declaration, default) or skeleton (the scaffold written into <target>)",
103
- },
104
- } as const satisfies Readonly<Record<string, ChannelArgRow>>;
105
-
106
- /** The shaped channel subset — the value-domain-validated channel types
107
- * (string/path/bool carry no parser — the unshaped faces register absent). */
108
- export type ShapedChannelValueType = "enum" | "int-list" | "int";
109
-
110
- /** The value-domain shapes — the parsed raw's check + normalization per shaped
111
- * channel type: the parseArg family's single executor source (§4.1). Each rule
112
- * validates the raw against the row's declared domain and returns the normalized
113
- * value; a non-conforming raw throws commander.InvalidArgumentError with the
114
- * pinned error bytes (the value-domain error messages are a pinned surface —
115
- * zero byte drift across the retired method family). The enum rule reads the
116
- * row's declared `values`; the int-list normalization rewrites the consumed
117
- * shape, never the run face's own normalization. Data rows, never bare
118
- * functions — one executor reads them (face/projection.ts #parseArgOf). */
119
- export const VALUE_SHAPES: Readonly<
120
- Record<ShapedChannelValueType, { parse(raw: string, row: ChannelArgRow): string }>
121
- > = {
122
- enum: {
123
- parse(raw, row) {
124
- if (!(row.values ?? []).includes(raw)) {
125
- throw new InvalidArgumentError(`must be one of ${(row.values ?? []).join(" | ")}`);
126
- }
127
- return raw;
128
- },
129
- },
130
- "int-list": {
131
- parse(raw) {
132
- const parts = raw.split(",").map((part) => part.trim());
133
- const invalid = parts.find((part) => !/^\d+$/.test(part));
134
- if (invalid !== undefined) {
135
- throw new InvalidArgumentError(
136
- `--tasks <n|n,n,…> — must be comma-separated integers: ${invalid}`,
137
- );
138
- }
139
- return [...new Set(parts.map(Number))].sort((a, b) => a - b).join(",");
140
- },
141
- },
142
- int: {
143
- parse(raw) {
144
- if (!/^\d+$/.test(raw)) {
145
- throw new InvalidArgumentError("must be an integer");
146
- }
147
- return raw;
148
- },
149
- },
150
- };
151
-
152
- /** The seven subcommand words — the CLI command face (implement · review · fix ·
153
- * schema · issue · base · board). */
154
- export type CliVerb = "implement" | "review" | "fix" | "schema" | "issue" | "base" | "board";
155
-
156
- /** The nested leaf words — the sub-command surfaces of the pure commands. */
157
- export type CliLeafName = "get" | "set" | "render";
158
-
159
- /** A per-command value-type override — a declared key whose value shape differs
160
- * from the channel's global typing for that key (base set's `--base` carries a
161
- * branch name — the branch-domain display token/help). */
162
- export type CliValueOverride = "branch";
163
-
164
- /** One declared arg of a command — the key + how strictly the run requires it. */
165
- export interface CliArgSpec {
166
- /** The canonical engine-config argv-channel key. */
167
- key: string;
168
- /** Whether the run requires the value (enforced at parse — .requiredOption() /
169
- * a required .argument()). */
170
- required?: boolean;
171
- /** The value-type override (only where the command's use differs from the channel). */
172
- valueType?: CliValueOverride;
173
- }
174
-
175
- /** One nested leaf command (base set|get · schema get · issue render). */
176
- export interface CliLeafSpec {
177
- name: CliLeafName;
178
- description: string;
179
- keys: readonly CliArgSpec[];
180
- positionals?: readonly CliArgSpec[];
181
- }
182
-
183
- /** One subcommand declaration — the command face's data row. */
184
- export interface CliCommandSpec {
185
- name: CliVerb;
186
- description: string;
187
- keys: readonly CliArgSpec[];
188
- positionals?: readonly CliArgSpec[];
189
- leaves?: readonly CliLeafSpec[];
190
- /** One minimal runnable example (the help face's Examples section — projected by
191
- * the builder's .addHelpText(); the P1 example sentences). */
192
- example?: string;
193
- }
194
-
195
- /** The seven subcommand declarations — implement, review, fix (the lifecycle work
196
- * commands) plus the pure base / schema / issue artifact commands and the board
197
- * observability command. */
198
- export const CLI_COMMANDS: readonly CliCommandSpec[] = [
199
- {
200
- name: "implement",
201
- description: "run the task implement phase",
202
- example: "cdd implement --tasks 1,2 --plan docs/kairos/plans/p3.md",
203
- keys: [{ key: "tasks", required: true }, { key: "plan", required: true }, { key: "root" }],
204
- },
205
- {
206
- name: "review",
207
- description: "run a review — task | branch | spec | plan",
208
- example: "cdd review --type spec --spec docs/kairos/specs/p3-design.md",
209
- keys: [
210
- { key: "type", required: true },
211
- { key: "tasks" },
212
- { key: "plan" },
213
- { key: "spec" },
214
- { key: "round" },
215
- { key: "root" },
216
- ],
217
- },
218
- {
219
- name: "fix",
220
- description: "fix review findings — task | branch | spec | plan",
221
- example: "cdd fix --type wave --tasks 1 --findings tasks-1-review-1.json",
222
- keys: [
223
- { key: "type", required: true },
224
- { key: "tasks" },
225
- { key: "findings" },
226
- { key: "spec" },
227
- { key: "plan" },
228
- { key: "root" },
229
- ],
230
- },
231
- {
232
- name: "base",
233
- description: "read/write base.json (single CDD --plan target)",
234
- example: "cdd base set --plan docs/kairos/plans/p3.md --base develop --source plan-field",
235
- keys: [],
236
- leaves: [
237
- {
238
- name: "set",
239
- description: "write the base artifact",
240
- keys: [
241
- { key: "plan", required: true },
242
- { key: "base", required: true, valueType: "branch" },
243
- { key: "source", required: true },
244
- { key: "force" },
245
- ],
246
- },
247
- {
248
- name: "get",
249
- description: "read the base artifact",
250
- keys: [{ key: "plan", required: true }],
251
- },
252
- ],
253
- },
254
- {
255
- name: "schema",
256
- description: "read canonical doc-structure schemas (discovery, zero enforcement)",
257
- example: "cdd schema get phase-spec",
258
- keys: [{ key: "plan" }],
259
- leaves: [
260
- {
261
- name: "get",
262
- description:
263
- "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)",
264
- keys: [{ key: "plan" }, { key: "output" }],
265
- positionals: [{ key: "type", required: true }, { key: "target" }],
266
- },
267
- ],
268
- },
269
- {
270
- name: "issue",
271
- description: "aggregate issue-body rendering (cdd issue render, zero enforcement)",
272
- example: "cdd issue render < findings.json",
273
- keys: [],
274
- leaves: [
275
- {
276
- name: "render",
277
- description: "render the aggregate issue body (stdin findings JSON → stdout)",
278
- keys: [],
279
- },
280
- ],
281
- },
282
- {
283
- name: "board",
284
- description: "render the slug progress board (overall/spec/plan/wave/branch)",
285
- example: "cdd board 2026-10-10-engine-doc-tooling-p7",
286
- keys: [{ key: "root" }],
287
- positionals: [{ key: "slug", required: true }],
288
- },
289
- ];
290
-
291
- /** The schema `<type>` vocabulary — the get leaf's ONE table (spec §5.3): the
292
- * primary DocKey spellings (overall-spec | plan | phase-spec | single-spec) plus
293
- * the legacy `phaseSpec` alias row normalized to the kebab key. One normalizing
294
- * vocabulary, never a second hand-written list — the builder's #parseTypeKey
295
- * validates through it. */
296
- export const SCHEMA_TYPE_KEYS: Readonly<Record<string, DocKey>> = {
297
- "overall-spec": "overall-spec",
298
- plan: "plan",
299
- "phase-spec": "phase-spec",
300
- "single-spec": "single-spec",
301
- phaseSpec: "phase-spec",
302
- };
303
-
304
- /** The conditional required group per work verb + target type — the preAction hook's
305
- * data face (spec §4.2): review `{plan}` / `{spec}` / `{plan}` · fix `{plan}` /
306
- * `{spec}` / `{findings, plan}` — every branch face carries the `--plan` workspace
307
- * identity (the branch line holds no commit ref: the review judges the live tree,
308
- * the scope anchor BASE_BRANCH is engine-injected at dispatch). Keyed by declared
309
- * flag spelling; non-exclusive — a round declaring both `--plan` and `--spec`
310
- * stays accepted (no mutual-exclusion rejection). */
311
- export const REQUIRED_GROUPS: Readonly<
312
- Record<"review" | "fix", Readonly<Record<string, readonly string[]>>>
313
- > = {
314
- review: {
315
- wave: ["--plan"],
316
- spec: ["--spec"],
317
- plan: ["--plan"],
318
- branch: ["--plan"],
319
- },
320
- fix: {
321
- wave: ["--plan"],
322
- spec: ["--spec"],
323
- plan: ["--plan"],
324
- branch: ["--findings", "--plan"],
325
- },
326
- };
@@ -1,170 +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, writeFileSync } from "node:fs";
12
- import { MarkdownPrimitives } from "../contract/doc.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 type { RunInput, WorkScene } from "./cli.ts";
17
-
18
- /**
19
- * CliGate — the target/line gate family (the split contract's gate face): the
20
- * readiness judgments the work commands consult before dispatching a round. The
21
- * instance's methods take the per-invocation scene; the gate holds only the stable
22
- * collaborators it needs (the brief renderer). The verdict-bearing methods return
23
- * their ruling + message — the root renders, never re-judges.
24
- */
25
- export class CliGate {
26
- readonly #brief: BriefRenderer;
27
-
28
- constructor(opts: { brief?: BriefRenderer } = {}) {
29
- this.#brief = opts.brief ?? new BriefRenderer();
30
- }
31
-
32
- /** The single-target line's current open phase plus the doc-line verdict the gate
33
- * judged — the {phase, verdict} pair IS the gate's ruling: the revision-aware
34
- * BLOCK renders only the "same" verdict the gate returned, the pending-fix note
35
- * only the derived pending face, never a recomputed one. The task face holds no
36
- * separate gate here: the WaveGate's wrong-phase verdict (the pre-flight) IS the
37
- * task-face phase authority — the wave gate is the single phase authority. A
38
- * doc line's gate is the reviewGate method family (T8 · §3.5 · judgment order =
39
- * doc revision FIRST, shared by the lifecycle's frame phase so an opened gate
40
- * dispatches): a moved doc opens the review lead whatever the round/route state
41
- * says (fix after · backfill after · user-decision after are the SAME case — the
42
- * stuck "next round is fix after an aborted fix" never freezes a revised doc),
43
- * an unchanged doc yields the gate's "same" verdict — the pending fix DERIVED
44
- * from the latest review's non-APPROVED conclusion opens only the fix phase,
45
- * while the no-pending face falls back to the legacy rounds/routes judgment: a
46
- * completed-fix line reopens the review lead through its fix round's C5-1 route
47
- * (the lifecycle's own fall-through — an open gate and a dispatchable frame
48
- * agree), a truly closed line keeps the revision-aware BLOCK. An unbound line
49
- * (no identity on record / an unreadable doc) keeps the legacy round/route
50
- * judgment + the generic closed message (only present facts land). */
51
- lineGate(scene: WorkScene): {
52
- phase: DispatchPhase | null;
53
- verdict: "same" | "pending-fix" | null;
54
- reviewed: DocRevisionRef | null;
55
- } {
56
- if (scene.target?.kind === "doc") {
57
- const key = this.#lineKey(scene);
58
- if (key === null) return { phase: null, verdict: null, reviewed: null };
59
- const verdict = scene.ledger.reviewGate(key, scene.target.doc, scene.face.type);
60
- if (verdict.kind === "open") {
61
- return { phase: scene.face.product.reviewLead, verdict: null, reviewed: null };
62
- }
63
- if (verdict.kind === "same") {
64
- if (verdict.pending) {
65
- return { phase: "fix", verdict: "pending-fix", reviewed: verdict.reviewed };
66
- }
67
- // same + no pending fix — the legacy rounds/routes judgment (the lifecycle's
68
- // own fall-through): a completed-fix line reopens the review lead through its
69
- // fix round's C5-1 route; a truly closed line keeps the revision-aware BLOCK.
70
- const open = this.#linePhase(scene);
71
- return open !== null
72
- ? { phase: open, verdict: null, reviewed: null }
73
- : { phase: null, verdict: "same", reviewed: verdict.reviewed };
74
- }
75
- }
76
- const open = this.#linePhase(scene);
77
- return { phase: open, verdict: null, reviewed: null };
78
- }
79
-
80
- /** The doc line's revision-aware BLOCK message (T7/T8) — the unchanged-approved
81
- * face: "{plan|spec} already reviewed at vX.Y (doc-hash …) — target revision
82
- * unchanged; amend body/version to open a new review". Renders ONLY on the
83
- * gate's "same" verdict — the approved identity the gate judged, whose reviewed
84
- * ref the message names: the block consumes the verdict's identity, never a
85
- * second ledger lookup (the face's judgment read points converge to the
86
- * method family). Null off that face or with no identity ("target revision
87
- * unchanged" is a present fact only there). */
88
- docLineBlock(scene: WorkScene, reviewed: DocRevisionRef | null): string | null {
89
- if (reviewed === null || scene.target?.kind !== "doc") return null;
90
- const version = this.#docVersionOf(this.#docContent(scene.target.doc));
91
- 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`;
92
- }
93
-
94
- /** The doc line's derived pending-fix note (T8) — the unchanged + non-APPROVED
95
- * face: "the pending fix applies to the unchanged doc (doc-hash …) — run cdd
96
- * fix first". Renders ONLY for the gate's "pending-fix" verdict — the derived
97
- * fix-awaited face (a same-doc re-review stays refused until its fix lands,
98
- * Review Convergence anti-spin); the message names the reviewed identity the
99
- * gate judged. */
100
- pendingFixBlock(scene: WorkScene, reviewed: DocRevisionRef | null): string | null {
101
- if (reviewed === null || scene.target?.kind !== "doc") return null;
102
- return `the pending fix applies to the unchanged doc (doc-hash ${reviewed.doc_hash.slice(0, 12)}…) — run cdd fix first`;
103
- }
104
-
105
- /** The requested group ints — the normalized tasks value split. */
106
- tasksOf(parsed: RunInput): number[] {
107
- return (parsed.args.tasks ?? "").split(",").map((part) => Number(part));
108
- }
109
-
110
- /** Render the task group brief into the workspace (the implement dispatch's input)
111
- * — the brief mirrors the current plan (its task sections + the `## Constraints`
112
- * section, re-extracted at every dispatch). */
113
- renderBrief(scene: WorkScene, parsed: RunInput): string {
114
- const tasks = this.tasksOf(parsed);
115
- const content = this.#brief.render(scene.planText!, tasks);
116
- const briefPath = scene.workspace.resolve(`tasks-${parsed.args.tasks}-brief.md`);
117
- writeFileSync(briefPath, content, "utf8");
118
- return briefPath;
119
- }
120
-
121
- /** The single-target line's current open phase — fix-awaits / re-review / closure
122
- * read from the ledger's SINGLE line-phase judge (`Ledger#linePhase`, D40 — the
123
- * retired gate twin): the gate and the lifecycle's frame frontier now read ONE
124
- * source, never a second walk. */
125
- #linePhase(scene: WorkScene): DispatchPhase | null {
126
- const key = this.#lineKey(scene);
127
- if (key === null) return null;
128
- return scene.ledger.linePhase(key, scene.face.type);
129
- }
130
-
131
- /** The line key of a fixed-target face — the line's STABLE key (find #9 · spec
132
- * §6.5/§3.7 — `"branch"` per workspace for the branch line; the doc line keys by
133
- * its line-type constant `"spec"`/`"plan"` — never the argv path: a moved argv
134
- * string must not fork the same line into two ledger rows, resetting its round),
135
- * the lifecycle's own key derivation (run.ts #lineKey). */
136
- #lineKey(scene: WorkScene): string | null {
137
- if (scene.target?.kind === "branch") return "branch";
138
- if (scene.target?.kind === "doc") return scene.face.type;
139
- return null;
140
- }
141
-
142
- /** The doc's live content — readable doc else null. This helper backs the face's
143
- * one remaining doc read site, the revision-aware BLOCK's version token — a read
144
- * fired only when the BLOCK message actually renders (the version is raw doc
145
- * grammar — zero parse dependence: the revision hash is a raw-content digest).
146
- * The gate's own doc read lives in the ledger (Ledger#docLineVerdict — one read
147
- * per reviewGate, the shared comparison). A BLOCK render is a run-failure prose
148
- * channel — never a usage face — so the read is guarded here (null on unreadable),
149
- * not routed through the artifacts readText's usage error. */
150
- #docContent(doc: string): string | null {
151
- try {
152
- return readFileSync(doc, "utf8");
153
- } catch {
154
- return null;
155
- }
156
- }
157
-
158
- /** The doc's `v<major>.<minor>` version token — the first token on the
159
- * `**Version**` header line (the shared version-token grammar's one home —
160
- * MarkdownPrimitives.versionTokensOf · contract/doc.ts). */
161
- #docVersionOf(content: string | null): string | null {
162
- if (content === null) return null;
163
- for (const line of content.split("\n")) {
164
- if (line.trimStart().startsWith("- **Version**:")) {
165
- return MarkdownPrimitives.versionTokensOf(line)[0] ?? null;
166
- }
167
- }
168
- return null;
169
- }
170
- }
@@ -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
- }