@oscaner-skills/cdd-engine 2.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/package.json +4 -3
  4. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  5. package/src-next/__tests__/floor.guard.test.ts +69 -0
  6. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  7. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  8. package/src-next/__tests__/smoke.integration.test.ts +60 -77
  9. package/src-next/__tests__/support/strip-comments.ts +99 -0
  10. package/src-next/__tests__/zero-dep.test.ts +6 -46
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +39 -21
  12. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +40 -28
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +40 -23
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +38 -21
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +21 -6
  16. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +22 -12
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +23 -8
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +21 -6
  19. package/src-next/contract/__tests__/declare.test.ts +251 -12
  20. package/src-next/contract/__tests__/doc.test.ts +214 -45
  21. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  22. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  23. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  24. package/src-next/contract/__tests__/judge.test.ts +410 -172
  25. package/src-next/contract/__tests__/lint.test.ts +49 -39
  26. package/src-next/contract/__tests__/project.test.ts +60 -19
  27. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  28. package/src-next/contract/declare.ts +179 -91
  29. package/src-next/contract/doc.ts +227 -164
  30. package/src-next/contract/frontmatter.ts +233 -0
  31. package/src-next/contract/home-extractors.ts +397 -0
  32. package/src-next/contract/invariants.ts +214 -69
  33. package/src-next/contract/judge.ts +28 -19
  34. package/src-next/contract/lint.ts +5 -41
  35. package/src-next/contract/project.ts +103 -43
  36. package/src-next/contract/skill-anatomy.ts +39 -11
  37. package/src-next/face/__tests__/board-view.test.ts +318 -115
  38. package/src-next/face/__tests__/capsule.test.ts +49 -25
  39. package/src-next/face/__tests__/channel-closure.guard.test.ts +28 -1
  40. package/src-next/face/__tests__/cli.test.ts +1091 -837
  41. package/src-next/face/__tests__/face.test.ts +5 -5
  42. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  43. package/src-next/face/__tests__/preview.test.ts +374 -0
  44. package/src-next/face/__tests__/projection.test.ts +5 -3
  45. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  46. package/src-next/face/__tests__/termination.test.ts +650 -0
  47. package/src-next/face/artifacts.ts +90 -37
  48. package/src-next/face/board-view.ts +128 -138
  49. package/src-next/face/capsule.ts +30 -16
  50. package/src-next/face/cli.ts +306 -97
  51. package/src-next/face/declare.ts +15 -18
  52. package/src-next/face/gate.ts +19 -18
  53. package/src-next/face/host.ts +6 -30
  54. package/src-next/face/lifecycle.ts +213 -188
  55. package/src-next/face/preview.ts +151 -0
  56. package/src-next/face/projection.ts +4 -1
  57. package/src-next/face/route-render.ts +39 -14
  58. package/src-next/face/termination.ts +573 -0
  59. package/src-next/face/words.ts +20 -2
  60. package/src-next/infra/__tests__/infra.test.ts +49 -3
  61. package/src-next/infra/__tests__/root.test.ts +56 -0
  62. package/src-next/infra/doc-roots.ts +29 -0
  63. package/src-next/infra/root.ts +73 -0
  64. package/src-next/infra/runtime.ts +12 -65
  65. package/src-next/infra/workspace.ts +95 -5
  66. package/src-next/render/__tests__/render.test.ts +92 -41
  67. package/src-next/render/__tests__/skeleton.test.ts +282 -64
  68. package/src-next/render/issue-body.ts +5 -2
  69. package/src-next/render/skeleton.ts +155 -90
  70. package/src-next/render/templates.ts +51 -56
  71. package/src-next/session/__tests__/graph.test.ts +11 -4
  72. package/src-next/session/__tests__/ledger.test.ts +3 -2
  73. package/src-next/session/__tests__/next.test.ts +100 -8
  74. package/src-next/session/__tests__/preflight.test.ts +79 -25
  75. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  76. package/src-next/session/__tests__/run.test.ts +140 -128
  77. package/src-next/session/__tests__/wave.test.ts +11 -4
  78. package/src-next/session/ledger.ts +96 -24
  79. package/src-next/session/next.ts +116 -15
  80. package/src-next/session/preflight.ts +41 -10
  81. package/src-next/session/round-naming.ts +84 -0
  82. package/src-next/session/run.ts +24 -20
  83. package/templates/report/issue-body.json +0 -46
  84. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
