@oscaner-skills/cdd-engine 3.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 (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 +141 -0
  15. package/dist/face/cli.js +891 -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 +603 -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 +482 -0
  25. package/dist/face/words.js +220 -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 +441 -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,293 +0,0 @@
1
- // packages/cdd-engine/src-next/session/next.ts
2
- // T7 — NextStepRouter single point (design spec §3.2): the ONLY `next:` generation
3
- // face of the new tree. The C5 decision table (the spec's pinned semantics, v1.20:
4
- // the closure single-verdict — close() is the one closure point every review/fix
5
- // approval shares):
6
- // review zero findings → close(state) — the ready batch decides next-wave | done
7
- // review findings → fix (one-way — a review never previews what a fix will do)
8
- // fix blocker>0 → a re-review hop (the live tree, no commit identity)
9
- // fix blocker==0 → close(state) — the warn/nit-only / clean closure (#278,
10
- // no APPROVED-mandated re-review)
11
- // fix soft cap → the "BLOCKED: review-cycle-cap" suggestion (user adjudicates)
12
- // BLOCKED/TIMEOUT → null (no next line — the CDD_BLOCKED channel owns the face)
13
- //
14
- // close(state) — the v1.20 unified closure terminal: every closure point (a review
15
- // with zero findings / a fix whose source blockers cleared) renders the SAME route
16
- // family — `next-wave` when another wave is ready, `done` when the run is exhausted.
17
- // The `none` word is RETIRED (closure is `done`, never "no suggestion"), and a
18
- // completed non-failed round producing null is now a hard error on the dispatch face
19
- // (no next line = abnormal) — never a silent approved-without-next.
20
- //
21
- // The table judges the round carrier (ledger.ts — the fix round's own findings are
22
- // the source review's input, C5-1) against the execution state (state.ts — the
23
- // ready batch decides next-wave vs done). The Route output carries the structured
24
- // facts the capsule face renders into the `next:` line — including the fix-route
25
- // readback copy, authored here once as FIX_READBACK_SUFFIX (the declared wording
26
- // the capsule renders verbatim, never a literal restate).
27
- //
28
- // D40 — ONE "next step" concept: the face-INTERNAL C5 hop and the face-TO-face
29
- // handoff are the SAME `Route` union (a `handoff` kind carries the pipeline entry),
30
- // so a consumer never consults a second table. `NextStepRouter.resolve` is the ONE
31
- // "one line → next" resolver: an active C5 hop passes through, a drained line yields
32
- // the face-to-face handoff. Both the board (its per-line walk) and the capsule
33
- // (the round's own line) call it — single resolver, single renderer.
34
- //
35
- // Module-level exports are types / constants / the class — zero behavior-carrying
36
- // bare functions (the plan's zero-bare-function discipline).
37
-
38
- import type { RouteTarget } from "./faces.ts";
39
- import type { Round } from "./ledger.ts";
40
- import type { ExecutionState } from "./state.ts";
41
-
42
- /** The next-hop suggestion — the decision table's output (null = no next line). The
43
- * ONE "next step" concept (D40): the face-internal C5 hops AND the face-to-face
44
- * handoff are the same union, so a consumer never consults a second table. */
45
- export type Route =
46
- /** closure — the run is exhausted (`next: done`, the v1.20 terminal word). */
47
- | { kind: "done" }
48
- /** closure — another wave is ready: the next dispatch wave's task ids. */
49
- | { kind: "next-wave"; tasks: string }
50
- /** a review hop — a review judges the live tree, carrying no commit identity. */
51
- | { kind: "review" }
52
- /** the one-way fix hop — reviewsPath = the review handoff the fix reads (`--reviews`). */
53
- | { kind: "fix"; reviews?: string }
54
- /** the review-cycle soft cap — the suggestion defers to user adjudication. */
55
- | { kind: "soft-cap"; message: string }
56
- /** the face-to-face handoff (D40) — the line's C5 frontier exhausted, so the next
57
- * step is the next pipeline face's entry (`PIPELINE_NEXT[doc-class]`): the face
58
- * to face transition is ONE Route kind, never a second table a consumer reads. */
59
- | { kind: "handoff"; entry: PipelineEntry };
60
-
61
- /** The review-cycle soft cap — the consecutive-S1 run length at which the fix face
62
- * defers the next hop to user adjudication (soft by nature: a default suggestion,
63
- * never a hard stop — the user / the plan write authority override it). */
64
- export const REVIEW_CYCLE_CAP = 20;
65
-
66
- /** The decision-edge words of the Route union — the C5 hop kinds that a review/fix
67
- * closure decision edge renders as a `next:` label (`done` · `next-wave` · `review`
68
- * · `fix` · `soft-cap`). The pure face-to-face `handoff` kind is EXCLUDED: it carries
69
- * no decision word (it renders the pipeline entry ref/literal, never a branch label).
70
- * The skill-anatomy contract's `edgeConditionWords` derives from this tuple — the
71
- * runtime Route lexicon is the ONE source, never a second hand-written list. */
72
- export const ROUTE_DECISION_WORDS = ["done", "next-wave", "review", "fix", "soft-cap"] as const;
73
-
74
- // ---------------------------------------------------------------------------
75
- // the face indirection line — the pipeline's face-to-face `done` routing table (D33)
76
- // ---------------------------------------------------------------------------
77
-
78
- /** The doc-class keys of the unified next face — one row per pipeline seam a face
79
- * `done` can land on (the capsule's doc-class lookup reads them). */
80
- export type PipelineKey = "phase-spec" | "overall-spec" | "plan" | "wave" | "branch";
81
-
82
- /** One pipeline-next row — the skill ref to dispatch (`ref`), a literal command
83
- * (`literal`, the wave→branch transition — the wiring literal with its `<plan>`
84
- * slot), or the pipeline terminal (`done`). */
85
- export type PipelineEntry =
86
- | { kind: "ref"; ref: string }
87
- | { kind: "literal"; literal: string }
88
- | { kind: "done" };
89
-
90
- /** The pipeline next table — the ONE face-indirection source (D33 · single-addressed
91
- * at session/next.ts):
92
- * the doc-class key → the next pipeline entrypoint. The skill refs ride REFS
93
- * (face/host.ts) resolved per host at the render — never a hard-coded plugin
94
- * spelling; the wave literal's `<plan>` slot is filled by the capsule with the
95
- * frame's plan fact. */
96
- export const PIPELINE_NEXT: Readonly<Record<PipelineKey, PipelineEntry>> = {
97
- "phase-spec": { kind: "ref", ref: "kairos:cdd-plan" },
98
- "overall-spec": { kind: "done" },
99
- plan: { kind: "ref", ref: "kairos:cdd-dev" },
100
- wave: { kind: "literal", literal: "review --type branch --plan <plan>" },
101
- branch: { kind: "ref", ref: "kairos:cdd-close" },
102
- };
103
-
104
- /** The pipeline's phase-level face keys (D40) — `PipelineKey` minus the program-level
105
- * `overall-spec` (whose closure is the pipeline terminus, rendered by the capsule,
106
- * never walked). */
107
- export type PhaseFaceKey = Exclude<PipelineKey, "overall-spec">;
108
-
109
- /** The pipeline's phase-level face order (D40) — the face-to-face traversal
110
- * `spec → plan → wave → branch`, the ONE order declaration; `NextStepRouter.walk`
111
- * iterates it, so a consumer maps key → facts and declares NO order of its own. */
112
- export const PIPELINE_FACES: readonly PhaseFaceKey[] = ["phase-spec", "plan", "wave", "branch"];
113
-
114
- /** One pipeline face's OBSERVED state — the per-face facts a consumer reads off
115
- * disk and the ledger (never a judgment): whether the face is closed, its ACTIVE
116
- * C5 hop (null when the face never started), and the render target the literal
117
- * needs. The walk (`NextStepRouter.walk`) is the ONE decider over these
118
- * observations — a consumer reports facts, the router resolves the next step. */
119
- export interface PipelineFaceState {
120
- /** Whether the face's line is closed (its latest C5 route lies on the closure
121
- * side) — a face holding no open work (an empty wave segment) is closed. */
122
- closed: boolean;
123
- /** The face's active C5 hop — null when the face holds no open hop (not started). */
124
- active: Route | null;
125
- /** The face's render target (the literal's type + id + plan), or null when absent. */
126
- target: RouteTarget | null;
127
- }
128
-
129
- /** The consumer's face report — one observation per phase face, keyed by its
130
- * `PIPELINE_FACES` key (the order stays the router's; the consumer names faces). */
131
- export type PipelineFaceReport = Readonly<Record<PhaseFaceKey, PipelineFaceState>>;
132
-
133
- /** The walk's verdict — the ONE next Route + the render target it belongs to (the
134
- * frontier face's own target; the last face's on the all-closed terminal). */
135
- export interface PipelineNext {
136
- route: Route;
137
- target: RouteTarget | null;
138
- }
139
-
140
- /** The review-cycle soft-cap suggestion (the C5-0 suggestion face — user adjudicates). */
141
- export const SOFT_CAP_SUGGESTION = "BLOCKED: review-cycle-cap — user adjudicates";
142
-
143
- /** The fix-route readback suffix — appended verbatim to the fix findings path on the
144
- * route's `next:` render (`(confirm the findings · if a finding needs a ruling,
145
- * record the ruling in the findings file)`), a pure wording prompt: the
146
- * anti-blind-fix mechanical guard is the ledger round / C5-1, the suffix only
147
- * reminds the orchestrator to confirm the captured findings and, when a finding
148
- * needs a user ruling, record that ruling back into the findings file the fix
149
- * round consumes. `annotate` names the carrier action alone — distinct from
150
- * `backfill` (a durable fact landed into its owning doc), which stays the
151
- * ruling's destination when it asserts a project-level fact. */
152
- export const FIX_READBACK_SUFFIX =
153
- "(confirm the findings · if a finding needs a ruling, record the ruling in the findings file)";
154
-
155
- /** The failure face — a BLOCKED/TIMEOUT round goes the stderr CDD_BLOCKED channel and
156
- * produces no `next:` line on any op. Exported as the ONE failure-status set: the
157
- * skill-anatomy contract's `edgeConditionWords` derivation reads it to exclude the
158
- * failure statuses from the decision-edge status words (a failure round carries no
159
- * closure edge — the reason rides the CDD_BLOCKED channel). */
160
- export const FAILED_STATUS = new Set(["BLOCKED", "TIMEOUT"]);
161
-
162
- /**
163
- * NextStepRouter — the C5 decision table as one instance method. The router keeps
164
- * no hidden state: every judgment reads the execution state + the round carrier.
165
- */
166
- export class NextStepRouter {
167
- /** next(state, ref) — the C5 derivation: the next-hop Route, or null when the round
168
- * produces no next line (the BLOCKED/TIMEOUT failure-mode face). */
169
- next(state: ExecutionState, ref: Round): Route | null {
170
- // The failure face first — a BLOCKED/TIMEOUT round never gets a next suggestion.
171
- if (ref.status !== undefined && FAILED_STATUS.has(ref.status)) return null;
172
-
173
- switch (ref.phase) {
174
- case "implement":
175
- // The implement round completes → the group's review is the next hop. A
176
- // review judges the live tree, so the hop carries no commit identity.
177
- return { kind: "review" };
178
- case "review":
179
- // One-way: any findings (any severity) → the fix round — a review never previews
180
- // what the fix will do (C5-1). Zero findings (approved) → the unified closure: the
181
- // ready batch decides whether the next wave continues or the run is exhausted.
182
- if (ref.findings.length > 0) return { kind: "fix", reviews: ref.reviewsPath };
183
- return this.#close(state);
184
- case "fix": {
185
- // C5-1: the fix face is the re-review / closure decision point. The soft cap
186
- // outranks the blocker row — a capped run defers to the user, never auto-loops.
187
- if (ref.consecutiveS1 >= REVIEW_CYCLE_CAP) {
188
- return { kind: "soft-cap", message: SOFT_CAP_SUGGESTION };
189
- }
190
- if (this.#blockerCount(ref) > 0) {
191
- // Blockers remain in the input findings → the fix delta is re-reviewed. A
192
- // review judges the live tree, so the hop carries no commit identity.
193
- return { kind: "review" };
194
- }
195
- // No blockers → the unified closure: the ready batch decides next-wave | done
196
- // (a warn/nit-only fix closes — the #278 REVIEW_FIX state, no re-review preview).
197
- return this.#close(state);
198
- }
199
- case "branch-review":
200
- // The branch terminal face — findings route the fix; zero findings close the line
201
- // through the same unified closure terminal.
202
- return ref.findings.length > 0
203
- ? { kind: "fix", reviews: ref.reviewsPath }
204
- : this.#close(state);
205
- }
206
- }
207
-
208
- /** The unified closure terminal (v1.20) — the single way a review/fix closure renders
209
- * its next hop: the ready batch decides `next-wave` vs `done` (a closing review with
210
- * another wave ready continues the run; an exhausted run reports `done`). */
211
- #close(state: ExecutionState): Route {
212
- const ready = state.readyBatch();
213
- return ready.length > 0 ? { kind: "next-wave", tasks: ready.join(",") } : { kind: "done" };
214
- }
215
-
216
- /** The blocker count of the round's findings — the C5-1 severity count. */
217
- #blockerCount(ref: Round): number {
218
- return ref.findings.filter((finding) => finding.severity === "blocker").length;
219
- }
220
-
221
- /** The face-to-face handoff route for a pipeline doc-class (D40) — the next-face
222
- * entry (`PIPELINE_NEXT[key]`). One of the two ways the ONE "next step" concept
223
- * is produced (the C5 hop is the other), so a consumer never consults a second
224
- * table. */
225
- static handoff(key: PipelineKey): Route {
226
- return { kind: "handoff", entry: PIPELINE_NEXT[key] };
227
- }
228
-
229
- /** Resolve a line's next step (D40) — the capsule's "one line → next" point for the
230
- * round's OWN line: an ACTIVE C5 hop (`review` / `fix` / `implement` / `next-wave` /
231
- * `soft-cap`) passes through as the line's next step; a drained / not-yet-started
232
- * line (the C5 `done` / no active round) yields the face-to-face handoff carrying
233
- * the pipeline entry. A null doc-class (no face seam — the overall line / a bare
234
- * terminal) renders the bare `done` word. A whole-slug walk is `walk` (the board's
235
- * face-to-face traversal); this is the single-line form the capsule holds. Pure. */
236
- static resolve(active: Route | null, key: PipelineKey | null): Route {
237
- if (active !== null && active.kind !== "done") return active;
238
- return key === null ? { kind: "done" } : NextStepRouter.handoff(key);
239
- }
240
-
241
- /** Walk(face report) → the ONE next step (D40 · the board's face-to-face traversal
242
- * as a single router method). The caller REPORTS each face's facts keyed by its
243
- * `PIPELINE_FACES` key; the router iterates the ONE order and DECIDES the next step
244
- * — so no consumer re-derives the order OR the face-transition rule (the retired
245
- * board fork handed off via the frontier LINE's own key, so a slug whose spec just
246
- * closed but whose plan was not yet authored rendered `plan`'s exit `cdd-dev`
247
- * instead of the spec's exit `cdd-plan` — a face-boundary off-by-one the ONE walk
248
- * eliminates). The rule:
249
- * · the FRONTIER face (first not-closed) with an active C5 hop → render that hop
250
- * (the in-flight work — `review` / `fix` / `implement` / `next-wave`);
251
- * · the frontier has no active hop but IS entered (`target` present — an empty
252
- * wave segment, a drained-but-reached face) → its OWN pipeline exit entry;
253
- * · the frontier is NOT entered (no target — an absent doc, e.g. no plan yet) →
254
- * the transition INTO it, i.e. the PRECEDING entered face's exit entry (so a
255
- * just-closed spec hands off to the spec's exit `cdd-plan`, never the absent
256
- * plan's exit); no preceding entered face → the FIRST face's exit entry;
257
- * · every face closed → the LAST entered face's exit entry (the pipeline
258
- * terminus — `cdd-close` for a phase slug). */
259
- static walk(report: PipelineFaceReport): PipelineNext {
260
- const states = PIPELINE_FACES.map((key) => report[key]);
261
- const frontierIndex = states.findIndex((face) => !face.closed);
262
- if (frontierIndex === -1) {
263
- const terminalIndex = NextStepRouter.#lastEnteredIndex(states);
264
- const terminal = terminalIndex === -1 ? null : states[terminalIndex]!;
265
- return terminal === null
266
- ? { route: { kind: "done" }, target: null }
267
- : {
268
- route: NextStepRouter.handoff(PIPELINE_FACES[terminalIndex]!),
269
- target: terminal.target,
270
- };
271
- }
272
- const frontier = states[frontierIndex]!;
273
- if (frontier.active !== null) return { route: frontier.active, target: frontier.target };
274
- const anchorIndex =
275
- frontier.target !== null
276
- ? frontierIndex
277
- : Math.max(0, NextStepRouter.#lastEnteredIndex(states.slice(0, frontierIndex)));
278
- const anchor = states[anchorIndex]!;
279
- return {
280
- route: NextStepRouter.handoff(PIPELINE_FACES[anchorIndex]!),
281
- target: anchor.target,
282
- };
283
- }
284
-
285
- /** The index of the last OBSERVED face carrying a render target — the last face the
286
- * pipeline has REACHED (a face with no target was never entered). -1 when none is. */
287
- static #lastEnteredIndex(states: readonly PipelineFaceState[]): number {
288
- for (let i = states.length - 1; i >= 0; i--) {
289
- if (states[i]!.target !== null) return i;
290
- }
291
- return -1;
292
- }
293
- }
@@ -1,271 +0,0 @@
1
- // packages/cdd-engine/src-next/session/preflight.ts
2
- // P4.1 T1 — the lifecycle pre-flight seam (design spec §1): the dispatch gates
3
- // converge into ONE single-entry gate a work command consults before ANY child
4
- // dispatch — the clean-tree hard gate (tree-clean → BLOCKED with the commit/discard
5
- // guidance, the skill-side claim `engine entry gate: dirty → BLOCKED` finally made
6
- // real), then the wave-side gates (graph validate + the three-verb WaveGate)
7
- // and the doc-side gate (Contract.validate over the target doc).
8
- //
9
- // Gate order (the design's pinned sequence, judgeable on every verdict):
10
- // tree-clean → (wave/plan faces) graph validate → (wave face) WaveGate.vet →
11
- // (spec/plan faces) Contract.validate → dispatch
12
- // The evidence/read-back gates stay at the dispatch child face (the seam never
13
- // touches the round's produced artifacts — non-pre-flight by design).
14
- //
15
- // The verdict is the single BLOCK carrier: `gate` names the refusing gate, `reason`
16
- // the named refusal row, `message` the CDD_BLOCKED wording (pinned rows), `details`
17
- // the named issue/finding lines the renderer prints, `order` the gates that ran
18
- // (the CLI never re-implements a gate — the seam owns the whole sequence). BLOCK
19
- // wording rides the word table (the capsule station + the preflight rows), never a
20
- // CLI restate.
21
- //
22
- // Module-level exports are types / the class — zero behavior-carrying bare
23
- // functions (the plan's zero-bare-function discipline).
24
-
25
- import { existsSync, readdirSync, readFileSync } from "node:fs";
26
- import { PlanDocType } from "../contract/doc.ts";
27
- import { FrontMatterExtractor } from "../contract/frontmatter.ts";
28
- import type { DocFs } from "../contract/invariants.ts";
29
- import type { Contract } from "../contract/judge.ts";
30
- import type { DocKey } from "../contract/project.ts";
31
- import type { Words } from "../face/words.ts";
32
- import type { GitClient } from "../infra/git.ts";
33
- import { type RepoPath, RepoRoot } from "../infra/root.ts";
34
- import type { TargetType } from "./faces.ts";
35
- import { TaskGraph } from "./graph.ts";
36
- import type { Ledger } from "./ledger.ts";
37
- import { WaveGate } from "./wave.ts";
38
-
39
- /** The named gates the seam composes — the run evidence + the blocking gate label. */
40
- export type PreFlightGateName = "tree-clean" | "graph" | "wave" | "doc-contract";
41
-
42
- /** The named refusal rows — the BLOCK reason the CDD_BLOCKED wording fills. */
43
- export type PreFlightReason = "dirty-tree" | "graph" | "split" | "wrong-phase" | "doc-contract";
44
-
45
- /** One pre-flight verdict — the single BLOCK carrier of the dispatch gates. */
46
- export interface PreFlightVerdict {
47
- /** Whether the dispatch is approved (the gates passed). */
48
- ok: boolean;
49
- /** The refusing gate (absent when ok — no gate blocked). */
50
- gate?: PreFlightGateName;
51
- /** The named refusal row (absent when ok). */
52
- reason?: PreFlightReason;
53
- /** The rendered BLOCK wording — the CDD_BLOCKED channel carries it (word-table
54
- * rows + the WaveGate verdict's own filled rows). */
55
- message?: string;
56
- /** The named issue/finding lines the renderer prints under the message. */
57
- details?: readonly string[];
58
- /** The gates that ran, in order — the judgeable order (tree-clean → graph →
59
- * wave → doc-contract, per the face's applicable set). */
60
- order: readonly PreFlightGateName[];
61
- }
62
-
63
- /** The doc-contract target of a spec/plan dispatch. */
64
- export interface PreFlightDoc {
65
- /** The target doc type's registry key — read from the doc's front-matter
66
- * `doc-type:` key (spec §12 · D34; both the spec and the plan faces key by
67
- * the head key, zero command-type carve-out).
68
- * null when a present doc carries no key — the seam BLOCKs (zero
69
- * filename-suffix fallback, one declaration reading face `BoardView.readDocType`). */
70
- docKey: DocKey | null;
71
- /** The target doc's path — the branded repoRoot-relative `RepoPath` (T4 §2.2: a
72
- * bare `string` never reaches this read face; the caller feeds the funnel-shaped
73
- * relative value). The seam erases it to the absolute syscall form through its
74
- * OWN `RepoRoot(ctx.repoRoot)` just before the read — the brand is REAL (the
75
- * absolute state is unrepresentable as a `RepoPath`), the same shape as
76
- * `artifacts.readText(node, root, file: RepoPath)`). */
77
- path: RepoPath;
78
- }
79
-
80
- /** One dispatch's pre-flight inputs — the facts the seam judges. */
81
- export interface PreFlightContext {
82
- /** The requested dispatch verb (the three work verbs — the WaveGate's verb). */
83
- verb: "implement" | "review" | "fix";
84
- /** The dispatch's target type (wave / branch / spec / plan). */
85
- type: TargetType;
86
- /** The repo root the tree-clean gate reads. */
87
- repoRoot: string;
88
- /** The plan text (the wave/plan faces' graph gate input; null otherwise). */
89
- planText: string | null;
90
- /** The requested `--tasks` group (the wave face's WaveGate input). */
91
- tasks: ReadonlySet<number> | null;
92
- /** The session ledger (the wave face's WaveGate input). */
93
- ledger: Ledger | null;
94
- /** The doc-contract target of a spec/plan dispatch (null on the other faces). */
95
- doc: PreFlightDoc | null;
96
- }
97
-
98
- /**
99
- * PreFlight — the single pre-flight seam of the work dispatch. One `vet` call runs
100
- * the whole gate sequence in the pinned order and returns the verdict the CLI
101
- * renders (or approves): the seam owns the gates, the CLI only orchestrates the
102
- * call + the render — zero second implementation on the CLI face.
103
- */
104
- export class PreFlight {
105
- /** The git seam the tree-clean gate reads. */
106
- readonly #git: GitClient;
107
- /** The doc-contract coordinator the doc faces judge through. */
108
- readonly #contract: Contract;
109
- /** The three-verb unified wave gate the wave face consults. */
110
- readonly #waveGate: WaveGate;
111
- /** The word table the BLOCK wording rides. */
112
- readonly #words: Words;
113
- /** The filesystem seam the doc-contract gate reads (defaults to node:fs). */
114
- readonly #fs: DocFs;
115
-
116
- constructor(opts: {
117
- git: GitClient;
118
- contract: Contract;
119
- words: Words;
120
- waveGate?: WaveGate;
121
- fs?: DocFs;
122
- }) {
123
- this.#git = opts.git;
124
- this.#contract = opts.contract;
125
- this.#words = opts.words;
126
- this.#waveGate = opts.waveGate ?? new WaveGate();
127
- this.#fs = opts.fs ?? new NodeFs();
128
- }
129
-
130
- /** vet(ctx) — the single seam call: tree-clean → graph → wave → doc-contract.
131
- * The first refused gate owns the verdict; the gates that ran precede it (the
132
- * judgeable order). */
133
- async vet(ctx: PreFlightContext): Promise<PreFlightVerdict> {
134
- const gates: PreFlightGateName[] = [];
135
- // 1. tree-clean — the hard gate all three verbs share: a dirty working tree
136
- // BLOCKs BEFORE any other judgment (review's baseline = the committed state). isClean is
137
- // fail-open-false (a non-repo counts dirty — the CDD flow needs git).
138
- gates.push("tree-clean");
139
- if (!(await this.#git.isClean(ctx.repoRoot))) {
140
- return {
141
- ok: false,
142
- gate: "tree-clean",
143
- reason: "dirty-tree",
144
- message: this.#words.preflightWords().dirtyTree,
145
- order: gates,
146
- };
147
- }
148
- // 2. graph — the wave/plan faces' structural gate: the plan's DependsOn
149
- // graph must validate (missing-edge / missing-id / self-loop / cycle) before
150
- // the dispatch reads it. The task-loss class dies here, never silently.
151
- let graph: TaskGraph | null = null;
152
- if ((ctx.type === "wave" || ctx.type === "plan") && ctx.planText !== null) {
153
- gates.push("graph");
154
- graph = new TaskGraph(new PlanDocType("plan").parse(ctx.planText.split("\n")));
155
- const issues = graph.validate();
156
- if (issues.length > 0) {
157
- return {
158
- ok: false,
159
- gate: "graph",
160
- reason: "graph",
161
- message: this.#words.preflightWords().graph.replace("{count}", String(issues.length)),
162
- details: issues.map((issue) => `${issue.kind}@T${issue.task}: ${issue.message}`),
163
- order: gates,
164
- };
165
- }
166
- }
167
- // 3. wave — the three-verb unified wave gate (the task face's phase authority):
168
- // the requested `--tasks` must be EXACTLY the derived open wave at the verb's
169
- // phase. The refusal wording rides the wave-gate word-table rows.
170
- if (ctx.type === "wave" && graph !== null && ctx.ledger !== null && ctx.tasks !== null) {
171
- gates.push("wave");
172
- const verdict = this.#waveGate.vet(ctx.tasks, ctx.verb, graph, ctx.ledger, this.#words);
173
- if (!verdict.ok) {
174
- return {
175
- ok: false,
176
- gate: "wave",
177
- reason: verdict.reason,
178
- message: verdict.message ?? "",
179
- order: gates,
180
- };
181
- }
182
- }
183
- // 4. doc-contract — the doc faces' structural gate: the target doc must pass
184
- // Contract.validate (the interpreter's single judgment entry) before its
185
- // review/fix round dispatches. An unreadable doc carries no judgment (no
186
- // fabricated findings from an absent surface). A PRESENT doc carrying no
187
- // `doc-type:` key BLOCKs (spec §12 · D34: the declared type is
188
- // the one reading face, zero filename-suffix fallback).
189
- if (ctx.type === "spec" || ctx.type === "plan") {
190
- gates.push("doc-contract");
191
- const doc = ctx.doc;
192
- // The relative `RepoPath` erases to the absolute syscall form through the ONE
193
- // value object (the seam's OWN `RepoRoot(ctx.repoRoot)`) just before the read.
194
- const docAbsolute = doc === null ? null : new RepoRoot(ctx.repoRoot).resolve(doc.path);
195
- const content = docAbsolute === null ? null : this.#fs.read(docAbsolute);
196
- if (content !== null && doc !== null && docAbsolute !== null) {
197
- // D1 (position-carrying error): a front-matter block the `yaml` engine cannot parse is
198
- // BLOCKed with the REAL failure (line · column · reason) BEFORE the
199
- // doc-type judgment — an unparseable head also reads no doc-type, so the
200
- // parse check must precede the missing-key check (the misread fix: a
201
- // `[`-led author line reports "invalid YAML", never "no doc-type").
202
- const { head } = FrontMatterExtractor.split(content);
203
- const parseError = head.parseError;
204
- if (parseError !== null) {
205
- return {
206
- ok: false,
207
- gate: "doc-contract",
208
- reason: "doc-contract",
209
- message: this.#words
210
- .routeWord("frontmatterParse")
211
- .replace("{reason}", parseError.reason)
212
- .replace("{line}", String(parseError.line))
213
- .replace("{column}", String(parseError.column))
214
- .replace("{source}", parseError.source),
215
- order: gates,
216
- };
217
- }
218
- if (doc.docKey === null) {
219
- return {
220
- ok: false,
221
- gate: "doc-contract",
222
- reason: "doc-contract",
223
- message: this.#words.routeWord("docType"),
224
- order: gates,
225
- };
226
- }
227
- const findings = this.#contract.validate({
228
- docKey: doc.docKey,
229
- path: docAbsolute,
230
- content,
231
- root: ctx.repoRoot,
232
- fs: this.#fs,
233
- });
234
- if (findings.length > 0) {
235
- return {
236
- ok: false,
237
- gate: "doc-contract",
238
- reason: "doc-contract",
239
- message: this.#words.preflightWords().docContract,
240
- details: findings.map(
241
- (finding) => `${finding.kind}@${finding.field}: ${finding.message}`,
242
- ),
243
- order: gates,
244
- };
245
- }
246
- }
247
- }
248
- return { ok: true, order: gates };
249
- }
250
- }
251
-
252
- /** The node:fs default — the production seam for the doc-contract's file reads. */
253
- class NodeFs implements DocFs {
254
- read(p: string): string | null {
255
- try {
256
- return readFileSync(p, "utf8");
257
- } catch {
258
- return null;
259
- }
260
- }
261
- exists(p: string): boolean {
262
- return existsSync(p);
263
- }
264
- list(p: string): readonly string[] {
265
- try {
266
- return readdirSync(p);
267
- } catch {
268
- return [];
269
- }
270
- }
271
- }
@@ -1,84 +0,0 @@
1
- // packages/cdd-engine/src-next/session/round-naming.ts
2
- // P11 T4 — the round-naming single source: the frame → artifact-name derivations
3
- // (report · evidence · brief) the lifecycle's read-back and the dry-run preview
4
- // share, plus the frame → family-op mapping those names key on. The handoff carrier
5
- // name is NOT derived here — it stays with the Ledger's HANDOFF_FAMILIES table (the
6
- // naming table is the single truth, never a second list).
7
- //
8
- // Module-level exports are the class — zero behavior-carrying bare functions.
9
-
10
- import type { Workspace } from "../infra/workspace.ts";
11
- import type { OpType } from "./ledger.ts";
12
- import type { OpenFrame } from "./run.ts";
13
-
14
- /**
15
- * RoundNaming — the one home of a round's prescribed artifact names. A frame's
16
- * report / evidence / brief names derive here, so every consumer (the lifecycle's
17
- * write-back and read-back, the dry-run preview, the brief render) names the same
18
- * artifacts by the same rule — one fact, one place. The class holds only the
19
- * workspace the names resolve against.
20
- */
21
- export class RoundNaming {
22
- readonly #workspace: Workspace;
23
-
24
- constructor(workspace: Workspace) {
25
- this.#workspace = workspace;
26
- }
27
-
28
- /** The handoff-family op of a frame — branch-review rides the review family. The
29
- * artifact stems embed this op, so the mapping is a naming fact owned here (the
30
- * lifecycle's op read delegates, never a second copy of the rule). */
31
- op(frame: OpenFrame): OpType {
32
- return frame.phase === "branch-review" ? "review" : frame.phase;
33
- }
34
-
35
- /** The engine-rendered brief path of a wave's task group —
36
- * `tasks-{tasks}-brief.md` (the implement dispatch's read input; its producer is
37
- * `CliGate#renderBrief`). */
38
- brief(tasks: string): string {
39
- return this.#workspace.resolve(this.briefName(tasks));
40
- }
41
-
42
- /** The brief's workspace-relative NAME — the write face takes the name, the read
43
- * faces take the resolved path (one derivation, both spellings). */
44
- briefName(tasks: string): string {
45
- return `tasks-${tasks}-brief.md`;
46
- }
47
-
48
- /** The prescribed report path of a round — the doc line's
49
- * `{type}-{op}-{round}-report.md` stem, the wave/branch line's
50
- * `{family}-{op}{-round}-report.md` (the implement round carries no round token:
51
- * the line keys the implement round alone). */
52
- report(frame: OpenFrame): string {
53
- if (frame.type === "spec" || frame.type === "plan") {
54
- return this.#workspace.resolve(`${frame.type}-${this.op(frame)}-${frame.round}-report.md`);
55
- }
56
- const family = frame.type === "wave" ? `tasks-${frame.params.tasks ?? ""}` : "branch";
57
- const suffix = frame.phase === "implement" ? "" : `-${frame.round}`;
58
- return this.#workspace.resolve(`${family}-${this.op(frame)}${suffix}-report.md`);
59
- }
60
-
61
- /** The prescribed test-evidence path of a round — "" off the work faces (the doc
62
- * lines and the review rounds prescribe no evidence file). */
63
- evidence(frame: OpenFrame): string {
64
- const name = this.evidenceName(frame);
65
- return name === "" ? "" : this.#workspace.resolve(name);
66
- }
67
-
68
- /** The test-evidence file NAME of a work frame — the workspace-relative face the
69
- * read-back gate reads it by (`{line}-test-evidence.json`: the task families key
70
- * the line, the branch line names the family alone). "" off the work faces. */
71
- evidenceName(frame: OpenFrame): string {
72
- if (frame.type === "spec" || frame.type === "plan") return "";
73
- if (frame.phase !== "implement" && frame.phase !== "fix") return "";
74
- const key = frame.type === "wave" ? (frame.params.tasks ?? "") : "";
75
- const line = key === "" ? this.prefix(frame) : `${this.prefix(frame)}-${key}`;
76
- return `${line}-test-evidence.json`;
77
- }
78
-
79
- /** The evidence file's family prefix — `tasks` for the wave families, `branch`
80
- * for the branch line (never the misleading tasks- spine). */
81
- prefix(frame: OpenFrame): string {
82
- return frame.type === "wave" ? "tasks" : "branch";
83
- }
84
- }