@oscaner-skills/cdd-engine 4.3.0 → 4.4.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.
package/README.md CHANGED
@@ -33,7 +33,7 @@ Global option: `--dry-run` — preview the next dispatch step and the artifacts
33
33
  | `schema` | `cdd schema get <type>` | Print the canonical doc-structure schema (discovery-only, zero enforcement) |
34
34
  | `issue` | `cdd issue render` | Render an aggregate issue body from stdin findings (pure rendering, zero enforcement) |
35
35
  | `board` | `cdd board --plan <path> / --spec <path>` | Render the entry document's progress board (overall/phase-spec/single-spec/plan/wave/branch; pure read, zero enforcement) |
36
- | `init` | `cdd init --harness=<claude\|pi> [--update]` | Install or update the kairos plugin set for a harness (repo-independent, streams inherited) |
36
+ | `init` | `cdd init --harness=<claude\|pi> [--update] [--include-recommends]` | Install or update the kairos plugin set for a harness (repo-independent, streams inherited) |
37
37
 
38
38
  Use `cdd <command> --help` for a command's full option list (for example `cdd review --tasks` / `--spec` / `--plan` / `--round`).
39
39
 
@@ -88,4 +88,4 @@ During repository development the engine is invoked straight on the source entry
88
88
 
89
89
  ## License
90
90
 
91
- MIT
91
+ MIT
package/README.zh-CN.md CHANGED
@@ -35,7 +35,7 @@ npm install @oscaner-skills/cdd-engine
35
35
  | `schema` | `cdd schema get <type>` | 打印 canonical 文档结构 schema(发现型、零执法) |
36
36
  | `issue` | `cdd issue render` | 依据 stdin 发现渲染聚合 issue 正文(纯渲染、零执法) |
37
37
  | `board` | `cdd board --plan <path> / --spec <path>` | 渲染入口文档的进度板(overall/phase-spec/single-spec/plan/wave/branch;纯读、零执法) |
38
- | `init` | `cdd init --harness=<claude\|pi> [--update]` | 为指定 harness 安装或更新 kairos 插件集(与 repo 无关,三流继承) |
38
+ | `init` | `cdd init --harness=<claude\|pi> [--update] [--include-recommends]` | 为指定 harness 安装或更新 kairos 插件集(与 repo 无关,三流继承) |
39
39
 
40
40
  用 `cdd <command> --help` 查看某命令的完整选项列表(例如 `cdd review --tasks` / `--spec` / `--plan` / `--round`)。
41
41
 
@@ -9,23 +9,28 @@
9
9
  //
10
10
  // This module carries the header `{version, status, docType}` read, the per-node
11
11
  // progress projection, the render face (the phase/program board layouts) and the
12
- // pipeline OBSERVATION (`#pipelineFacts`). The doc type is the DECLARED fact — the
12
+ // pipeline OBSERVATION (`pipelineFacts`). The doc type is the DECLARED fact — the
13
13
  // front-matter `doc-type:` head key (spec §12 · D34) — never a filename-suffix
14
14
  // derivation; an absent key reads null and the consumer blocks (zero dual-read
15
15
  // fallback).
16
16
  //
17
17
  // P22 §5.2 — the board's `next:` line renders an INJECTED `NextHop` and judges
18
- // nothing: the pipeline traversal (the four face-order rules) lives on the
19
- // assembly face (`face/cli.ts`), the ONE derivation is `NextStepRouter#nextHop`,
20
- // and the ONE literal renderer is `RouteRenderer` (shared with the capsule). The
21
- // board only OBSERVES each face's facts (`#pipelineFacts`) and renders.
18
+ // nothing: the pipeline traversal (the four face-order rules) lives in the session
19
+ // plane (`session/pipeline.ts` `PipelineFrontier`), the ONE derivation is
20
+ // `NextStepRouter#nextHop`, and the ONE literal renderer is `RouteRenderer` (shared
21
+ // with the capsule). The board only OBSERVES each face's facts (`pipelineFacts`)
22
+ // and renders.
22
23
  //
