@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/dist/face/cli.js CHANGED
@@ -288,13 +288,22 @@ export class Cli {
288
288
  if (parsed.harness === undefined)
289
289
  this.#usage(command, "cdd init: missing --harness");
290
290
  const update = parsed.update ?? false;
291
+ // The recommended tier is its own parsed boolean — an absent flag means the
292
+ // core-only face, never a derived default.
293
+ const recommended = parsed.includeRecommends ?? false;
294
+ // The flatten request — the ONE shape `preview` and `run` both read.
295
+ const request = {
296
+ host: parsed.harness,
297
+ shape: update ? "update" : "install",
298
+ recommended,
299
+ };
291
300
  if (dryRun) {
292
- for (const line of this.#init.preview(parsed.harness, update))
301
+ for (const line of this.#init.preview(request))
293
302
  this.#initHeader(line);
294
303
  this.#exitCode = 0;
295
304
  return;
296
305
  }
297
- this.#exitCode = await this.#init.run(parsed.harness, update);
306
+ this.#exitCode = await this.#init.run(request);
298
307
  });
299
308
  }
300
309
  /** `cdd board --plan <path> / --spec <path>` — the entry document's progress board
@@ -357,10 +366,11 @@ export class Cli {
357
366
  // The in-flight fact is TREE-level: the board inspects it (read-only — the gate
358
367
  // and the board share `InFlight.inspect()`, never a second liveness judgment).
359
368
  const inflight = new InFlight(new WorkspaceRoot(repoRoot, this.#config.handoffNamespace().workspaceRoot), entry.slug ?? "");
360
- // The board's `next:` line renders ONE injected `NextHop` (P22 §5.2): the
361
- // pipeline OBSERVATION comes from the board face, the four face-order rules and
362
- // the ONE derivation from this assembly point (`BoardNext`) — the board itself
363
- // holds no ledger for the next line and judges nothing.
369
+ // The board's `next:` line renders ONE injected `NextHop` (P22 §5.2 · P24 §11):
370
+ // the pipeline FACTS come from the board face, and the ONE hop assembly (the four
371
+ // face-order rules + the six hop cells) lives in the session plane's
372
+ // `PipelineFrontier` — the same assembly the capsule renders, so the board and the
373
+ // capsule state one hop. Neither face judges anything here.
364
374
  const next = BoardNext.of(index, entry, root);
365
375
  const board = BoardView.render(index, entry, repoRoot, this.#words, host, ARGV_CHANNEL, await inflight.inspect(), next);
366
376
  for (const line of board.lines)
@@ -404,6 +414,7 @@ export class Cli {
404
414
  // boolean, never a truthy string.
405
415
  harness: HOST_IDS.find((id) => id === harnessToken),
406
416
  update: globals.update === true,
417
+ includeRecommends: globals.includeRecommends === true,
407
418
  };
408
419
  }
409
420
  /** The invocation's `--dry-run` scope — the constructor flag OR the program-scope
@@ -586,7 +597,10 @@ export class Cli {
586
597
  },
587
598
  target: scene.target ?? undefined,
588
599
  capsule: new Capsule(this.#words, ARGV_CHANNEL, HostDetect.detect(process.env), scene.workspace.root.basis),
589
- planPath: scene.planPath,
600
+ planPath: scene.pipeline.planPath,
601
+ specType: scene.pipeline.specType,
602
+ specPath: scene.pipeline.specPath,
603
+ planGraph: scene.pipeline.planGraph,
590
604
  // The hop derivation's pipeline-station discrimination (§5.2) — the ONE
591
605
  // declaration-reading judgment, injected so the session plane never imports a
592
606
  // face class.
@@ -600,9 +614,10 @@ export class Cli {
600
614
  if (open !== expected) {
601
615
  const pendingBlock = verdict === "pending-fix" ? this.#gate.pendingFixBlock(scene, reviewed) : null;
602
616
  const docBlock = open === null ? this.#gate.docLineBlock(scene, reviewed) : null;
603
- // The generic refusal renders the SAME `NextHop` the capsule / board /
604
- // frontier read (P22 §5.2 · the ONE message shape): `<reason> · the next
605
- // round is <hop>` · `<reason> · next: <station>` · the bare reason. The two
617
+ // The generic refusal renders this LINE's own hop (the line frontier's
618
+ // assembly): `<reason> · the next round is <hop>` · `<reason> · next:
619
+ // <station>` · the bare reason. The capsule and the board render the PIPELINE
620
+ // frontier's assembly — a different reader, a different object. The two
606
621
  // identity-aware block messages above own their facts (`reviewed` has no
607
622
  // Home in `NextHop`) and stay verbatim.
608
623
  const reject = pendingBlock ??
@@ -919,6 +934,23 @@ export class Cli {
919
934
  const state = type === "wave"
920
935
  ? new TaskGraph(new PlanDocType("plan").parse(planText.split("\n")))
921
936
  : EMPTY_RUN_STATE;
937
+ // The pipeline frontier's four declared cells (§11) — the composition root's ONE
938
+ // collection point. The identity word + path come from the document index (never
939
+ // the argv `--type` spelling): every non-plan declared document owns the identity
940
+ // slot, so `phase-spec` / `single-spec` / `overall` all reach the same assembly.
941
+ // The plan path is the argv value on the plan / branch lines and the index's
942
+ // same-slug plan on a `--spec` round whose argv names none — a spec round that
943
+ // dropped it would leave the frontier blind to the plan face and the capsule
944
+ // printing this line's own exit. The graph is the ONE guarded plan read (the wave
945
+ // run's already-parsed state stands in; the session plane reads no file).
946
+ const identity = index.identityDoc(slug);
947
+ const hopPlanPath = planPath ?? index.planOf(slug)?.path ?? null;
948
+ const pipeline = {
949
+ specType: identity?.docType ?? null,
950
+ specPath: identity?.path ?? null,
951
+ planPath: hopPlanPath,
952
+ planGraph: state instanceof TaskGraph ? state : BoardView.planGraph(hopPlanPath),
953
+ };
922
954
  return {
923
955
  workspace,
924
956
  ledger,
@@ -929,6 +961,7 @@ export class Cli {
929
961
  target,
930
962
  state,
931
963
  router: new NextStepRouter(),
964
+ pipeline,
932
965
  briefPath: null,
933
966
  specLink,
934
967
  overallLink,
@@ -76,6 +76,11 @@ export const ARGV_CHANNEL = {
76
76
  type: "bool",
77
77
  help: "update the installed plugin set instead of installing it",
78
78
  },
79
+ includeRecommends: {
80
+ flag: "--include-recommends",
81
+ type: "bool",
82
+ help: "also install/update the recommended pi capability packages",
83
+ },
79
84
  dryRun: {
80
85
  flag: "--dry-run",
81
86
  type: "bool",
@@ -233,7 +238,7 @@ export const CLI_COMMANDS = [
233
238
  name: "init",
234
239
  description: "install or update the kairos plugin set for a harness",
235
240
  example: "cdd init --harness=claude",
236
- keys: [{ key: "harness", required: true }, { key: "update" }],
241
+ keys: [{ key: "harness", required: true }, { key: "update" }, { key: "includeRecommends" }],
237
242
  },
238
243
  ];
239
244
  /** The schema `<type>` vocabulary — the get leaf's ONE table (spec §5.3): the
package/dist/face/gate.js CHANGED
@@ -112,13 +112,15 @@ export class CliGate {
112
112
  return null;
113
113
  return `the pending fix applies to the unchanged doc (doc-hash ${reviewed.doc_hash.slice(0, 12)}…) — run cdd fix first`;
114
114
  }
115
- /** lineHop(scene) — the line's ONE next-hop object (§5.2): the SAME derivation
116
- * the capsule, the board and the lifecycle frontier read, built from this line's
117
- * facts through `Ledger#nextHopOf` (the ONE assembly entry: the drift gate + the
118
- * declaration read). The CLI rejection message renders THIS object's `reason` +
119
- * hop/station — never a second judgment, never a second shape. The doc-class
115
+ /** lineHop(scene) — this LINE's next-hop object (§5.2), the LINE FRONTIER's
116
+ * assembly: built from this line's facts through `Ledger#nextHopOf` (the ONE
117
+ * derivation entry: the drift gate + the declaration read). The capsule and the
118
+ * board render the PIPELINE frontier's assembly (`PipelineFrontier#hopOf`) instead,
119
+ * a different reader over a different input; this one serves the CLI rejection
120
+ * message, which renders THIS object's `reason` + hop/station
121
+ * — never a second judgment, never a second shape. The doc-class
120
122
  * discrimination is ROOTED in the workspace's own repo basis (the same basis the
121
- * lifecycle frontier injects), so an engine invoked from a subdirectory reads the
123
+ * lifecycle injects), so an engine invoked from a subdirectory reads the
122
124
  * same declared `doc-type:` the board does. Null when the scene holds no
123
125
  * registered line (no fixed target → there is no line to name). */