@@ -41,12 +41,19 @@ const fixture = (): { ledger: Ledger; repo: string; cleanup: () => void } => {
41
41
  };
42
42
  };
43
43
 
44
- /** A plan document over `### Task N:` blocks + `- **DependsOn**:` values. */
44
+ /** A plan document over `### Task N:` blocks + `- **DependsOn**:` values (the
45
+ * front-matter head the plan parser reads). */
45
46
  const planDoc = (blocks: readonly (readonly string[])[]): string => {
46
47
  return [
47
- "# Test Plan",
48
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
49
- "- **Parent program**: [x-overall.md v1.0](docs/kairos/specs/x-overall.md)",
48
+ "---",
49
+ "title: Test Plan",
50
+ "doc-type: plan",
51
+ "version: v1.0",
52
+ "date: 2026-10-09",
53
+ "spec: docs/kairos/specs/x-design.md",
54
+ "parent-program: docs/kairos/specs/x-overall.md",
55
+ "parent-version: v1.0",
56
+ "---",
50
57
  "",
51
58
  "## Constraints",
52
59
  "",
@@ -15,7 +15,7 @@
15
15
  // handoff carrier's union).
16
16
  // · round — the round carrier: the handoff presented as the Round the dispatch
17
17
  // next-router judges. A fix round carries the SOURCE review's findings (the
18
- // `--findings` input content, C5-1), never its own; the consecutive-S1 run is
18
+ // `--reviews` input content, C5-1), never its own; the consecutive-S1 run is
19
19
  // walked from the round history (the review-cycle soft-cap basis).
20
20
  //
21
21
  // Module-level exports are types / constant data / the class — zero behavior-
@@ -24,6 +24,7 @@
24
24
  import { createHash } from "node:crypto";
25
25
  import { readFileSync } from "node:fs";
26
26
  import type { ConfigLoader } from "../infra/config.ts";
27
+ import type { RepoPath, RepoRoot } from "../infra/root.ts";
27
28
  import type { HandoffFamily } from "../infra/runtime.ts";
28
29
  import type { Workspace } from "../infra/workspace.ts";
29
30
  import { BriefRenderer } from "../render/brief.ts";
@@ -88,8 +89,8 @@ export interface Round {
88
89
  status?: RoundStatus;
89
90
  /** The findings the next-hop derivation judges. */
90
91
  findings: readonly RoundFinding[];
91
- /** The findings handoff path (fix: the `--findings` input; review: its own handoff). */
92
- findingsPath?: string;
92
+ /** The review handoff path (fix: the `--reviews` input; review: its own handoff). */
93
+ reviewsPath?: string;
93
94
  /** The consecutive-S1 run (the leading blocker-lead reviews, newest first) — the
94
95
  * review-cycle soft-cap basis. */
95
96
  consecutiveS1: number;
@@ -146,28 +147,57 @@ export interface ProgressData {
146
147
  /** The ledger lookup key — a scalar task id or the group key string. */
147
148
  export type LedgerKey = number | string;
148
149
 
150
+ /** The dispatch-termination vocabulary — why a round was cut short (single source:
151
+ * the terminator derives the cause from the child's own result face, the crash
152
+ * record carries it as a postmortem fact, zero behavior fork — resume never routes
153
+ * on it). `stalled` = the engine's stall judgment killed the child; `over-budget` =
154
+ * the wall-clock ceiling was reached; `signal` = an external signal killed the
155
+ * child (any signal, one semantic — never the SIGTERM literal). */
156
+ export type TerminationCause = "stalled" | "over-budget" | "signal";
157
+
158
+ /** The stall judge's verdict per sample tick: `progress` (a leg advanced), `unknown`
159
+ * (a leg is unreadable — the fail-open state, never a kill), `idled` (no progress
160
+ * yet, the idle window is open) and `stalled` (no progress and the window is spent
161
+ * — the kill). */
162
+ export type StallVerdict = "progress" | "unknown" | "idled" | "stalled";
163
+
164
+ /** One sample tick's two legs — the process group's cumulative CPU (ms) and the
165
+ * newest mtime (ms) of the scanned tree. `null` = that leg is unreadable (the
166
+ * fail-open face: an unreadable leg never authorizes a kill). The field names are
167
+ * the heartbeat record's names (one naming, two references). */
168
+ export interface Sample {
169
+ groupCpuMs: number | null;
170
+ newestMtimeMs: number | null;
171
+ }
172
+
173
+ /** The recorded sample — a `Sample` extended with its tick's timestamp and the
174
+ * judge's verdict (the heartbeat file's field set; the crash record embeds it). */
175
+ export interface SampleRecord extends Sample {
176
+ sampledAt: number;
177
+ verdict: StallVerdict;
178
+ }
179
+
149
180
  /** The lane-crash cause vocabulary — postmortem classification of why a dispatch
150
181
  * terminated before the exit gate (zero behavior fork: resume never routes on it).
151
- * `contract-violation` is the read-back face: the child exited 0 but produced no
152
- * draft or a schema-violating one (the engine BLOCKs + preserves the draft + stores
153
- * the same-command resume — the read-back rejection's crash record). */
154
- export type CrashCause =
155
- | "child-exit"
156
- | "child-signal"
157
- | "engine-over-budget"
158
- | "engine-timeout"
159
- | "contract-violation"
160
- | "unknown";
182
+ * The termination causes cover the round that was cut short; `child-exit` is the
183
+ * child's own non-zero exit, `contract-violation` the read-back face (the child
184
+ * exited 0 but produced no draft or a schema-violating one — the engine BLOCKs +
185
+ * preserves the draft + stores the same-command resume), and `unknown` the
186
+ * unattributable termination fallback. */
187
+ export type CrashCause = TerminationCause | "child-exit" | "contract-violation" | "unknown";
161
188
 
162
189
  /** The crash record — the lane crash's recovery record (`crash-<lane>-<round>.json`):
163
190
  * the same-command resume's decision source (the resume command + the dead child's
164
191
  * tails), never the handoff carrier. */
165
192
  export interface CrashRecord {
166
- /** The dead child's exit code (1 = run failure, 143 = SIGTERM — the shell convention). */
167
- exitCode: number;
168
- /** The last CRASH_TAIL_LINES stderr lines (the "403 / abort without trace" tail). */
193
+ /** The dead child's exit code — null when the child never spawned (a broken
194
+ * command) or was terminated by a signal (a signalled child has no exit code;
195
+ * the signal semantics ride the `cause`). */
196
+ exitCode: number | null;
197
+ /** The dead child's stderr tail (the "403 / abort without trace" tail — the
198
+ * caller's captured lines, no fixed tail-length constant). */
169
199
  stderrTail: readonly string[];
170
- /** The last CRASH_TAIL_LINES stdout lines. */
200
+ /** The dead child's stdout tail. */
171
201
  stdoutTail: readonly string[];
172
202
  /** The handoff path the dead child was expected to write (null when the lane carries none). */
173
203
  attemptedHandoff: string | null;
@@ -175,6 +205,11 @@ export interface CrashRecord {
175
205
  next: string;
176
206
  /** The unified termination cause — postmortem, zero behavior fork. */
177
207
  cause: CrashCause;
208
+ /** The terminated round's last observed sample (the stall face's postmortem pair) —
209
+ * null when the round was not cut short or no sample was ever taken. The sample
210
+ * rides the termination fact in memory (zero re-read of the heartbeat file the
211
+ * engine itself wrote); the on-disk heartbeat stays for a human's postmortem. */
212
+ lastSample: SampleRecord | null;
178
213
  }
179
214
 
180
215
  // ---------------------------------------------------------------------------
@@ -338,6 +373,28 @@ export class Ledger {
338
373
  return this.#refs;
339
374
  }
340
375
 
376
+ /** The ledger's repo-basis value object — the ONE conversion exit every persisted
377
+ * path field normalizes through (T1 `RepoRoot` · P9 T4 §2.7). The basis is the
378
+ * workspace root's OWN value object (built once at the root's boundary) — never
379
+ * re-wrapped here (branch-review-1 F2: one basis, one form). */
380
+ #basis(): RepoRoot {
381
+ return this.#workspace.root.basis;
382
+ }
383
+
384
+ /** Normalize a path value to the canonical repoRoot-relative `RepoPath` — the
385
+ * comparison/write side of the shapes fix (a persisted relative value and an
386
+ * incoming absolute argv value compare on ONE basis). */
387
+ #rel(value: string): RepoPath {
388
+ return this.#basis().relativize(value);
389
+ }
390
+
391
+ /** Erase a (possibly relative) path value to the absolute syscall string for a
392
+ * read (a legacy relative persisted value resolves against the basis, never
393
+ * `process.cwd()`). */
394
+ #abs(value: string): string {
395
+ return this.#basis().resolve(this.#basis().relativize(value));
396
+ }
397
+
341
398
  // ---- the single author's write/read primitives ----
342
399
 
343
400
  /** Persist a JSON artifact — the ledger's single write point (engine sole author). */
@@ -468,8 +525,10 @@ export class Ledger {
468
525
  #briefRevision(waveKey: string, planPath: string): BriefRevisionRef | null {
469
526
  try {
470
527
  const tasks = waveKey.split(",").map((part) => Number(part));
471
- const brief = this.#brief.render(readFileSync(planPath, "utf8"), tasks);
472
- return this.#refs.briefRevision(planPath, brief);
528
+ // The plan layer is stored repoRoot-relative (P9 T4 §2.7) — one basis with
529
+ // every persisted path field; the read erases to absolute at the syscall edge.
530
+ const brief = this.#brief.render(readFileSync(this.#abs(planPath), "utf8"), tasks);
531
+ return this.#refs.briefRevision(this.#rel(planPath), brief);
473
532
  } catch {
474
533
  return null;
475
534
  }
@@ -504,7 +563,11 @@ export class Ledger {
504
563
  const reviewed = this.reviewedDocRevisionOf(key);
505
564
  if (reviewed === null) return null;
506
565
  try {
507
- const current = this.#refs.docRevision(doc, readFileSync(doc, "utf8"));
566
+ // Both sides on ONE basis (P9 T4 §2.7): the recorded ref is repoRoot-relative;
567
+ // the incoming target (an absolute argv-erasure) is relativized here so the
568
+ // false-drift comparison never reads one document as two.
569
+ const rel = this.#rel(doc);
570
+ const current = this.#refs.docRevision(rel, readFileSync(this.#abs(doc), "utf8"));
508
571
  return this.#refs.sameRef(reviewed, current) ? "same" : "drift";
509
572
  } catch {
510
573
  return null;
@@ -585,7 +648,7 @@ export class Ledger {
585
648
  if (reviewed !== null && this.#briefDrift(waveKey, reviewed)) return { kind: "review" };
586
649
  return {
587
650
  kind: "fix",
588
- findings: this.handoffPath("review", "wave", { tasks: waveKey, round: latestReview }),
651
+ reviews: this.handoffPath("review", "wave", { tasks: waveKey, round: latestReview }),
589
652
  };
590
653
  }
591
654
  return null;
@@ -647,6 +710,15 @@ export class Ledger {
647
710
  return this.readProgress()?.[key] ?? 0;
648
711
  }
649
712
 
713
+ /** Increment the timeout counter — the terminated-round write point (one TIMEOUT
714
+ * round lands, the count goes up by one). The counter's only writer. */
715
+ incrementTimeoutCount(): number {
716
+ const data = this.readProgress() ?? this.emptyProgress();
717
+ data.timeoutCount += 1;
718
+ this.writeProgress(data);
719
+ return data.timeoutCount;
720
+ }
721
+
650
722
  // -------------------------------------------------------------------------
651
723
  // closedWaves — the closure single read face (v1.20)
652
724
  // -------------------------------------------------------------------------
@@ -944,7 +1016,7 @@ export class Ledger {
944
1016
  * a rejected child's leftover draft is never read back as a completed round
945
1017
  * (the §2.8 gate; without it a BLOCKED round with a stale draft rendered a
946
1018
  * contradictory `status: BLOCKED · next: done`). A fix round carries the SOURCE
947
- * review's findings (C5-1: the `--findings` input content, never its own
1019
+ * review's findings (C5-1: the `--reviews` input content, never its own
948
1020
  * carrier); the consecutive-S1 run is walked from the review history.
949
1021
  * Missing/corrupt evaluated handoff → null too — a fix round whose source review
950
1022
  * is unreadable is never a zero-findings fabrication: a round whose blocker set
@@ -977,7 +1049,7 @@ export class Ledger {
977
1049
  // shared with the fix leg below (`HandoffSchema.conclusionOf`).
978
1050
  status: this.#handoffSchema.conclusionOf("findings", carrier),
979
1051
  findings: this.#findingsOf(carrier),
980
- findingsPath: this.handoffPath("review", type, reviewParams),
1052
+ reviewsPath: this.handoffPath("review", type, reviewParams),
981
1053
  consecutiveS1: this.#consecutiveS1Run(type, params, round),
982
1054
  };
983
1055
  }
@@ -997,7 +1069,7 @@ export class Ledger {
997
1069
  // the same `conclusionOf` single source (D27).
998
1070
  status: this.#handoffSchema.conclusionOf(this.handoffFaceOf("fix", type), fixCarrier),
999
1071
  findings: this.#findingsOf(reviewCarrier),
1000
- findingsPath: this.handoffPath("review", type, reviewParams),
1072
+ reviewsPath: this.handoffPath("review", type, reviewParams),
1001
1073
  consecutiveS1: this.#consecutiveS1Run(type, params, round),
1002
1074
  };
1003
1075
  }
@@ -35,6 +35,7 @@
35
35
  // Module-level exports are types / constants / the class — zero behavior-carrying
36
36
  // bare functions (the plan's zero-bare-function discipline).
37
37
 
38
+ import type { RouteTarget } from "./faces.ts";
38
39
  import type { Round } from "./ledger.ts";
39
40
  import type { ExecutionState } from "./state.ts";
40
41
 
@@ -48,8 +49,8 @@ export type Route =
48
49
  | { kind: "next-wave"; tasks: string }
49
50
  /** a review hop — a review judges the live tree, carrying no commit identity. */
50
51
  | { kind: "review" }
51
- /** the one-way fix hop — findingsPath = the review handoff the fix reads (`--findings`). */
52
- | { kind: "fix"; findings?: string }
52
+ /** the one-way fix hop — reviewsPath = the review handoff the fix reads (`--reviews`). */
53
+ | { kind: "fix"; reviews?: string }
53
54
  /** the review-cycle soft cap — the suggestion defers to user adjudication. */
54
55
  | { kind: "soft-cap"; message: string }
55
56
  /** the face-to-face handoff (D40) — the line's C5 frontier exhausted, so the next
@@ -59,8 +60,16 @@ export type Route =
59
60
 
60
61
  /** The review-cycle soft cap — the consecutive-S1 run length at which the fix face
61
62
  * defers the next hop to user adjudication (soft by nature: a default suggestion,
62
- * never a hard stop — the user / Plan Sole Writer override it). */
63
- export const REVIEW_CYCLE_CAP = 10;
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;
64
73
 
65
74
  // ---------------------------------------------------------------------------
66
75
  // the face indirection line — the pipeline's face-to-face `done` routing table (D33)
@@ -92,6 +101,42 @@ export const PIPELINE_NEXT: Readonly<Record<PipelineKey, PipelineEntry>> = {
92
101
  branch: { kind: "ref", ref: "kairos:cdd-close" },
93
102
  };
94
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
+
95
140
  /** The review-cycle soft-cap suggestion (the C5-0 suggestion face — user adjudicates). */
96
141
  export const SOFT_CAP_SUGGESTION = "BLOCKED: review-cycle-cap — user adjudicates";
97
142
 
@@ -108,8 +153,11 @@ export const FIX_READBACK_SUFFIX =
108
153
  "(confirm the findings · if a finding needs a ruling, record the ruling in the findings file)";
109
154
 
110
155
  /** The failure face — a BLOCKED/TIMEOUT round goes the stderr CDD_BLOCKED channel and
111
- * produces no `next:` line on any op. */
112
- const FAILED_STATUS = new Set(["BLOCKED", "TIMEOUT"]);
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"]);
113
161
 
114
162
  /**
115
163
  * NextStepRouter — the C5 decision table as one instance method. The router keeps
@@ -131,7 +179,7 @@ export class NextStepRouter {
131
179
  // One-way: any findings (any severity) → the fix round — a review never previews
132
180
  // what the fix will do (C5-1). Zero findings (approved) → the unified closure: the
133
181
  // ready batch decides whether the next wave continues or the run is exhausted.
134
- if (ref.findings.length > 0) return { kind: "fix", findings: ref.findingsPath };
182
+ if (ref.findings.length > 0) return { kind: "fix", reviews: ref.reviewsPath };
135
183
  return this.#close(state);
136
184
  case "fix": {
137
185
  // C5-1: the fix face is the re-review / closure decision point. The soft cap
@@ -152,7 +200,7 @@ export class NextStepRouter {
152
200
  // The branch terminal face — findings route the fix; zero findings close the line
153
201
  // through the same unified closure terminal.
154
202
  return ref.findings.length > 0
155
- ? { kind: "fix", findings: ref.findingsPath }
203
+ ? { kind: "fix", reviews: ref.reviewsPath }
156
204
  : this.#close(state);
157
205
  }
158
206
  }
@@ -178,15 +226,68 @@ export class NextStepRouter {
178
226
  return { kind: "handoff", entry: PIPELINE_NEXT[key] };
179
227
  }
180
228
 
181
- /** Resolve a line's next step (D40) — the single "one line → next" point shared by
182
- * the board (its per-line walk) and the capsule (the round's own line). An ACTIVE
183
- * C5 hop (`review` / `fix` / `implement` / `next-wave` / `soft-cap`) passes through
184
- * as the line's next step; a drained or not-yet-started line (the C5 `done` / no
185
- * active round) yields the face-to-face handoff carrying the pipeline entry. A null
186
- * doc-class (no face seam — the overall line / a bare terminal) rerenders the bare
187
- * `done` word. Pure — the callers hold their own line facts. */
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. */
188
236
  static resolve(active: Route | null, key: PipelineKey | null): Route {
189
237
  if (active !== null && active.kind !== "done") return active;
190
238
  return key === null ? { kind: "done" } : NextStepRouter.handoff(key);
191
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
+ }
192
293
  }
@@ -24,11 +24,13 @@
24
24
 
25
25
  import { existsSync, readdirSync, readFileSync } from "node:fs";
26
26
  import { PlanDocType } from "../contract/doc.ts";
27
+ import { FrontMatterExtractor } from "../contract/frontmatter.ts";
27
28
  import type { DocFs } from "../contract/invariants.ts";
28
29
  import type { Contract } from "../contract/judge.ts";
29
30
  import type { DocKey } from "../contract/project.ts";
30
31
  import type { Words } from "../face/words.ts";
31
32
  import type { GitClient } from "../infra/git.ts";
33
+ import { type RepoPath, RepoRoot } from "../infra/root.ts";
32
34
  import type { TargetType } from "./faces.ts";
33
35
  import { TaskGraph } from "./graph.ts";
34
36
  import type { Ledger } from "./ledger.ts";
@@ -60,14 +62,19 @@ export interface PreFlightVerdict {
60
62
 
61
63
  /** The doc-contract target of a spec/plan dispatch. */
62
64
  export interface PreFlightDoc {
63
- /** The target doc type's registry key — read from the doc's `- **Doc type**:`
64
- * header declaration (spec §12 · D34; both the spec and the plan faces key by
65
- * the declaration, zero command-type carve-out).
66
- * null when a present doc carries no declaration — the seam BLOCKs (zero
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
67
69
  * filename-suffix fallback, one declaration reading face `BoardView.readDocType`). */
68
70
  docKey: DocKey | null;
69
- /** The target doc's path (the lifecycle's audit path). */
70
- path: string;
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;
71
78
  }
72
79
 
73
80
  /** One dispatch's pre-flight inputs — the facts the seam judges. */
@@ -177,13 +184,37 @@ export class PreFlight {
177
184
  // Contract.validate (the interpreter's single judgment entry) before its
178
185
  // review/fix round dispatches. An unreadable doc carries no judgment (no
179
186
  // fabricated findings from an absent surface). A PRESENT doc carrying no
180
- // `- **Doc type**:` declaration BLOCKs (spec §12 · D34: the declared type is
187
+ // `doc-type:` key BLOCKs (spec §12 · D34: the declared type is
181
188
  // the one reading face, zero filename-suffix fallback).
182
189
  if (ctx.type === "spec" || ctx.type === "plan") {
183
190
  gates.push("doc-contract");
184
191
  const doc = ctx.doc;
185
- const content = doc === null ? null : this.#fs.read(doc.path);
186
- if (content !== null && doc !== null) {
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
+ }
187
218
  if (doc.docKey === null) {
188
219
  return {
189
220
  ok: false,
@@ -195,7 +226,7 @@ export class PreFlight {
195
226
  }
196
227
  const findings = this.#contract.validate({
197
228
  docKey: doc.docKey,
198
- path: doc.path,
229
+ path: docAbsolute,
199
230
  content,
200
231
  root: ctx.repoRoot,
201
232
  fs: this.#fs,
@@ -0,0 +1,84 @@
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
+ }