23
- // P22 §5.3 — the default layout aggregates each line's rounds BY VERB into
24
- // `{label} {count}{attempt} {mark}` tokens (the judgement glyph is mandatory, the
25
- // findings count rides a `+N` suffix, a re-dispatch carries its `a{attempt}`
26
- // superscript); range forms never render (there is no `--verbose` in this phase).
27
- // Each wave line's label carries the wave's task scope in braces (`W1 {5,11}`)
28
- // with the ✔/▶/○ marker column fixed-width aligned.
24
+ // P22 §5.3 — the default layout aggregates each line's rounds BY VERB (the judgement
25
+ // glyph is mandatory, the findings count rides a `+N` suffix, a plain token carries the
26
+ // last record's `a{attempt}` superscript); range forms never render (there is no
27
+ // `--verbose` in this phase). P24 §12 splits that aggregation into two shapes: the
28
+ // success face merges per verb — an `{ok}/{attempts}` ratio with NO superscript once
29
+ // the verb has a failed attempt — and the anomaly face expands one token per failed
30
+ // attempt, each naming its own cycle and, past the first, its own `a{attempt}`
31
+ // (`fix 12 ✗→✓` when that cycle's next attempt completed). Each wave line's label
32
+ // carries the wave's task scope in braces (`W1 {5,11}`) with the ✔/▶/○ marker
33
+ // column fixed-width aligned.
29
34
  //
30
35
  // Module-level exports are types / constants / the classes — zero behavior-carrying
31
36
  // bare functions (the plan's zero-bare-function discipline).
@@ -41,7 +46,7 @@ import { SlugIndex } from "../infra/slug-index.js";
41
46
  import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
42
47
  import { TaskGraph } from "../session/graph.js";
43
48
  import { Ledger, RoundRecords } from "../session/ledger.js";
44
- import { NextStepRouter, PIPELINE_FACES, PIPELINE_NEXT, } from "../session/next.js";
49
+ import { PipelineFrontier } from "../session/pipeline.js";
45
50
  import { PROGRESS_LEGEND, PROGRESS_MARKERS } from "./graph-view.js";
46
51
  import { RouteRenderer } from "./route-render.js";
47
52
  /** The verb render order of a line's rounds tokens — the stable display order the
@@ -50,7 +55,7 @@ import { RouteRenderer } from "./route-render.js";
50
55
  const VERB_ORDER = ["implement", "review", "branch-review", "fix"];
51
56
  /** The judgement glyphs of one aggregated token (spec §5.3 — the mark is MANDATORY:
52
57
  * `✓` a completed round, `✗` a round that failed its target action). */