124
126
  lineHop(scene) {
package/dist/face/init.js CHANGED
@@ -62,47 +62,106 @@ export class CliInit {
62
62
  this.#runner = opts.runner;
63
63
  this.#header = opts.header;
64
64
  }
65
- /** The ordered step plan for one harness + shape — the ONE flatten source the
66
- * preview and the real run both read. The only branch point between them is
67
- * whether `StepRunner` is called, so a preview can never drift from the run. */
68
- #stepsOf(host, update) {
65
+ /** The ordered step plan for one request — the ONE flatten source the preview and
66
+ * the real run both read. A `recommended === false` request takes the `core` rows
67
+ * only, which is the flag-less face's byte-identical plan; `true` takes the whole
68
+ * table in roster order (the recommended rows carry zero claude commands, so a
69
+ * claude request cannot grow beyond its core span). The only branch point between
70
+ * preview and run is whether `StepRunner` is called, so a preview can never drift
71
+ * from the run. */
72
+ #stepsOf(request) {
69
73
  const steps = [];
70
74
  for (const row of PLUGINS) {
71
- for (const argv of update ? row[host].update : row[host].install) {
72
- steps.push({ packageName: row.name, argv });
75
+ if (!request.recommended && row.tier !== "core")
76
+ continue;
77
+ const column = row[request.host];
78
+ for (const argv of request.shape === "update" ? column.update : column.install) {
79
+ steps.push({ packageName: row.name, argv, tier: row.tier });
73
80
  }
74
81
  }
75
82
  return steps;
76
83
  }
84
+ /** The tier split of one flattened plan — counted off each step's own `tier`.
85
+ * The tier fact travels with the step (§4.1), so no surface below re-reads the
86
+ * roster: `#stepsOf` is the only tier judge in this face. */
87
+ #tierCountsOf(steps) {
88
+ let core = 0;
89
+ for (const step of steps)
90
+ if (step.tier === "core")
91
+ core += 1;
92
+ return { core, recommended: steps.length - core };
93
+ }
94
+ /** The summary line — the flag-less bytes, plus the tier split only when the
95
+ * recommended tier was requested (§5.2). `ok` selects the run face's `ok` word;
96
+ * the preview face adds its dry-run tail instead. */
97
+ #summaryOf(steps, request, ok) {
98
+ const { core, recommended } = this.#tierCountsOf(steps);
99
+ const head = ok ? `init: ${steps.length} steps ok` : `init: ${steps.length} steps`;
100
+ const tier = request.recommended ? ` · ${core} core + ${recommended} recommended` : "";
101
+ const tail = ok ? "" : " — dry run, nothing executed";
102
+ return `${head} (${request.host} · ${request.shape}${tier})${tail}`;
103
+ }
104
+ /** The empty-tier info line — written only when the flag was requested and the
105
+ * flattened plan carries zero recommended steps (today: claude). A silent no-op
106
+ * would read as "installed", so the line is a hard requirement (§5.2). */
107
+ #emptyTierLinesOf(steps, request) {
108
+ if (!request.recommended || this.#tierCountsOf(steps).recommended > 0)
109
+ return [];
110
+ return [`init: no recommended packages for ${request.host}`];
111
+ }
112
+ /** The recommended-tier failure line — one wording per command shape (§5.3): the
113
+ * install form states the core set is already in place, the update form points at
114
+ * the install run instead of repeating the update that just failed. */
115
+ #recommendedFailureOf(step, request) {
116
+ const head = `init: ${step.packageName} is a recommended package — `;
117
+ return request.shape === "update"
118
+ ? `${head}run cdd init --harness=${request.host} --include-recommends without --update first`
119
+ : `${head}the core plugin set is already installed`;
120
+ }
121
+ /** The first-failure report — the pinned failure line, then the recommended-tier
122
+ * line (recommended steps only), then the unchanged update hint. Always exits 1. */
123
+ #reportFailure(steps, index, code, request) {
124
+ const step = steps[index];
125
+ this.#io.stderr(`init[${index + 1}/${steps.length}] · ${step.argv.join(" ")} · exit ${code}\n`);
126
+ if (step.tier === "recommended") {
127
+ this.#io.stderr(`${this.#recommendedFailureOf(step, request)}\n`);
128
+ }
129
+ // The hint is conditional wording — the engine parses zero harness output,
130
+ // so it cannot know whether "not installed" caused this failure.
131
+ if (request.shape === "update") {
132
+ this.#io.stderr(`if the package is not installed, run cdd init --harness=${request.host} without --update first\n`);
133
+ }
134
+ return 1;
135
+ }
136
+ /** The green close — the summary line, then the empty-tier info line when the flag
137
+ * was requested and nothing recommended was planned (§5.2 order: summary first). */
138
+ #writeGreenSummary(steps, request) {
139
+ this.#header(this.#summaryOf(steps, request, true));
140
+ for (const line of this.#emptyTierLinesOf(steps, request))
141
+ this.#header(line);
142
+ }
77
143
  /** Render the step plan the run would execute — one `would run: <argv join>` line
78
144
  * per step, then the summary. Zero spawn, zero write: the runner is never
79
145
  * reached on this path (a preview is a rendering, not an execution). */