53
- const JUDGEMENT_MARKERS = { passed: "✓", failed: "✗" };
58
+ const JUDGEMENT_MARKERS = { passed: "✓", failed: "✗", recovered: "✗→✓" };
54
59
  /** The DocKey domain of the `doc-type:` declaration — the declared value must
55
60
  * be one of the four keys; anything else reads null (present facts, never a
56
61
  * fabricated type). Derived from the ONE DocKey declaration (contract/project.ts
@@ -194,34 +199,69 @@ export class BoardView {
194
199
  marker: null,
195
200
  };
196
201
  }
197
- /** summaryCell(records) — the line's aggregated rounds cell (spec §5.3): one token
198
- * per verb × judgement run (`{label} {count}{attempt} {mark}`), joined by ` · `.
199
- * The count is the run's round count, the attempt superscript belongs to the run's
200
- * LAST record (a re-dispatch: `fix 1 ✗ · fix 1a2 ✓`), the mark is the run's verdict
201
- * (`✓` completed / `✗` failed — never omitted), and the run's graded findings ride
202
- * the `+N` suffix (omitted at 0). The range form (`review 1–10 ✓`) never renders:
203
- * the aggregation IS the count. */
202
+ /** summaryCell(records) — the line's aggregated rounds cell (P24 §12): the SUCCESS
203
+ * face of each verb merges into at most one token (never rendered at zero successes),
204
+ * the ANOMALY face expands one token per failed attempt. Tokens are verb-major in
205
+ * `VERB_ORDER`, a verb's success token before its failures, those in stored order. The
206
+ * range form (`review 1–10 ✓`) never renders: the aggregation IS the count. */
204
207
  static summaryCell(records) {
205
208
  const tokens = [];
206
209
  const extra = [...new Set(records.map((record) => record.op))].filter((op) => !VERB_ORDER.includes(op));
207
210
  for (const verb of [...VERB_ORDER, ...extra]) {
208
- const ofVerb = records.filter((record) => record.op === verb);
209
- for (const run of BoardView.#judgementRuns(ofVerb)) {
210
- tokens.push(BoardView.#summaryToken(verb, run));
211
- }
211
+ const faces = BoardView.#judgementRuns(records.filter((record) => record.op === verb));
212
+ tokens.push(...BoardView.#verbTokens(verb, faces));
212
213
  }
213
214
  return tokens.join(" · ");
214
215
  }
215
- /** One aggregated token of a verb × judgement run. The `+N` suffix counts the
216
- * run's graded FINDINGS, read from each round's own carrier (`carrierPath` → the
217
- * handoff's `findings` array, spec §5.3) — never the round's hard/soft contract
218
- * violations, which are a different fact. A record with no carrier (a legacy row,
219
- * or a work-plane round whose carrier declares no findings) contributes zero. */
220
- static #summaryToken(verb, run) {
221
- const mark = run[0].verdict.targetAction ? JUDGEMENT_MARKERS.passed : JUDGEMENT_MARKERS.failed;
216
+ /** One verb's tokens — its success token (absent at zero successes) followed by one
217
+ * token per failed attempt, so a failure never drifts to the line's tail (P24 §12). */
218
+ static #verbTokens(verb, faces) {
219
+ const tokens = [];
220
+ const success = BoardView.#successToken(verb, faces);
221
+ if (success !== null)
222
+ tokens.push(success);
223
+ for (const record of faces.failures) {
224
+ tokens.push(BoardView.#failureToken(verb, record, faces.successes));
225
+ }
226
+ return tokens;
227
+ }
228
+ /** One verb's success token — absent when no round of the verb succeeded (a
229
+ * failure-only verb renders its `✗` tokens alone), the plain count plus the LAST
230
+ * success's attempt superscript when the verb has no failed attempt, and the
231
+ * `{succeeded}/{attempts}` ratio — never a superscript — once it has one (P24 §12).
232
+ * Its `+N` counts the SUCCESS records' carriers alone; a failed attempt's findings
233
+ * already ride that attempt's own token. */
234
+ static #successToken(verb, faces) {
235
+ const count = faces.successes.length;
236
+ if (count === 0)
237
+ return null;
238
+ const last = faces.successes[count - 1];
239
+ const body = faces.failures.length === 0
240
+ ? `${count}${BoardView.attemptSuffix(last)}`
241
+ : `${count}/${count + faces.failures.length}`;
242
+ return BoardView.#summaryToken(verb, body, JUDGEMENT_MARKERS.passed, faces.successes);
243
+ }
244
+ /** One failed attempt's token — `{verb} {cycle}{aN} ✗{+N}`, the cycle naming the round
245
+ * that failed rather than a re-counted segment, and `✗→✓` when the SAME cycle's next
246
+ * attempt (`attempt + 1`) completed: recovery reads exactly that one edge — a later
247
+ * cycle's success and a further same-cycle attempt are historical failures. The `+N`
248
+ * counts this record's own carrier alone, never erased by a later success (P24 §12). */
249
+ static #failureToken(verb, record, successes) {
250
+ const recovered = successes.some((other) => other.cycle === record.cycle && other.attempt === record.attempt + 1);
251
+ const mark = recovered ? JUDGEMENT_MARKERS.recovered : JUDGEMENT_MARKERS.failed;
252
+ const body = `${record.cycle}${BoardView.attemptSuffix(record)}`;
253
+ return BoardView.#summaryToken(verb, body, mark, [record]);
254
+ }
255
+ /** One token of a verb's success face or of one failed attempt, `{verb} {body} {mark}`
256
+ * (P24 §12). The `+N` suffix counts the run's graded FINDINGS, read from each round's
257
+ * own carrier (`carrierPath` → the handoff's `findings` array, spec §5.3) — never the
258
+ * round's hard/soft contract violations, which are a different fact. A record with no
259
+ * carrier (a legacy row, or a work-plane round whose carrier declares no findings)
260
+ * contributes zero. */
261
+ static #summaryToken(verb, body, mark, run) {
222
262
  const findings = run.reduce((total, record) => total + BoardView.#findingsCountOf(record), 0);
223
263
  const suffix = findings === 0 ? "" : `+${findings}`;
224
- return `${verb} ${run.length}${BoardView.attemptSuffix(run[run.length - 1])} ${mark}${suffix}`;
264
+ return `${verb} ${body} ${mark}${suffix}`;
225
265
  }
226
266
  /** One round's findings count — the `findings` array length of the carrier the round
227
267
  * persisted (the judge plane's declared field). Zero when the record carries no
@@ -248,21 +288,14 @@ export class BoardView {
248
288
  static attemptSuffix(record) {
249
289
  return record.attempt === 1 ? "" : `a${record.attempt}`;
250
290
  }
251
- /** The judgement runs of one verb — contiguous records sharing a verdict, in the
252
- * stored (chronological) order, so a re-dispatch's `✗ → ✓` pair renders as two
253
- * tokens and an unbroken green history collapses into one (spec §5.3). */
291
+ /** The judgement faces of one verb — the success face and the anomaly face, each in
292
+ * the stored (chronological) order: successes merge into ONE token per verb while
293
+ * failed attempts expand one token each (P24 §12). */
254
294
  static #judgementRuns(records) {