80
- preview(host, update) {
81
- const steps = this.#stepsOf(host, update);
146
+ preview(request) {
147
+ const steps = this.#stepsOf(request);
82
148
  return [
83
149
  ...steps.map((step) => `would run: ${step.argv.join(" ")}`),
84
- `init: ${steps.length} steps (${host} · ${update ? "update" : "install"}) — dry run, nothing executed`,
150
+ this.#summaryOf(steps, request, false),
151
+ ...this.#emptyTierLinesOf(steps, request),
85
152
  ];
86
153
  }
87
- /** Run the harness's sequence — 0 all green, 1 the first failed step. */
88
- async run(host, update) {
89
- const steps = this.#stepsOf(host, update);
90
- const total = steps.length;
154
+ /** Run one request — 0 all green, 1 the first failed step. */
155
+ async run(request) {
156
+ const steps = this.#stepsOf(request);
91
157
  for (const [index, step] of steps.entries()) {
92
158
  const ordinal = index + 1;
93
- this.#header(`init[${ordinal}/${total}] ${host} · ${step.packageName} · ${step.argv.slice(1).join(" ")}`);
159
+ this.#header(`init[${ordinal}/${steps.length}] ${request.host} · ${step.packageName} · ${step.argv.slice(1).join(" ")}`);
94
160
  const code = await this.#runner.run(step.argv);
95
- if (code !== 0) {
96
- this.#io.stderr(`init[${ordinal}/${total}] · ${step.argv.join(" ")} · exit ${code}\n`);
97
- // The hint is conditional wording — the engine parses zero harness output,
98
- // so it cannot know whether "not installed" caused this failure.
99
- if (update) {
100
- this.#io.stderr(`if the package is not installed, run cdd init --harness=${host} without --update first\n`);
101
- }
102
- return 1;
103
- }
161
+ if (code !== 0)
162
+ return this.#reportFailure(steps, index, code, request);
104
163
  }
105
- this.#header(`init: ${total} steps ok (${host} · ${update ? "update" : "install"})`);
164
+ this.#writeGreenSummary(steps, request);
106
165
  return 0;
107
166
  }
108
167
  }
@@ -6,8 +6,15 @@
6
6
  // plus a gate, never a second source.
7
7
  //
8
8
  // Row order is a first-class fact — the array order IS the execution order and the
9
- // README row order (upstream dependencies first, kairos last). Object key order
10
- // would not carry that promise, so the roster is an array of rows, not an object.
9
+ // README row order (the core three first: upstream dependencies then kairos; the six
10
+ // recommended capability packages after them). Object key order would not carry that
11
+ // promise, so the roster is an array of rows, not an object.
12
+ //
13
+ // The `tier` field splits the same table in two without a second list: `core` rows
14
+ // are the install contract `cdd init` always runs, `recommended` rows are the pi
15
+ // capability packages the `--include-recommends` flag opts into. Claude Code carries
16
+ // those six capabilities natively, so a recommended row's claude column is an EMPTY
17
+ // array — an empty cell, never a missing column.
11
18
  //
12
19
  // The host vocabulary stays single-sourced in `face/host.ts`: this module declares
13
20
  // no host id list — the row's column set closes over `HostId` (a missing column, or
@@ -21,6 +28,7 @@
21
28
  export const PLUGINS = [
22
29
  {
23
30
  name: "superpowers",
31
+ tier: "core",
24
32
  claude: {
25
33
  install: [
26
34
  ["claude", "plugin", "marketplace", "add", "obra/superpowers-marketplace"],
@@ -38,6 +46,7 @@ export const PLUGINS = [
38
46
  },
39
47
  {
40
48
  name: "mattpocock-skills",
49
+ tier: "core",
41
50
  claude: {
42
51
  install: [
43
52
  ["claude", "plugin", "marketplace", "add", "mattpocock/skills"],
@@ -55,6 +64,7 @@ export const PLUGINS = [
55
64
  },
56
65
  {
57
66
  name: "kairos",
67
+ tier: "core",
58
68
  claude: {
59
69
  install: [
60
70
  ["claude", "plugin", "marketplace", "add", "oscaner/skills"],
@@ -70,4 +80,62 @@ export const PLUGINS = [
70
80
  update: [["pi", "update", "npm:@oscaner-skills/kairos"]],
71
81
  },
72
82
  },
83
+ // The six recommended capability packages — pi-only rows. Claude Code carries file
84
+ // search, todo tracking, structured questioning, web access, background tasks and
85
+ // AGENTS.md injection natively, so the claude column stays EMPTY here: an empty
86
+ // array is the fact, never a placeholder to be filled for symmetry.
87
+ {
88
+ name: "pi-fff",
89
+ tier: "recommended",
90
+ claude: { install: [], update: [] },
91
+ pi: {
92
+ install: [["pi", "install", "npm:@ff-labs/pi-fff"]],
93
+ update: [["pi", "update", "npm:@ff-labs/pi-fff"]],
94
+ },
95
+ },
96
+ {
97
+ name: "rpiv-todo",
98
+ tier: "recommended",
99
+ claude: { install: [], update: [] },
100
+ pi: {
101
+ install: [["pi", "install", "npm:@juicesharp/rpiv-todo"]],
102
+ update: [["pi", "update", "npm:@juicesharp/rpiv-todo"]],
103
+ },
104
+ },
105
+ {
106
+ name: "rpiv-ask-user-question",
107
+ tier: "recommended",
108
+ claude: { install: [], update: [] },
109
+ pi: {
110
+ install: [["pi", "install", "npm:@juicesharp/rpiv-ask-user-question"]],
111
+ update: [["pi", "update", "npm:@juicesharp/rpiv-ask-user-question"]],
112
+ },
113
+ },
114
+ {
115
+ name: "pi-web-access",
116
+ tier: "recommended",
117
+ claude: { install: [], update: [] },
118
+ pi: {
119
+ install: [["pi", "install", "npm:pi-web-access"]],
120
+ update: [["pi", "update", "npm:pi-web-access"]],
121
+ },
122
+ },
123
+ {
124
+ name: "pi-background-tasks",
125
+ tier: "recommended",
126
+ claude: { install: [], update: [] },
127
+ pi: {
128
+ install: [["pi", "install", "npm:pi-background-tasks"]],
129
+ update: [["pi", "update", "npm:pi-background-tasks"]],
130
+ },
131
+ },
132
+ {
133
+ name: "pi-agentsmd",
134
+ tier: "recommended",
135
+ claude: { install: [], update: [] },
136
+ pi: {
137
+ install: [["pi", "install", "npm:pi-agentsmd"]],
138
+ update: [["pi", "update", "npm:pi-agentsmd"]],
139
+ },
140
+ },
73
141
  ];
@@ -17,6 +17,7 @@
17
17
  //
18
18
  // Module-level exports are the class — zero behavior-carrying bare functions.
19
19
  import process from "node:process";
20
+ import { ReviewedIdentity } from "../session/reviewed-identity.js";
20
21
  import { RoundNaming } from "../session/round-naming.js";
21
22
  import { HOSTS, HostDetect } from "./host.js";
22
23
  import { Words } from "./words.js";
@@ -129,22 +130,39 @@ export class Preview {
129
130
  .join(" · ");
130
131
  }
131
132
  /** The ledger writes the round would record — the round RECORD it would append
132
- * (identity: op · cycle · attempt) plus, on a completed review, the
133
- * reviewed-revision write-back. The three legs are `#bookkeep`'s own: the doc line
134
- * binds its document's revision, the wave line its RENDERED brief's, and the
135
- * branch line binds none (its review judges the live tree). */
133
+ * (identity: op · cycle · attempt) plus, when the round lands one, the
134
+ * reviewed-revision write-back. WHICH reviewed input the round binds is the ONE
135
+ * judgment both faces share (`ReviewedIdentity.legOf`): the same phases — review,
136
+ * branch-review, fix — and the same kind → leg mapping. The verdict's
137
+ * `targetAction` is the lifecycle's own input and never rides a dry run: the
138
+ * preview states the write-back a completed round WOULD record. */
136
139
  #recordsOf(frame) {
137
140
  const parts = [
138
141
  `progress.waves["${frame.key}"].rounds += { op: ${this.#naming.op(frame)}, cycle: ${frame.round}, attempt: ${frame.attempt ?? 1} }`,
139
142
  ];
140
- if (frame.phase === "review") {
141
- if (frame.target.kind === "wave")
142
- parts.push("reviewedRevision(brief)");
143
- else if (frame.target.kind === "plan" || frame.target.kind === "spec")
144
- parts.push("reviewedRevision(doc)");
143
+ const leg = ReviewedIdentity.legOf(frame.phase, frame.target.kind);
144
+ if (leg !== null) {
145
+ const stated = this.#reviewedLegOf(leg);
146
+ if (stated !== null)
147
+ parts.push(stated);
145
148
  }
146
149
  return parts.join(" · ");
147
150
  }
151
+ /** The rendered write-back leg of one judgment leg: the wave line states its
152
+ * RENDERED brief, the doc lines their judged document, the branch line its plan
153
+ * document. The branch leg's plan path is an INPUT, not part of the judgment —
154
+ * with no plan fact the preview states no leg rather than an empty identity (the
155
+ * same source the `reads:` row names, and what the real run records too). */
156
+ #reviewedLegOf(leg) {
157
+ switch (leg) {
158
+ case "doc":
159
+ return "reviewedRevision(doc)";
160
+ case "brief":
161
+ return "reviewedRevision(brief)";
162
+ case "branch":
163
+ return this.#scene.planPath === null ? null : "reviewedRevision(doc)";
164
+ }
165
+ }
148
166
  /** The child invocation the real run would spawn — `<HostId> <invoke>`: the host
149
167
  * id then the harness row's invoke argument string verbatim (the binary name is a
150
168
  * separate row column and never rides the invoke value). With no host detected the
@@ -80,6 +80,15 @@ export class RouteRenderer {
80
80
  }
81
81
  return this.#words.routeWord("done");
82
82
  }
83
+ /** renderReason(hop) → the `reason:` VALUE of one derived NextHop — the named fact
84
+ * that selected the hop (one of the seven `NEXT_HOP_REASON` tokens), rendered as a
85
+ * row of its OWN so the dispatchable `next:` literal keeps its exact bytes. A
86
+ * hop-absent round renders no row at all: the caller gates on the SAME hop object
87
+ * its `next:` render reads, so the two rows can never disagree. The station word
88
+ * rides the word table, so the capsule's prefix and this face's value never fork. */
89
+ renderReason(hop) {
90
+ return `${this.#words.station("reason")} ${hop.reason}`;
91
+ }
83
92
  /** render(route, target) → the `next:` value: the complete executable command (a
84
93
  * C5 hop), the pipeline entry (a `handoff`), or the bare terminal word (`done`).
85
94
  * The additive optional RouteTarget supplies the frame's own type + id + plan for
@@ -5,9 +5,10 @@
5
5
  // table with three families served by one class:
6
6
  //
7
7
  // capsule — the capsule-station words: the capsule keys (status · handoff, the
8
- // pinned emit order), the `next:` route station + the stderr stations, the
9
- // status vocabulary and the route classifier words. Every byte the capsule
10
- // emits rides this family — a reorder is a red test.
8
+ // pinned emit order), the two route stations (`next:` + `reason:`) and
9
+ // the stderr stations, the status vocabulary and the route classifier
10
+ // words. Every byte the capsule emits rides this family — a reorder is a
11
+ // red test.
11
12
  // guard — the guard-ban words: the retired-vocabulary ban rows (STALE / GATE /
12
13
  // shape) the guards assert absent from the live faces. This is the ban
13
14
  // table's data-source face — the guard scan releases these rows as its
@@ -53,9 +54,12 @@ export const CAPSULE_WORDS = {
53
54
  separator: " · ",
54
55
  /** The status vocabulary — the five handoff-conclusion values. */
55
56
  status: ["APPROVED", "BLOCKED", "CHANGES_REQUESTED", "REVIEW_FIX", "TIMEOUT"],
56
- /** The route stations — the `: `-suffixed channel anchors. */
57
+ /** The route stations — the `: `-suffixed channel anchors. The two route anchors
58
+ * (`next:` and the `reason:` row that follows it) open the capsule's output;
59
+ * the three stderr anchors open the diagnostics channels. */
57
60
  stations: {
58
61
  next: "next:",
62
+ reason: "reason:",
59
63
  blocked: "CDD_BLOCKED:",
60
64
  warn: "CDD_WARN:",
61
65
  cliMissing: "CDD_CLI_MISSING:",
@@ -394,10 +394,10 @@ export class Ledger {
394
394
  return cycles.length > 0 ? Math.max(...cycles) + 1 : 1;
395
395
  }
396
396
  /** Record a line's reviewed identity — the identity-aware gate's basis (written
397
- * when the review round completes: the line reopens on drift from this recorded
398
- * revision, and BLOCKs revision-aware when unchanged). The kind IS part of the
399
- * identity: a doc line binds a doc-revision (T7), a wave line a brief-revision
400
- * (D30) — one row, one reviewed identity. */
397
+ * when a review or a fix round completes: the line reopens on drift from this
398
+ * recorded revision, and BLOCKs revision-aware when unchanged). The kind IS part
399
+ * of the identity: a doc line binds a doc-revision (T7), a wave line a
400
+ * brief-revision (D30) — one row, one reviewed identity. */
401
401
  recordReviewedRevision(key, revision, identity = null) {
402
402
  const data = this.readProgress() ?? this.emptyProgress();
403
403
  let row = _a.rowFor(data, key, identity);
@@ -569,8 +569,7 @@ export class Ledger {
569
569
  return { kind: "review" };
570
570
  if (route?.kind === "fix") {
571
571
  // The fix-awaited face — a drifted wave BRIEF reopens at review (D30/D16), else fix.
572
- const reviewed = this.reviewedRevisionOf(waveKey);
573
- if (reviewed !== null && this.#briefDrift(waveKey, reviewed))
572
+ if (this.briefDrifted(waveKey))
574
573
  return { kind: "review" };
575
574
  return {
576
575
  kind: "fix",
@@ -603,9 +602,12 @@ export class Ledger {
603
602
  * (the append-only backfill case the whole-plan hash wrongly flagged). An
604
603
  * underivable brief (unreadable plan / absent task) is not a drift (present
605
604
  * facts only). A row bound to a non-brief kind (a doc kind, only via a corrupt
606
- * hand-write) is not a wave brief — no drift. */
607
- #briefDrift(waveKey, reviewed) {
608
- if (reviewed.kind !== "brief-revision")
605
+ * hand-write) is not a wave brief — no drift. The ONE public read of the fact:
606
+ * `waveLineRoute`'s D30 leg and the next-hop assembly's reason-only `briefDrift`
607
+ * cell both come through here. */
608
+ briefDrifted(waveKey) {
609
+ const reviewed = this.reviewedRevisionOf(waveKey);
610
+ if (reviewed === null || reviewed.kind !== "brief-revision")
609
611
  return false;
610
612
  const current = this.#briefRevision(waveKey, reviewed.plan);
611
613
  if (current === null)
@@ -796,16 +798,23 @@ export class Ledger {
796
798
  * line's OWN facts and handed to the router's ONE derivation: the drift-aware gate
797
799
  * verdict, the ONE doc-class verdict (the declared station the face axis is read
798
800
  * out of), the caller's route (the count table's row for a single line, the
799
- * pipeline walk's route for the board) and the judged document. Every read face
800
- * (capsule · CLI rejection · board · the lifecycle frontier) comes through here,
801
- * so the four faces share one object by construction — no face assembles a second
802
- * copy of the inputs, and no judgment is re-made here (the route is the count
803
- * table's). The ONE exception is the drift-reopened line: the gate's `drift`
804
- * verdict IS the reopen, and the closure-side route the count table recorded
805
- * predates the document movement — so the assembly hands the derivation the
806
- * reopened review hop in that case. A presentation-level substitution: the count
807
- * table's judgment (`NextStepRouter#next`) stays the only judge, and a still-open
808
- * hop (review / fix) is never overridden by the drift fact. */
801
+ * pipeline walk's route for the board) and the judged document. TWO assemblies
802
+ * call this derivation (the line frontier's and the pipeline frontier's
803
+ * `PipelineFrontier#hopOf`) and neither keeps a private copy of the inputs — the
804
+ * line frontier serves `peekNext` and the CLI rejection, the pipeline assembly
805
+ * serves the capsule and the board — and no judgment is re-made here (the route is
806
+ * the count table's). TWO drift values leave this assembly, kept apart on purpose:
807
+ * · the ROUTE SUBSTITUTION driver reads the gate verdict alone (a doc line's
808
+ * `reviewGate`); the injected `briefDrift` cell never moves a route — a wave's
809
+ * exit-side station (`handoff`) is never rewritten into a review;
810
+ * · the REASON cell adds the caller-injected wave brief-drift fact to that
811
+ * verdict, so a drifted wave names `doc-drift` without a second judgment.
812
+ * The ONE exception to the route being the caller's is the drift-reopened doc
813
+ * line: the gate's `drift` verdict IS its reopen, and the closure-side route the
814
+ * count table recorded predates the document movement — so the assembly hands the
815
+ * derivation the reopened review hop in that case. A presentation-level
816
+ * substitution: the count table's judgment (`NextStepRouter#next`) stays the only
817
+ * judge, and a still-open hop (review / fix) is never overridden by the drift fact. */
809
818
  nextHopOf(input) {
810
819
  const drift = input.doc != null && input.type !== "wave"
811
820
  ? this.reviewGate(input.key, input.doc, input.type).kind === "open"
@@ -822,9 +831,13 @@ export class Ledger {
822
831
  // The face axis is the ONE verdict this assembly reads (spec §5.2's doc-class
823
832
  // discrimination): no target carries no judgeable class (the bare terminal).
824
833
  const verdict = input.target === null ? "terminal" : input.docClassOf(input.target);
834
+ // The REASON cell's drift value — `drift` above plus the caller-injected wave
835
+ // brief-drift fact. The two are kept apart: only `drift` drives the route
836
+ // substitution, so a wave's exit-side station keeps its bytes while its `reason:`
837
+ // row still names the movement.
825
838
  return this.#router.nextHop({
826
839
  target: input.target,
827
- gate: { drift },
840
+ gate: { drift: drift || (input.briefDrift ?? false) },
828
841
  verdict,
829
842
  route,
830
843
  nextLineOpen: input.nextLineOpen,
@@ -30,8 +30,8 @@
30
30
  // so a consumer never consults a second table. The face-to-face station selection
31
31
  // rides the ONE derivation (`nextHop`): a `done` route's `to` cell is
32
32
  // `PIPELINE_NEXT`'s row for the judged doc class, a `handoff` route carries its own
33
- // entry, and the pipeline traversal itself belongs to the board's assembly face —
34
- // no second resolver.
33
+ // entry, and the pipeline traversal itself belongs to the session plane's
34
+ // `PipelineFrontier` — no second resolver.
35
35
  //
36
36
  // Module-level exports are types / constants / the class — zero behavior-carrying
37
37
  // bare functions (the plan's zero-bare-function discipline).
@@ -69,8 +69,9 @@ export const PIPELINE_NEXT = {
69
69
  branch: { kind: "ref", ref: "kairos:cdd-close" },
70
70
  };
71
71
  /** The pipeline's phase-level face order (D40) — the face-to-face traversal
72
- * `spec → plan → wave → branch`, the ONE order declaration: the board's assembly
73
- * face iterates it, so a consumer maps key → facts and declares NO order of its own. */
72
+ * `spec → plan → wave → branch`, the ONE order declaration: the session plane's
73
+ * `PipelineFrontier` iterates it, so a consumer maps key → facts and declares NO
74
+ * order of its own. */
74
75
  export const PIPELINE_FACES = ["phase-spec", "plan", "wave", "branch"];
75
76
  /** The single reason table (§5.2) — every `NextHop.reason` value comes from here, so
76
77
  * the four read faces and the CLI rejection message name a fact by ONE spelling (a
@@ -240,7 +241,8 @@ export class NextStepRouter {
240
241
  return PIPELINE_NEXT[verdict];
241
242
  }
242
243
  /** The named fact behind the hop — one `NEXT_HOP_REASON` row, in this order: the
243
- * soft cap · a pending fix · a drift-reopened line · an open line advancing · an
244
+ * soft cap · a pending fix · a drift-reopened line (its reviewed identity moved —
245
+ * a doc revision or a wave's brief revision) · an open line advancing · an
244
246
  * unjudgeable doc class · a closed face · the closed line's handoff. Drift never
245
247
  * outranks a pending fix (an unclosed line's blocker keeps the fix hop). */
246
248
  #reasonOf(input, route, verdict) {