255
- const runs = [];
256
- for (const record of records) {
257
- const last = runs[runs.length - 1];
258
- if (last !== undefined && last[0].verdict.targetAction === record.verdict.targetAction) {
259
- last.push(record);
260
- }
261
- else {
262
- runs.push([record]);
263
- }
264
- }
265
- return runs;
295
+ return {
296
+ successes: records.filter((record) => record.verdict.targetAction),
297
+ failures: records.filter((record) => !record.verdict.targetAction),
298
+ };
266
299
  }
267
300
  /** nextLine(hop, renderer) — the board's `next:` row rendered from the INJECTED
268
301
  * hop through the shared hop renderer (`RouteRenderer#renderHop`), so the board's
@@ -274,6 +307,17 @@ export class BoardView {
274
307
  const value = renderer.renderHop(hop) ?? "(none)";
275
308
  return ` next: ${value}`;
276
309
  }
310
+ /** reasonLine(hop) — the board's `reason:` row under `next:`: the hop's OWN named
311
+ * fact (`NextHop.reason`), the same field the capsule's `renderReason` row prints,
312
+ * so the two faces state one value by construction. The PREFIX is this face's own
313
+ * layout literal (` reason: ` — the same 11-column shape `nextLine` uses); the
314
+ * capsule takes its prefix from the word table instead, so each face keeps its own
315
+ * prefix and only the token is shared. A row exists only for an existing hop: the
316
+ * absent hop renders ` next: (none)` and NO reason row at all (the caller's
317
+ * null-next branch), never a half-built one. */
318
+ static reasonLine(hop) {
319
+ return ` reason: ${hop.reason}`;
320
+ }
277
321
  /** inFlightRows(state, orphans, words) — the tree's dispatch fact + the
278
322
  * workspace's orphan handoff drafts, as board lines. The held row names the
279
323
  * holder's IDENTITY facts alone (the operating verb, the round's cycle + attempt
@@ -426,7 +470,9 @@ export class BoardView {
426
470
  lines.push(" next: (none)");
427
471
  }
428
472
  else {
429
- lines.push(BoardView.nextLine(next, new RouteRenderer(words, channels, host, root)));
473
+ const renderer = new RouteRenderer(words, channels, host, root);
474
+ lines.push(BoardView.nextLine(next, renderer));
475
+ lines.push(BoardView.reasonLine(next));
430
476
  }
431
477
  return blocked ? 2 : 0;
432
478
  }
@@ -531,78 +577,34 @@ export class BoardView {
531
577
  const root = new WorkspaceRoot(repoRoot, ENGINE_RUNTIME.handoffNamespace.workspaceRoot);
532
578
  return new Ledger(new Workspace(root, nodeSlug), new ConfigLoader());
533
579
  }
534
- /** pipelineFacts(index, entry, root) — the board's per-face OBSERVATION of the
535
- * pipeline (spec §5.2): each face's closed fact, its ACTIVE C5 hop (the SAME
536
- * state→next chain the dispatch engine walks — `Ledger#lineRoute` for the
537
- * doc/branch lines, the plan frontier + `Ledger#waveLineRoute` for the wave line)
538
- * and its render target, keyed by the ONE `PIPELINE_FACES` key set. The board
539
- * reports facts; the traversal (the four face-order rules) and the ONE hop
540
- * derivation belong to the assembly face. Null when the node holds no legal slug
541
- * (no workspace to observe). */
580
+ /** pipelineFacts(index, entry, root) — the board's FACTS about the pipeline (spec
581
+ * §5.2): the node's ledger and the pipeline frontier's declared input (the spec
582
+ * word and path, the plan path, the guarded plan read). The board reports facts
583
+ * only — the per-face observations and the four face-order rules live in the
584
+ * session plane's `PipelineFrontier`. Null when the node holds no legal slug (no
585
+ * workspace to observe). */
542
586
  static pipelineFacts(index, entry, root) {
543
587
  const nodeSlug = BoardView.#validSlug(entry);
544
588
  if (nodeSlug === null)
545
589
  return null;
546
590
  const ledger = BoardView.#ledgerOf(nodeSlug, root.absolute);
547
591
  const sources = BoardView.#nodeSources(index, entry);
548
- const progress = ledger.readProgress();
549
- const waves = BoardView.#waveLines(sources.plan?.path ?? null, progress, ledger);
550
592
  const specPath = sources.spec?.path ?? null;
551
593
  const planPath = sources.plan?.path ?? null;
552
594
  // The identity line's OWN word — the document's DECLARED `doc-type:` — keys the
553
595
  // line and names the pipeline station (`single-spec` closes onto its `done` row).
554
596
  const specType = BoardView.#lineWordOf(sources.spec);
555
- // The plan's open frontier wave — the SAME ready batch the dispatch engine's
556
- // task-graph frontier yields (frontier over closedWaves()).
557
- const waveKey = BoardView.#waveFrontierKey(ledger, planPath);
558
- const report = {
559
- // The report KEY is the pipeline POSITION (the first face — `PIPELINE_FACES`);
560
- // the line's type/key/target cells are the declaration the document carries.
561
- "phase-spec": {
562
- closed: ledger.lineClosed(specType, specType),
563
- active: specPath === null ? null : ledger.lineRoute(specType, specType),
564
- target: specPath === null ? null : { type: specType, id: specPath },
565
- },
566
- plan: {
567
- closed: ledger.lineClosed("plan", "plan"),
568
- active: planPath === null ? null : ledger.lineRoute("plan", "plan"),
569
- target: planPath === null ? null : { type: "plan", id: planPath, plan: planPath },
570
- },
571
- wave: {
572
- // The wave face is exhausted (skipped) only when the plan yields a wave set
573
- // and every wave is done — an empty wave segment (no plan) is not an exhausted
574
- // face (nothing was closed), so it stays the frontier and hands off.
575
- closed: waves.length > 0 && waves.every((wave) => wave.marker === PROGRESS_MARKERS.done),
576
- active: waveKey === null ? null : ledger.waveLineRoute(waveKey),
577
- target: planPath === null ? null : { type: "wave", id: waveKey ?? "", plan: planPath },
578
- },
579
- branch: {
580
- // The branch line's closure is judged AT its identity document (the plan): a
581
- // plan revision past the one the completed branch review bound reopens the
582
- // face, so the mark above and this frontier cell read ONE judgment.
583
- closed: ledger.lineStateAt("branch", "branch", planPath) === "closed",
584
- active: ledger.lineRoute("branch", "branch"),
585
- target: { type: "branch", id: "branch", plan: planPath ?? undefined },
586
- },
597
+ return {
598
+ ledger,
599
+ input: { specType, specPath, planPath, planGraph: BoardView.planGraph(planPath) },
587
600
  };
588
- return { ledger, report };
589
- }
590
- /** The plan's open frontier wave key — the ready batch over the node's `closedWaves()`
591
- * set, the SAME derivation the dispatch engine's task-graph frontier walks (T26, the
592
- * wave-unitary model). Null when the plan is absent or no wave remains open — the wave
593
- * face then holds no active hop (a not-yet-started wave line hands off to the next face). */
594
- static #waveFrontierKey(ledger, planPath) {
595
- const graph = BoardView.#planGraph(planPath);
596
- if (graph === null)
597
- return null;
598
- const frontier = graph.frontier(ledger.closedWaves());
599
- return frontier.length === 0 ? null : frontier.join(",");
600
- }
601
- /** The plan's task graph — the ONE guarded plan read shared by the wave frontier
602
- * key and the wave segment (`readFileSync` throwing on an unreadable plan is
603
- * caught here: a null plan path or an unreadable/absent file yields null, honoring
604
- * the wave face's "degradation, never a throw" contract). */
605
- static #planGraph(planPath) {
601
+ }
602
+ /** The plan's task graph — the ONE guarded plan read behind the board's own wave
603
+ * segment. `readFileSync` throwing on an unreadable plan is caught here: a null
604
+ * plan path or an unreadable/absent file yields null, honoring the wave face's
605
+ * "degradation, never a throw" contract. The pipeline frontier itself reads no
606
+ * file — the composition root injects this read's result as its `planGraph` cell. */
607
+ static planGraph(planPath) {
606
608
  if (planPath === null)
607
609
  return null;
608
610
  try {
@@ -638,7 +640,7 @@ export class BoardView {
638
640
  * share — the same source GraphView renders from), the wave's own `progress.json`
639
641
  * row spread alongside. No plan → empty segment (degradation, never a throw). */
640
642
  static #waveLines(planPath, progress, ledger) {
641
- const graph = BoardView.#planGraph(planPath);
643
+ const graph = BoardView.planGraph(planPath);
642
644
  if (graph === null)
643
645
  return [];
644
646
  const report = graph.report(ledger === null ? new Set() : ledger.closedWaves());
@@ -663,14 +665,13 @@ export class BoardView {
663
665
  }
664
666
  }
665
667
  /**
666
- * BoardNext — the board's next-hop assembly face (P22 §5.2): the retired router
667
- * `walk`'s four face-order rules, re-homed at the board's CONSTRUCTION face. The
668
- * board (`BoardView`) only REPORTS each pipeline face's facts; `BoardNext` decides
669
- * the next pipeline step (iterating the ONE `PIPELINE_FACES` order imported from
670
- * the session plane, never a second order declaration) and hands the result to the
671
- * ONE derivation (`Ledger#nextHopOf` → `NextStepRouter#nextHop`), so the board's
672
- * `next:` and the capsule's `next:` render ONE object. The composition root's board
673
- * assembly point (`face/cli.ts` `#runBoard`) constructs it.
668
+ * BoardNext — the board's hop entry point (P22 §5.2 · P24 §11): the board (`BoardView`)
669
+ * REPORTS the pipeline facts, and the session plane's `PipelineFrontier` both decides
670
+ * the next pipeline step and ASSEMBLES the hop (`PipelineFrontier#hopOf`, the ONE
671
+ * assembly the capsule renders too), so the board's `next:` and the capsule's `next:`
672
+ * render one object by construction. This class fills no cell and makes no judgment:
673
+ * it hands the facts over and returns what the assembly answered. The composition
674
+ * root's board assembly point (`face/cli.ts` `#runBoard`) constructs it.
674
675
  */
675
676
  // biome-ignore lint/complexity/noStaticOnlyClass: the board's assembly fact surface — the zero-bare-function discipline admits no standalone functions here.
676
677
  export class BoardNext {
@@ -681,73 +682,12 @@ export class BoardNext {
681
682
  const facts = entry.docType === "overall" ? null : BoardView.pipelineFacts(index, entry, root);
682
683
  return facts === null ? null : BoardNext.#hopOf(facts, root);
683
684
  }
684
- /** The derivation's input face — the walked route + target, the ledger's own
685
- * round facts and the declaration-reading station discrimination. The
686
- * `verdict → face` assembly lives in the ONE derivation (`Ledger#nextHopOf`), so
687
- * this face fills facts only. */
685
+ /** The session plane's ONE assembly, called with the board's facts and the face
686
+ * plane's declaration-reading station port. The board contributes no cell of its
687
+ * own — the hop is whatever the assembly answers. */
688
688
  static #hopOf(facts, root) {
689
- const next = BoardNext.#pipeline(facts.report);
690
- const target = next.target;
691
- return facts.ledger.nextHopOf({
692
- type: target?.type ?? "branch",
693
- key: target?.type === "wave" ? target.id : (target?.type ?? "branch"),
694
- route: next.route,
695
- target,
696
- doc: target === null ? null : target.type === "branch" ? (target.plan ?? null) : target.id,
689
+ return new PipelineFrontier(facts.ledger).hopOf(facts.input, {
697
690
  docClassOf: (candidate) => BoardView.docClassOf(root, candidate),
698
691
  });
699
692
  }
700
- /** The pipeline's face-to-face traversal (D40 · P22 §5.2) — the four face-order
701
- * rules over the ONE `PIPELINE_FACES` order the caller REPORTS facts against:
702
- * · the FRONTIER face (first not-closed) with an active C5 hop renders that hop
703
- * (the in-flight work — `review` / `fix` / `implement` / `next-wave`);
704
- * · the frontier has no active hop but IS entered (a target is present) → its
705
- * OWN pipeline exit entry;
706
- * · the frontier is NOT entered (no target — an absent doc) → the transition
707
- * INTO it: the PRECEDING entered face's exit entry (a just-closed spec hands
708
- * off to `cdd-plan`, never the absent plan's `cdd-dev`); none preceding → the
709
- * FIRST face's exit entry;
710
- * · every face closed → the LAST entered face's exit entry (the terminus —
711
- * `cdd-close` for a phase slug).
712
- * The order stays `PIPELINE_FACES`' (imported, never re-declared here). */
713
- static #pipeline(report) {
714
- const states = PIPELINE_FACES.map((key) => report[key]);
715
- const frontierIndex = states.findIndex((face) => !face.closed);
716
- if (frontierIndex === -1) {
717
- const terminalIndex = BoardNext.#lastEnteredIndex(states);
718
- const terminal = terminalIndex === -1 ? null : states[terminalIndex];
719
- return terminal === null
720
- ? { route: { kind: "done" }, target: null }
721
- : { route: BoardNext.#exitRoute(terminalIndex, terminal), target: terminal.target };
722
- }
723
- const frontier = states[frontierIndex];
724
- if (frontier.active !== null)
725
- return { route: frontier.active, target: frontier.target };
726
- const anchorIndex = frontier.target !== null
727
- ? frontierIndex
728
- : Math.max(0, BoardNext.#lastEnteredIndex(states.slice(0, frontierIndex)));
729
- const anchor = states[anchorIndex];
730
- return { route: BoardNext.#exitRoute(anchorIndex, anchor), target: anchor.target };
731
- }
732
- /** The anchor face's OWN pipeline exit — the row its render TARGET declares
733
- * (`PIPELINE_NEXT[target.type]`, the SAME one table the capsule's `done` face reads
734
- * through the ONE derivation). The identity face's target type IS the document's
735
- * declared word, so a `single-spec` closes onto its `done` row, never the phase-spec
736
- * line's `cdd-plan` ref; every node face's target type is its face key, so the lookup
737
- * is the face key there. A face with no target (never entered) falls back to its
738
- * pipeline face's row. */
739
- static #exitRoute(faceIndex, state) {
740
- if (state.target === null)
741
- return NextStepRouter.handoff(PIPELINE_FACES[faceIndex]);
742
- return { kind: "handoff", entry: PIPELINE_NEXT[state.target.type] };
743
- }
744
- /** The index of the last OBSERVED face carrying a render target — the last face the
745
- * pipeline has REACHED (a face with no target was never entered). -1 when none is. */
746
- static #lastEnteredIndex(states) {
747
- for (let i = states.length - 1; i >= 0; i--) {
748
- if (states[i].target !== null)
749
- return i;
750
- }
751
- return -1;
752
- }
753
693
  }
@@ -1,6 +1,7 @@
1
1
  // packages/cdd-engine/src-next/face/capsule.ts
2
- // T10 — the single capsule face (design spec §3.2: the `status · handoff · next:`
3
- // word-face steady state; P22 §10: the output face's closeout). Capsule#emit
2
+ // T10 — the single capsule face (design spec §3.2: the `status · handoff` + route
3
+ // word-face steady state; P22 §10: the output face's closeout). Both station anchors
4
+ // ride the word table (`next:` and the `reason:` row that follows it). Capsule#emit
4
5
  // renders the ALL-OP single stdout face — the capsule the orchestrator greps /
5
6
  // routes on without opening the handoff:
6
7
  //
@@ -8,6 +9,7 @@
8
9
  // status: <status> [· handoff: <crash>] (TIMEOUT / BLOCKED)
9
10
  // fixed N · rejected M (fix rounds only — between the status line and `next:`)
10
11
  // next: <suggestion> (optional — the C5 route / a caller-rendered text)
12
+ // reason: <token> (only after `next:` — the hop's named fact; no hop, no row)
11
13
  //
12
14
  // The `blocker` cell is retired: its whole information content — the blocker count —
13
15
  // is derivable from `status` (any blocker ⇒ CHANGES_REQUESTED, warn/nit-only ⇒
@@ -16,13 +18,15 @@
16
18
  // still the word table's single source (`Words.capsuleKeys(status, withHandoff)`) —
17
19
  // a failure status keeps the handoff cell only when the round wrote a crash record.
18
20
  // The fix round's disposition summary rides the SAME render, placed so the
19
- // dispatchable `next:` literal closes the output: `status` → summary → `next:`.
21
+ // dispatchable `next:` literal keeps its line: `status` → summary → `next:` →
22
+ // `reason:`.
20
23
  //
21
24
  // The byte face is v1-pinned: the key words (status · handoff) are pin-enforced by
22
25
  // the CapsuleKey type and the emit signature — a data-only change cannot reshape
23
26
  // them. What rides the injected Words table (the single word-table instance) is the
24
- // `·` separator, the `next:` station anchor and the route/status vocabulary — a
25
- // second table is excluded by construction. The `next:` value is
27
+ // `·` separator, the two route station anchors (`next:` and the `reason:` row that
28
+ // follows it) and the route/status vocabulary — a second table is excluded by
29
+ // construction. The `next:` value is
26
30
  // either a caller-rendered string or the C5 Route rendered through the route-word
27
31
  // table as a COMPLETE EXECUTABLE command (P4.1 T4 — the v1.39 semantic-literal
28
32
  // reversal): `implement --plan <path> --tasks 17` · `review --type phase-spec --spec
@@ -43,8 +47,8 @@
43
47
  // INJECTED `NextHop` — the ONE object every read face renders — and adds no
44
48
  // judgment of its own: the doc-class discrimination that picks the pipeline station
45
49
  // belongs to the derivation's injected seam (`BoardView.docClassOf`), never here.
46
- // A `NextHop` that is ABSENT (the BLOCKED / TIMEOUT failure face) prints no `next:`
47
- // line; a present hop with `hop: null` (`done` · `soft-cap` · the doc-class
50
+ // A `NextHop` that is ABSENT (the BLOCKED / TIMEOUT failure face) prints neither
51
+ // route row; a present hop with `hop: null` (`done` · `soft-cap` · the doc-class
48
52
  // `terminal` / `blocked` rows) still prints its frozen line.
49
53
  //
50
54
  // The class satisfies the session/run.ts CapsuleFace seam (T8's interaction point) —
@@ -55,7 +59,8 @@ import { RouteRenderer } from "./route-render.js";
55
59
  * Capsule — the single capsule output face. emit(status, handoff, hop?,
56
60
  * withHandoff?, summary?) renders one round's facts into the byte-pinned `status ·
57
61
  * handoff` line, the fix round's optional disposition summary, and the optional
58
- * `next:` line LAST (the dispatchable literal closes the output). The key words are
62
+ * `next:` row plus its `reason:` row LAST (the dispatchable literal keeps its exact
63
+ * bytes; the diagnostic fact rides the line after it). The key words are
59
64
  * the CapsuleKey literals the kind loop renders (pin-enforced by the emit
60
65
  * signature); the separator, station and route/status words ride the injected Words
61
66
  * instance. The complete executable `next:` literal composes its full argv from the
@@ -81,14 +86,14 @@ export class Capsule {
81
86
  * the status-class key set from the word table (a success status renders
82
87
  * `status · handoff`; a failure status renders `status`, plus `handoff` only when
83
88
  * the round wrote a crash record), then the fix round's optional summary line,
84
- * then the optional `next:` line LAST — the dispatchable literal is the output's
85
- * close. `hop` is the ONE injected `NextHop` object — its ABSENCE (null: the
86
- * BLOCKED / TIMEOUT failure face) prints no `next:` line at all, while a present
87
- * object renders through the shared hop face (`RouteRenderer#renderHop`: the
88
- * soft-cap message · the in-line hop · the face-to-face station · the BLOCKED
89
- * face · the terminal word). `withHandoff` is the caller's crash-record fact — the
90
- * key set remains the table's single source (this render adds no status special
91
- * case).
89
+ * then the optional `next:` row followed by its `reason:` row — the dispatchable
90
+ * literal keeps its exact bytes and the diagnostic fact lands on the line after
91
+ * it. `hop` is the ONE injected `NextHop` object — its ABSENCE (null: the
92
+ * BLOCKED / TIMEOUT failure face) prints neither row, while a present object
93
+ * renders through the shared hop face (`RouteRenderer#renderHop`: the soft-cap
94
+ * message · the in-line hop · the face-to-face station · the BLOCKED face · the
95
+ * terminal word). `withHandoff` is the caller's crash-record fact — the key set
96
+ * remains the table's single source (this render adds no status special case).
92
97
  *
93
98
  * Five parameters is one over the flat-signature limit: the positional face IS the
94
99
  * pinned contract (the seam's emit signature), so it stays flat rather than boxed
@@ -109,9 +114,12 @@ export class Capsule {
109
114
  const lines = [capsuleLine];
110
115
  if (summary !== undefined)
111
116
  lines.push(summary);
112
- const next = this.#route.renderHop(hop ?? null);
113
- if (next !== null)
117
+ const hopValue = hop ?? null;
118
+ const next = this.#route.renderHop(hopValue);
119
+ if (hopValue !== null && next !== null) {
114
120
  lines.push(`${words.station("next")} ${next}`);
121
+ lines.push(this.#route.renderReason(hopValue));
122
+ }
115
123
  return lines;
116
124
  }
117
125
  /** One path value normalized to the branded repoRoot-relative `RepoPath` through