@oscaner-skills/cdd-engine 4.5.0 → 4.7.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.
@@ -21,6 +21,7 @@ import { CompletionCriteria, FixDispositions } from "../contract/completion-crit
21
21
  import { GitClient } from "../infra/git.js";
22
22
  import { ProcessFacts } from "../infra/proc.js";
23
23
  import { RoundLog } from "../infra/round-log.js";
24
+ import { BriefRenderer } from "../render/brief.js";
24
25
  import { TemplateAssembler } from "../render/templates.js";
25
26
  import { TargetFaceTable } from "../session/faces.js";
26
27
  import { HandoffSchema } from "../session/handoff-schema.js";
@@ -60,6 +61,9 @@ export class CliLifecycle {
60
61
  #io;
61
62
  #scene;
62
63
  #reviews;
64
+ /** The brief projection face — the wave frame's reviewed-basis hash rides the same
65
+ * task-only assembly the ledger binds (one projection, two callers). */
66
+ #brief;
63
67
  /** The single word table (the promotion WARN wording + its station) — one instance,
64
68
  * injected at the composition root, so the lifecycle never re-types a user-facing
65
69
  * line. */
@@ -111,6 +115,7 @@ export class CliLifecycle {
111
115
  this.#stealStale = opts.stealStale ?? false;
112
116
  this.#sync = opts.sync ?? new Terminator();
113
117
  this.#template = opts.template ?? new TemplateAssembler();
118
+ this.#brief = opts.brief ?? new BriefRenderer();
114
119
  this.#words = opts.words ?? new Words();
115
120
  this.#io = opts.io ?? {
116
121
  stdout: (t) => process.stdout.write(t),
@@ -506,18 +511,20 @@ export class CliLifecycle {
506
511
  return null;
507
512
  }
508
513
  }
509
- /** The wave frame's brief hash at acquire time — `ReviewRefs.briefRevision` over the
510
- * brief file this dispatch rendered (the SAME hash face the ledger binds as the
511
- * reviewed revision). Computed independently of the ledger's records, so a wave's
512
- * FIRST dispatch (no `brief-revision` row yet) still carries the hash. Null off the
513
- * wave face and when the brief is not on disk yet. */
514
+ /** The wave frame's reviewed-basis hash at acquire time — `ReviewRefs.briefRevision`
515
+ * over the SAME task-only projection the ledger binds (`BriefRenderer#taskBody` of
516
+ * the plan for this wave's tasks — P29 §2.2, `## Constraints` excluded). Computed
517
+ * independently of the ledger's records, so a wave's FIRST dispatch (no
518
+ * `brief-revision` row yet) still carries the hash. Null off the wave face, on a
519
+ * plan-less scene and when the plan is unreadable. */
514
520
  #briefHashOf(frame) {
515
521
  const scene = this.#scene;
516
- if (frame.type !== "wave" || scene.planPath === null || scene.briefPath === null)
522
+ if (frame.type !== "wave" || frame.target.kind !== "wave" || scene.planPath === null)
517
523
  return null;
518
524
  try {
519
- const brief = readFileSync(scene.briefPath, "utf8");
520
- return scene.ledger.refs().briefRevision(this.#rel(scene.planPath), brief).brief_hash;
525
+ const plan = readFileSync(scene.planPath, "utf8");
526
+ const body = this.#brief.taskBody(plan, frame.target.tasks);
527
+ return scene.ledger.refs().briefRevision(this.#rel(scene.planPath), body).brief_hash;
521
528
  }
522
529
  catch {
523
530
  return null;
@@ -81,7 +81,7 @@ export class RouteRenderer {
81
81
  return this.#words.routeWord("done");
82
82
  }
83
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
84
+ * that selected the hop (one of the eight `NEXT_HOP_REASON` tokens), rendered as a
85
85
  * row of its OWN so the dispatchable `next:` literal keeps its exact bytes. A
86
86
  * hop-absent round renders no row at all: the caller gates on the SAME hop object
87
87
  * its `next:` render reads, so the two rows can never disagree. The station word
@@ -7,7 +7,9 @@
7
7
  // the plan's `## Constraints` section (the complete plan mirror). The checkable
8
8
  // gate blocks step surfaces that carry a step
9
9
  // with no checkable clause; a requested task with no matching heading blocks the
10
- // whole render (the group-level out-of-bounds contract).
10
+ // whole render (the group-level out-of-bounds contract). The task sections are
11
+ // also exposed alone (`taskBody`) — the wave's reviewed-basis projection (P29
12
+ // §2.2), so the child's bytes and the reopen fingerprint share one assembly.
11
13
  import { PlanDocType } from "../contract/doc.js";
12
14
  import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
13
15
  /**
@@ -54,19 +56,27 @@ export class BriefRenderer {
54
56
  }
55
57
  return { data, missing };
56
58
  }
57
- /** Render the brief content — the requested task sections + the plan's
58
- * `## Constraints` section (the complete plan mirror). Any requested task without
59
- * a heading blocks the whole render (out-of-bounds). */
60
- render(planContent, tasks) {
59
+ /** The task-only projection — the wave's reviewed-basis content face: the requested
60
+ * `### Task N:` sections and nothing else. `render` appends the plan's
61
+ * `## Constraints` on top of this projection for the child; the reviewed-brief hash
62
+ * (`Ledger#briefRevision` / `#briefDrifted`) covers this projection alone (P29 §2.2
63
+ * — a Constraints reword is dispatch input, never a brief drift). One assembly,
64
+ * two consumers: zero second slicing logic. */
65
+ taskBody(planContent, tasks) {
61
66
  const { data, missing } = this.extract(planContent, tasks);
62
67
  if (missing.length > 0) {
63
68
  throw new Error(`task${missing.length > 1 ? "s" : ""} ${missing.join(", ")} not found in the plan`);
64
69
  }
65
70
  const lines = planContent.split("\n");
66
- const sections = data.map((task) => this.#slice(lines, task.range));
71
+ return data.map((task) => this.#slice(lines, task.range)).join("\n\n");
72
+ }
73
+ /** Render the brief content — the task-only projection + the plan's `## Constraints`
74
+ * section (the complete plan mirror the child reads). Any requested task without a
75
+ * heading blocks the whole render (out-of-bounds). */
76
+ render(planContent, tasks) {
77
+ const body = this.taskBody(planContent, tasks);
67
78
  const constraints = this.#reader.section(planContent, "Constraints");
68
- const body = constraints === "" ? sections.join("\n\n") : `${sections.join("\n\n")}\n\n${constraints}`;
69
- return `${body}\n`;
79
+ return constraints === "" ? `${body}\n` : `${body}\n\n${constraints}\n`;
70
80
  }
71
81
  /** The AST-range slice of one task block — the block's own lines verbatim, its
72
82
  * `####` children included (the retired `^#` scan cut a block at its first child
@@ -124,6 +124,52 @@ export class IssueBodyRenderer {
124
124
  }
125
125
  });
126
126
  }
127
+ errors.push(...this.#relatedErrors(input.related));
128
+ return errors;
129
+ }
130
+ /** The `related` tail's shape leg — the nested `{ open?, closed?, program? }` is the
131
+ * only shape `renderBody` reads, so any other shape (a flat array, `null`, a
132
+ * scalar) is refused with its field path instead of silently dropping the tail. An
133
+ * absent `related` stays legal. */
134
+ #relatedErrors(raw) {
135
+ if (raw === undefined)
136
+ return [];
137
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw))
138
+ return ["related: object with open / closed / program expected"];
139
+ const related = raw;
140
+ return [
141
+ ...this.#hitErrors("open", related.open),
142
+ ...this.#hitErrors("closed", related.closed),
143
+ ...(related.program === undefined
144
+ ? []
145
+ : this.#issueErrors("related.program", related.program, false)),
146
+ ];
147
+ }
148
+ /** The open / closed hit rows — the array shape plus every element's `issue` number
149
+ * (an open hit carries `component` / `reason` on top). */
150
+ #hitErrors(kind, raw) {
151
+ if (raw === undefined)
152
+ return [];
153
+ const base = `related.${kind}`;
154
+ if (!Array.isArray(raw))
155
+ return [`${base}: array of ${kind} hits expected`];
156
+ return raw.flatMap((hit, i) => this.#issueErrors(`${base}[${i}]`, hit, kind === "open"));
157
+ }
158
+ /** One `{ issue: number }` row — `withContext` adds the open hit's two string rows. */
159
+ #issueErrors(base, raw, withContext) {
160
+ const shape = withContext ? "issue / component / reason" : "issue";
161
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw))
162
+ return [`${base}: object with ${shape} required`];
163
+ const row = raw;
164
+ const errors = [];
165
+ if (typeof row.issue !== "number")
166
+ errors.push(`${base}.issue: number required`);
167
+ if (!withContext)
168
+ return errors;
169
+ for (const field of ["component", "reason"]) {
170
+ if (typeof row[field] !== "string" || row[field].length === 0)
171
+ errors.push(`${base}.${field}: non-empty string required`);
172
+ }
127
173
  return errors;
128
174
  }
129
175
  }
@@ -270,8 +270,13 @@ export const reviewGuideOf = (key) => {
270
270
  /** The spec-shaped documents' narrative criteria body — the phase-spec line's URC
271
271
  * + its program-conformance clause, the ONE body both spec-shaped target rows
272
272
  * select (the filled rubric is what differs per row). The charter's own criteria
273
- * body is `docCharterAxes` — never a second narrative copy alongside this one. */
274
- const docNarrativeAxes = (guide) => `Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity) + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + program conformance — judge the phase against its parent overall at \`INPUT_OVERALL\` (the charter its \`program:\` names): the phase must sit inside the scope the overall's Phase inventory registered for it, and a phase that reaches beyond it is a completeness finding. ${guide}`;
273
+ * body is `docCharterAxes` — never a second narrative copy alongside this one.
274
+ * The `Claimed→pin` clause names the three claim SHAPES a spec may state (a symbol,
275
+ * a guarded count, a condition that must hold) instead of accepting whatever shape
276
+ * today's tree happens to have: a line number is not a pin, a prose count is the
277
+ * guard's business, and a present-tense description of today's shape belongs to the
278
+ * plan. Nothing gates the writing moment — the review is where a violation surfaces. */
279
+ const docNarrativeAxes = (guide) => `Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity) + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin by module path + symbol name — a line number is not a pin; a count ("N places" · "N rows" · "N modules") must be stated as pinned by the named guard or test; a present-tense description of today's shape belongs to the plan — in a design spec a measurement input is a lens-tagged finding unless restated as a condition that must hold — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + program conformance — judge the phase against its parent overall at \`INPUT_OVERALL\` (the charter its \`program:\` names): the phase must sit inside the scope the overall's Phase inventory registered for it, and a phase that reaches beyond it is a completeness finding. ${guide}`;
275
280
  /** The charter's criteria body — the six things a program charter owns, and only
276
281
  * those. It carries none of the implementation-face evidence duty the narrative
277
282
  * body carries (running the repository's commands, pinning every claim): a charter
@@ -42,6 +42,10 @@ import { TargetFaceTable, targetFaces, } from "./faces.js";
42
42
  import { DISPATCH_REASON, PIPELINE_FACES, } from "./next.js";
43
43
  import { PipelineFrontier } from "./pipeline.js";
44
44
  import { WaveGate } from "./wave.js";
45
+ /** The stable prefix of one hash end in a refusal's diagnosis — long enough to tell the
46
+ * two ends apart at a glance, short enough for one line (§2.5 leaves the exact
47
+ * completeness to the implementation; the two ends must stay distinguishable). */
48
+ export const DRIFT_HASH_PREFIX = 12;
45
49
  /**
46
50
  * DispatchAuthority — the ONE dispatch verdict (§2.1/§2.2). One `verdict` call walks
47
51
  * the three legs in priority order and returns the single verdict the CLI renders,
@@ -49,7 +53,9 @@ import { WaveGate } from "./wave.js";
49
53
  *
50
54
  * Rule zero on the ≤200-line class cap (broke by design, not by accident): the three
51
55
  * legs are one short-circuit chain over one `next:` assembly — extracted, the chain's
52
- * order moves to a caller and a refusal can name a round another leg contradicts.
56
+ * order moves to a caller and a refusal can name a round another leg contradicts. The
57
+ * drift diagnosis (§2.5) rides the same chain: it is read off the hop the refusal
58
+ * already names, and its ONE rendering site is `message`.
53
59
  */
54
60
  export class DispatchAuthority {
55
61
  /** The wave face's five rows — this leg's wave judge (the judgment body stays in
@@ -71,15 +77,18 @@ export class DispatchAuthority {
71
77
  return this.#lineLeg(request);
72
78
  }
73
79
  /** message(verdict, render) — the ONE refusal line (§2.6): `reason · next: ` plus
74
- * the command the hop renders, or `reason · <wording>` on the structure leg. */
80
+ * the command the hop renders, or `reason · <wording>` on the structure leg. A drift
81
+ * refusal carries its mandatory diagnosis (§2.5) between the reason and the hop, so
82
+ * the CLI prints layer · line key · both hash ends without a second wording source. */
75
83
  message(verdict, render) {
84
+ const reason = _a.#driftReasonText(verdict);
76
85
  if (verdict.next === null) {
77
86
  return render.detail === undefined || render.detail === ""
78
- ? verdict.reason
79
- : `${verdict.reason} · ${render.detail}`;
87
+ ? reason
88
+ : `${reason} · ${render.detail}`;
80
89
  }
81
90
  const command = render.command === undefined ? "" : render.command(verdict.next);
82
- return `${verdict.reason} · next: ${command}`;
91
+ return `${reason} · next: ${command}`;
83
92
  }
84
93
  /** The structure leg's verdict — the seam's refusal re-expressed as this chain's
85
94
  * first row. Its token is the refusing gate's own id (the table's structure rows:
@@ -109,15 +118,42 @@ export class DispatchAuthority {
109
118
  const station = this.#stationOf(face, request.line);
110
119
  if (station === null)
111
120
  continue;
112
- const next = this.#hopOf(request.line);
113
- const reason = station === "drift" ? DISPATCH_REASON.docDrift.token : next.reason;
114
- return { allowed: false, leg: "upstream", reason, next };
121
+ return this.#stationRefusal(station, request.line);
115
122
  }
116
123
  return null;
117
124
  }
118
- /** One upstream face's station sign — ① first (a moved reviewed identity refuses as
119
- * `doc-drift` whatever the closure cell says), then ② (the face has not closed for
120
- * the request, so the frontier's own hop reason rules). */
125
+ /** One upstream station's refusal (§2.3/§2.4) — the reason and the `next:` are read
126
+ * off the SAME station sign: a moved brief names `brief-drift` and points at that
127
+ * batch's wave review (never the pipeline frontier's branch hop, which belongs to a
128
+ * different face's fact), a moved document names `doc-drift` and points at the
129
+ * frontier's own hop, and an unclosed face keeps the hop's own reason. */
130
+ #stationRefusal(station, facts) {
131
+ if (station.kind === "brief-drift") {
132
+ return this.#refusal("upstream", DISPATCH_REASON.briefDrift.token, this.#waveReviewHop(facts, station.batch), facts);
133
+ }
134
+ const next = this.#hopOf(facts);
135
+ const reason = station.kind === "doc-drift" ? DISPATCH_REASON.docDrift.token : next.reason;
136
+ return this.#refusal("upstream", reason, next, facts);
137
+ }
138
+ /** The wave review hop of a drifted batch (P29 §2.4) — the ONE assembly
139
+ * (`Ledger#nextHopOf`) with the moved-brief cell injected and the wave target of the
140
+ * FIRST drifted open batch, so the refusal's `next:` is `review --type wave --tasks
141
+ * <batch> --plan <plan>` and its reason is the brief's own token. */
142
+ #waveReviewHop(facts, batch) {
143
+ const planPath = facts.pipeline.planPath;
144
+ return facts.ledger.nextHopOf({
145
+ type: "wave",
146
+ key: batch,
147
+ route: { kind: "review" },
148
+ target: { type: "wave", id: batch, plan: planPath ?? undefined },
149
+ briefDrift: true,
150
+ docClassOf: facts.docClassOf,
151
+ });
152
+ }
153
+ /** One upstream face's station sign (§2.1/§2.3) — ① first (a moved reviewed identity
154
+ * refuses whatever the closure cell says), then ② (the face has not closed for the
155
+ * request, so the frontier's own hop reason rules). The wave face reports the
156
+ * BRIEF's movement, the doc faces the document's — two layers, two tokens. */
121
157
  #stationOf(face, facts) {
122
158
  if (face === "wave")
123
159
  return this.#waveStation(facts);
@@ -129,12 +165,18 @@ export class DispatchAuthority {
129
165
  if (!_a.#docEntered(ledger, line))
130
166
  return null;
131
167
  if (ledger.reviewGate(line.key, line.doc, line.type).kind === "open")
132
- return "drift";
133
- return ledger.lineStateAt(line.key, line.type, line.doc) === "closed" ? null : "open";
168
+ return { kind: "doc-drift" };
169
+ return ledger.lineStateAt(line.key, line.type, line.doc) === "closed" ? null : { kind: "open" };
134
170
  }
135
171
  /** The wave face's station — read off the SAME two judges the frontier runs, never a
136
172
  * local walk: entered over the three dispatch modes, drifted over the derived
137
- * batches' reviewed briefs, exhausted over `closedWaves()`. */
173
+ * batches' reviewed briefs, exhausted over `closedWaves()`.
174
+ *
175
+ * P29 §2.1 — the drift read is NOT retroactive: a batch whose tasks all sit in
176
+ * `closedWaves()` is filtered out before `briefDrifted` runs. A closed wave has no
177
+ * round left to reopen, so its stale brief is nobody's `next:` (the #438 face: a
178
+ * finished run's plan edit blocked the branch review). Only an OPEN batch's brief
179
+ * movement refuses the faces below the wave face. */
138
180
  #waveStation(facts) {
139
181
  const graph = facts.pipeline.planGraph;
140
182
  if (graph === null)
@@ -142,10 +184,25 @@ export class DispatchAuthority {
142
184
  const frontier = this.#frontierOf(facts);
143
185
  if (!frontier.wavesEntered(graph))
144
186
  return null;
145
- const drifted = graph.batches().some((batch) => facts.ledger.briefDrifted(batch.join(",")));
146
- if (drifted)
147
- return "drift";
148
- return frontier.wavesExhausted(graph) ? null : "open";
187
+ const batch = _a.#firstDriftedOpenBatch(graph, facts.ledger);
188
+ if (batch !== null)
189
+ return { kind: "brief-drift", batch };
190
+ return frontier.wavesExhausted(graph) ? null : { kind: "open" };
191
+ }
192
+ /** The FIRST open batch whose task-only brief moved (`graph.batches()` order — the
193
+ * ONE order §2.4 makes executable) — null when every batch is either closed or
194
+ * undrifted. The closure cell is `closedWaves()`, the same read the frontier's
195
+ * exhaustion uses: a batch is closed when every one of its tasks is. */
196
+ static #firstDriftedOpenBatch(graph, ledger) {
197
+ const closed = ledger.closedWaves();
198
+ for (const batch of graph.batches()) {
199
+ if (batch.every((id) => closed.has(id)))
200
+ continue;
201
+ const key = batch.join(",");
202
+ if (ledger.briefDrifted(key))
203
+ return key;
204
+ }
205
+ return null;
149
206
  }
150
207
  /** The line leg — this line's phase against the requested one, with the refusal's
151
208
  * `next` read from the pipeline frontier only when the line actually refuses. */
@@ -155,7 +212,58 @@ export class DispatchAuthority {
155
212
  return { allowed: true };
156
213
  const next = this.#hopOf(request.line);
157
214
  const reason = ruling.kind === "row" ? ruling.reason : next.reason;
158
- return { allowed: false, leg: "line", reason, next };
215
+ return this.#refusal("line", reason, next, request.line);
216
+ }
217
+ /** One refusal, with its drift diagnosis attached when the reason is a drift token
218
+ * (§2.5 — one construction point, so no refusal has a second path to print by). The
219
+ * diagnosis reads the identity the hop itself names (`NextHop.target`), never a
220
+ * second lookup of which line moved. It is absent exactly when the target records no
221
+ * pair — a diagnosis never invents a fact, so an underivable identity prints the
222
+ * bare token. */
223
+ #refusal(leg, reason, next, facts) {
224
+ const drift = _a.#isDriftReason(reason)
225
+ ? _a.#driftOf(next, facts)
226
+ : undefined;
227
+ return drift === undefined
228
+ ? { allowed: false, leg, reason, next }
229
+ : { allowed: false, leg, reason, next, drift };
230
+ }
231
+ /** Whether a token names a moved reviewed identity — the two rows whose refusal line
232
+ * must carry the diagnosis (§2.5). */
233
+ static #isDriftReason(reason) {
234
+ return reason === DISPATCH_REASON.briefDrift.token || reason === DISPATCH_REASON.docDrift.token;
235
+ }
236
+ /** The diagnosis of the hop's OWN render target (§2.5) — a wave target is judged on
237
+ * its brief's task-only projection, every doc shape on its document revision, and the
238
+ * hop's target is the identity the refusal already names (never a second lookup of
239
+ * which line moved). Undefined when the target holds no identity on record: a
240
+ * diagnosis never invents a fact. */
241
+ static #driftOf(next, facts) {
242
+ const target = next.target;
243
+ if (target === null)
244
+ return undefined;
245
+ const brief = target.type === "wave";
246
+ const pair = brief
247
+ ? facts.ledger.briefDriftHashes(String(target.id))
248
+ : _a.#docDriftPair(target, facts);
249
+ return pair === null ? undefined : { layer: brief ? "brief" : "doc", ...pair };
250
+ }
251
+ /** The doc target's diagnosis read — the target's own type is the ledger key of the
252
+ * line it renders (`plan` / `branch` / the declared spec word), and a branch target
253
+ * carries its document in `plan`, every other shape in `id`. */
254
+ static #docDriftPair(target, facts) {
255
+ const doc = target.type === "branch" ? (target.plan ?? null) : target.id;
256
+ return doc === null ? null : facts.ledger.docDriftHashes(target.type, doc, target.type);
257
+ }
258
+ /** The refusal line's reason head — the token alone, or the token plus the mandatory
259
+ * diagnosis (§2.5): `layer=` · `line=` · `recorded=` · `current=` with a stable hash
260
+ * prefix per end. ONE rendering site, so the CLI cannot print a second wording. */
261
+ static #driftReasonText(verdict) {
262
+ const drift = verdict.drift;
263
+ if (drift === undefined)
264
+ return verdict.reason;
265
+ const prefix = (hash) => hash.slice(0, DRIFT_HASH_PREFIX);
266
+ return `${verdict.reason} · layer=${drift.layer} · line=${drift.line} · recorded=${prefix(drift.recorded)} · current=${prefix(drift.current)}`;
159
267
  }
160
268
  /** The wave face's rows — the three-verb gate judged whole (its order IS the
161
269
  * judgment: a shape matching an earlier row keeps that earlier row's cause). */
@@ -137,8 +137,8 @@ const RETIRED_SPEC_LINE_KEYS = new Set([
137
137
  ]);
138
138
  /**
139
139
  * ReviewRefs — the review-reference face (T25): the two-layer bindings (`docRevision`
140
- * — the doc hash from its content · `briefRevision` — the rendered brief's hash from
141
- * the plan it renders from) and the same-ref predicate (the SAME identity already
140
+ * — the doc hash from its content · `briefRevision` — the wave's task-only projection
141
+ * hash from the plan it renders from) and the same-ref predicate (the SAME identity already
142
142
  * bound is refused, never silently re-reviewed). The face is the ledger's review-ref
143
143
  * derivation point — typed data, zero prose.
144
144
  */
@@ -153,8 +153,10 @@ export class ReviewRefs {
153
153
  const projected = new DocBodyProjection().project(body);
154
154
  return { kind: "doc-revision", doc, doc_hash: this.#hash(projected) };
155
155
  }
156
- /** The brief-revision two-layer binding (D30) — the plan path the brief renders
157
- * from + the RENDERED brief content's hash (the wave line's reviewed identity). */
156
+ /** The brief-revision two-layer binding (D30, narrowed by P29 §2.2) — the plan path
157
+ * the brief renders from + the hash of the brief's TASK-ONLY projection (the wave
158
+ * line's reviewed identity; `## Constraints` is dispatch input, not a fingerprint
159
+ * byte). */
158
160
  briefRevision(plan, briefContent) {
159
161
  return { kind: "brief-revision", plan, brief_hash: this.#hash(briefContent) };
160
162
  }
@@ -205,9 +207,11 @@ export class Ledger {
205
207
  * through the same face). Injected with this ledger's own ref face, so the
206
208
  * same-ref predicate keeps one definition. */
207
209
  #identity = new LineIdentity(this.#refs);
208
- /** The task-brief renderer (D30) — the wave line's judgment-input derivation:
209
- * the wave's reviewed basis is the RENDERED brief's content, never the whole
210
- * plan (a backfill touching other tasks must not void a reviewed wave). */
210
+ /** The task-brief renderer (D30 · P29 §2.2) — the wave line's judgment-input
211
+ * derivation: the wave's reviewed basis is the TASK-ONLY projection
212
+ * (`BriefRenderer#taskBody`), never the whole plan and never the `## Constraints`
213
+ * dispatch input (a backfill touching other tasks, or a Constraints reword, must
214
+ * not void a reviewed wave). */
211
215
  #brief = new BriefRenderer();
212
216
  /** The round-naming single source over this ledger's workspace — the crash
213
217
  * artifact names derive here (zero second derivation). */
@@ -414,27 +418,27 @@ export class Ledger {
414
418
  row.reviewedRevision = revision;
415
419
  this.writeProgress(data);
416
420
  }
417
- /** Record a wave line's reviewed BRIEF revision (D30) — the RENDERED brief's
418
- * content hash for the wave's tasks: the wave's true judgment input is the brief
419
- * (§5: the wave's task sections + the plan's `## Constraints`), never the whole
420
- * plan. A backfill touching OTHER tasks leaves this brief byte-identical, so the
421
- * reviewed wave is not spuriously reopened (the backfill's whole point). An
421
+ /** Record a wave line's reviewed BRIEF revision (D30) — the hash of the wave's
422
+ * TASK-ONLY projection (P29 §2.2: the task sections, `## Constraints` excluded).
423
+ * A backfill touching OTHER tasks leaves this projection byte-identical, and so
424
+ * does a Constraints reword, so the reviewed wave is not spuriously reopened. An
422
425
  * underivable brief records nothing (present facts only — the legacy face holds). */
423
426
  recordReviewedBrief(waveKey, planPath) {
424
427
  const revision = this.#briefRevision(waveKey, planPath);
425
428
  if (revision !== null)
426
429
  this.recordReviewedRevision(waveKey, revision);
427
430
  }
428
- /** The wave line's reviewed-basis revision (D30) — the RENDERED brief's content
429
- * hash for the wave's tasks (the `plan` layer is the plan the brief renders from,
430
- * the `brief_hash` layer the brief's own digest). Null when the plan is unreadable
431
+ /** The wave line's reviewed-basis revision (D30) — the hash of the wave's TASK-ONLY
432
+ * projection (`BriefRenderer#taskBody`: the task sections, `## Constraints`
433
+ * excluded — P29 §2.2). The `plan` layer is the plan the brief renders from, the
434
+ * `brief_hash` layer the projection's own digest. Null when the plan is unreadable
431
435
  * or a requested task is absent (present facts only). */
432
436
  #briefRevision(waveKey, planPath) {
433
437
  try {
434
438
  const tasks = waveKey.split(",").map((part) => Number(part));
435
439
  // The plan layer is stored repoRoot-relative (P9 T4 §2.7) — one basis with
436
440
  // every persisted path field; the read erases to absolute at the syscall edge.
437
- const brief = this.#brief.render(readFileSync(this.#abs(planPath), "utf8"), tasks);
441
+ const brief = this.#brief.taskBody(readFileSync(this.#abs(planPath), "utf8"), tasks);
438
442
  return this.#refs.briefRevision(this.#rel(planPath), brief);
439
443
  }
440
444
  catch {
@@ -492,6 +496,19 @@ export class Ledger {
492
496
  * is on record or the doc is unreadable (the legacy closed face keeps its
493
497
  * generic message — only present facts land). */
494
498
  docLineVerdict(key, doc, identity = null) {
499
+ const pair = this.#docRevisionPair(key, doc, identity);
500
+ if (pair === null)
501
+ return null;
502
+ return this.#identity.verdict(pair.reviewed, { ref: pair.current }) === "same"
503
+ ? "same"
504
+ : "drift";
505
+ }
506
+ /** The doc line's two revision sides — the recorded reviewed revision and the one
507
+ * the document holds NOW (null when no reviewed revision is on record or the doc is
508
+ * unreadable). ONE read for TWO consumers: the drift verdict (`docLineVerdict`) and
509
+ * the refusal's mandatory diagnosis (`docDriftHashes`), so the two can never
510
+ * compare different bytes. */
511
+ #docRevisionPair(key, doc, identity) {
495
512
  const reviewed = this.reviewedDocRevisionOf(key, identity);
496
513
  if (reviewed === null)
497
514
  return null;
@@ -501,12 +518,35 @@ export class Ledger {
501
518
  // false-drift comparison never reads one document as two.
502
519
  const rel = this.#rel(doc);
503
520
  const current = this.#refs.docRevision(rel, readFileSync(this.#abs(doc), "utf8"));
504
- return this.#identity.verdict(reviewed, { ref: current }) === "same" ? "same" : "drift";
521
+ return { reviewed, current };
505
522
  }
506
523
  catch {
507
524
  return null;
508
525
  }
509
526
  }
527
+ /** The doc line's drift diagnosis (§2.5) — the layer's line key (the document path
528
+ * the review bound, on the ONE persisted basis) and both hash ends. Null when there
529
+ * is no recorded revision or the document is unreadable: a diagnosis never invents
530
+ * a fact. */
531
+ docDriftHashes(key, doc, identity = null) {
532
+ const pair = this.#docRevisionPair(key, doc, identity);
533
+ if (pair === null)
534
+ return null;
535
+ return {
536
+ line: pair.reviewed.doc,
537
+ recorded: pair.reviewed.doc_hash,
538
+ current: pair.current.doc_hash,
539
+ };
540
+ }
541
+ /** The wave line's drift diagnosis (§2.5) — the line key is the wave batch key, the
542
+ * hashes are the recorded vs current TASK-ONLY brief projections. Null when the row
543
+ * holds no brief identity or the plan's task section is underivable. */
544
+ briefDriftHashes(waveKey) {
545
+ const pair = this.#briefRevisionPair(waveKey);
546
+ if (pair === null)
547
+ return null;
548
+ return { line: waveKey, recorded: pair.reviewed.brief_hash, current: pair.current.brief_hash };
549
+ }
510
550
  /** The review-gate method (T8 · §3.5) — the doc line's review request judgment +
511
551
  * the phase advance: the shared docLineVerdict comparison reports the drift, and
512
552
  * the REOPEN's scope is the callers' ONE judgment (`Ledger#docReopens` — an
@@ -540,7 +580,7 @@ export class Ledger {
540
580
  * blockers outstanding) is the one-way fix hop carrying the source review's handoff
541
581
  * path. Null when the wave line holds no open hop (drained / deferred by the soft
542
582
  * cap). The D16/T11 revision precheck belongs HERE, not in a per-consumer copy: a
543
- * completed wave review bound the RENDERED BRIEF it judged to the row (run.ts
583
+ * completed wave review bound the BRIEF's task-only projection to the row (run.ts
544
584
  * bookkeep `#recordReviewedWaveBrief` → `#briefRevision`), and a drifted BRIEF
545
585
  * reopens the wave at review regardless of the fix-awaited round state (the
546
586
  * stale-revision findings are voided — new revision, new review). Same revision + a
@@ -601,24 +641,37 @@ export class Ledger {
601
641
  return "fix";
602
642
  return null;
603
643
  }
604
- /** The wave line's brief-drift verdict (D30) — the wave's CURRENT rendered brief
605
- * vs the recorded reviewed brief. `true` when the wave's judgment input moved past
606
- * the reviewed basis (the wave reopens at review). A plan edit OUTSIDE the wave's
607
- * task sections + `## Constraints` leaves the brief byte-identical → `false`
608
- * (the append-only backfill case the whole-plan hash wrongly flagged). An
609
- * underivable brief (unreadable plan / absent task) is not a drift (present
610
- * facts only). A row bound to a non-brief kind (a doc kind, only via a corrupt
611
- * hand-write) is not a wave brief — no drift. The ONE public read of the fact:
612
- * `waveLineRoute`'s D30 leg and the next-hop assembly's reason-only `briefDrift`
613
- * cell both come through here. */
644
+ /** The wave line's brief-drift verdict (D30) — the wave's CURRENT task-only
645
+ * projection (P29 §2.2) vs the recorded reviewed projection. `true` when the
646
+ * wave's judgment input moved past the reviewed basis (the wave reopens at
647
+ * review). A plan edit outside the wave's task sections — a `## Constraints`
648
+ * reword included, since Constraints is dispatch input rather than a fingerprint
649
+ * byte — leaves the task-only projection byte-identical → `false` (the
650
+ * append-only backfill case the whole-plan hash wrongly flagged). An underivable
651
+ * brief (unreadable plan / absent task) is not a drift (present facts only). A
652
+ * row bound to a non-brief kind (a doc kind, only via a corrupt hand-write) is
653
+ * not a wave brief — no drift. The ONE public read of the fact: `waveLineRoute`'s
654
+ * D30 leg and the next-hop assembly's reason-only `briefDrift` cell both come
655
+ * through here. */
614
656
  briefDrifted(waveKey) {
657
+ const pair = this.#briefRevisionPair(waveKey);
658
+ if (pair === null)
659
+ return false;
660
+ return this.#identity.verdict(pair.reviewed, { ref: pair.current }) === "drift";
661
+ }
662
+ /** The wave line's two brief-projection sides — the recorded task-only revision and
663
+ * the one the plan renders NOW (null when the row holds no brief identity or the
664
+ * plan is unreadable / a requested task is absent). ONE read for TWO consumers: the
665
+ * drift predicate (`briefDrifted`) and the refusal's diagnosis
666
+ * (`briefDriftHashes`), so neither can hash a different projection. */
667
+ #briefRevisionPair(waveKey) {
615
668
  const reviewed = this.reviewedRevisionOf(waveKey);
616
669
  if (reviewed === null || reviewed.kind !== "brief-revision")
617
- return false;
670
+ return null;
618
671
  const current = this.#briefRevision(waveKey, reviewed.plan);
619
672
  if (current === null)
620
- return false;
621
- return this.#identity.verdict(reviewed, { ref: current }) === "drift";
673
+ return null;
674
+ return { reviewed, current };
622
675
  }
623
676
  /** The pending-fix derivation — the "doc same + not APPROVED" face (T8): the
624
677
  * latest review round has an outstanding fix AND its conclusion was not an
@@ -814,9 +867,10 @@ export class Ledger {
814
867
  * `reviewGate`); the injected `briefDrift` cell never moves a route — a wave's
815
868
  * exit-side station (`handoff`) is never rewritten into a review;
816
869
  * · the REASON cell adds the caller-injected wave brief-drift fact to that
817
- * verdict, so a drifted wave names `doc-drift` without a second judgment.
870
+ * verdict, so a drifted wave names `brief-drift` without a second judgment —
871
+ * the document's own movement keeps `doc-drift` (§2.3: two facts, two tokens).
818
872
  * The ONE exception to the route being the caller's is the drift-reopened doc
819
- * line: the gate's `drift` verdict IS its reopen, and the closure-side route the
873
+ * line: the gate's `docDrift` verdict IS its reopen, and the closure-side route the
820
874
  * count table recorded predates the document movement — so the assembly hands the
821
875
  * derivation the reopened review hop in that case. A presentation-level
822
876
  * substitution: the count table's judgment (`NextStepRouter#next`) stays the only
@@ -837,13 +891,14 @@ export class Ledger {
837
891
  // The face axis is the ONE verdict this assembly reads (spec §5.2's doc-class
838
892
  // discrimination): no target carries no judgeable class (the bare terminal).
839
893
  const verdict = input.target === null ? "terminal" : input.docClassOf(input.target);
840
- // The REASON cell's drift value — `drift` above plus the caller-injected wave
841
- // brief-drift fact. The two are kept apart: only `drift` drives the route
842
- // substitution, so a wave's exit-side station keeps its bytes while its `reason:`
843
- // row still names the movement.
894
+ // The REASON cell's drift values — the doc verdict plus the caller-injected wave
895
+ // brief-drift fact, each landing on ITS own boolean (§2.3). The two are kept
896
+ // apart: only `docDrift` drives the route substitution, so a wave's exit-side
897
+ // station keeps its bytes while its `reason:` row still names the movement — and
898
+ // names it with the brief's own token, never the document's.
844
899
  return this.#router.nextHop({
845
900
  target: input.target,
846
- gate: { drift: drift || (input.briefDrift ?? false) },
901
+ gate: { docDrift: drift, briefDrift: input.briefDrift ?? false },
847
902
  verdict,
848
903
  route,
849
904
  nextLineOpen: input.nextLineOpen,
@@ -5,8 +5,9 @@
5
5
  // single identity face all three read:
6
6
  // · spec / plan — the document's `doc-revision` (a hash of the BODY: front matter
7
7
  // and `## Change history` are projected away, P26 T1);
8
- // · wave — the RENDERED brief's `brief-revision` (its task sections plus the
9
- // plan's `## Constraints` — a plan edit elsewhere is not a drift);
8
+ // · wave — the RENDERED brief's `brief-revision` over its TASK-ONLY
9
+ // projection (P29 §2.2: `## Constraints` is dispatch input, never a
10
+ // fingerprint byte — a plan edit elsewhere is not a drift);
10
11
  // · branch — its plan document's `doc-revision` (the SAME kind, no new ref
11
12
  // kind, no commit sha — the ledger keeps no second code identity).
12
13
  //
@@ -99,6 +99,9 @@ export const DISPATCH_REASON = {
99
99
  closedLine: { token: "closed-line", leg: "line" },
100
100
  faceClosed: { token: "face-closed", leg: "line" },
101
101
  // station — the signs a `next:` hop is named by
102
+ /** A wave line's TASK-ONLY projection moved past the one its review bound. */
103
+ briefDrift: { token: "brief-drift", leg: "station" },
104
+ /** A document's revision moved past the one its review bound. */
102
105
  docDrift: { token: "doc-drift", leg: "station" },
103
106
  softCap: { token: "soft-cap", leg: "station" },
104
107
  taskOpen: { token: "task-open", leg: "station" },
@@ -114,8 +117,12 @@ export const WAVE_GATE_REASON = {
114
117
  wrongPhase: DISPATCH_REASON.wrongPhase.token,
115
118
  };
116
119
  /** The named accessors for `NextHop.reason` — every value is the table's own token
117
- * (one spelling source; the hop reason domain spans both the line and station legs). */
120
+ * (one spelling source; the hop reason domain spans both the line and station legs).
121
+ * `briefDrift` and `docDrift` are TWO facts, never one: a wave brief's task-only
122
+ * projection vs a document's revision (§2.3), so a reader never has to guess which
123
+ * identity moved from the token alone. */
118
124
  export const NEXT_HOP_REASON = {
125
+ briefDrift: DISPATCH_REASON.briefDrift.token,
119
126
  docDrift: DISPATCH_REASON.docDrift.token,
120
127
  pendingFix: DISPATCH_REASON.pendingFix.token,
121
128
  closedLine: DISPATCH_REASON.closedLine.token,
@@ -281,15 +288,19 @@ export class NextStepRouter {
281
288
  }
282
289
  /** The named fact behind the hop — one `NEXT_HOP_REASON` row, in this order: the
283
290
  * soft cap · a pending fix · a drift-reopened line (its reviewed identity moved —
284
- * a doc revision or a wave's brief revision) · an open line advancing · an
285
- * unjudgeable doc class · a closed face · the closed line's handoff. Drift never
286
- * outranks a pending fix (an unclosed line's blocker keeps the fix hop). */
291
+ * the wave brief's task-only projection, or a document's revision) · an open line
292
+ * advancing · an unjudgeable doc class · a closed face · the closed line's handoff.
293
+ * Drift never outranks a pending fix (an unclosed line's blocker keeps the fix hop),
294
+ * and the two drift kinds never share a token: the wave brief's movement is
295
+ * `brief-drift`, a document revision's is `doc-drift` (§2.3). */
287
296
  #reasonOf(input, route, verdict) {
288
297
  if (route?.kind === "soft-cap")
289
298
  return NEXT_HOP_REASON.softCap;
290
299
  if (route?.kind === "fix")
291
300
  return NEXT_HOP_REASON.pendingFix;
292
- if (route?.kind === "review" && input.gate.drift)
301
+ if (route?.kind === "review" && input.gate.briefDrift)
302
+ return NEXT_HOP_REASON.briefDrift;
303
+ if (route?.kind === "review" && input.gate.docDrift)
293
304
  return NEXT_HOP_REASON.docDrift;
294
305
  if (route !== null && this.hopOf(route, _a.#faceOf(verdict)) !== null)
295
306
  return NEXT_HOP_REASON.taskOpen;
@@ -518,20 +518,22 @@ export class Lifecycle {
518
518
  /** The reviewed-revision write-back — bind the completed round's input revision to
519
519
  * the line record (the T7 doc + D30 wave identity gates' reopen-compare basis). The
520
520
  * doc face binds its target doc's BODY revision (the front matter and
521
- * `## Change history` projected away, P26 T1); the wave face binds its
522
- * RENDERED BRIEF's revision (D30 — the wave's true judgment input is the brief,
523
- * never the whole plan: transcript edits outside the wave's task sections must not
524
- * void a reviewed wave). An unreadable input records nothing — the line keeps the
521
+ * `## Change history` projected away, P26 T1); the wave face binds its TASK-ONLY
522
+ * brief projection's revision (D30 · P29 §2.2 — the wave's true judgment input is
523
+ * the brief's task sections, never the whole plan and never the `## Constraints`
524
+ * dispatch input: transcript edits outside the wave's task sections must not void a
525
+ * reviewed wave). An unreadable input records nothing — the line keeps the
525
526
  * legacy closed face (only present facts land, never an invented identity). */
526
527
  #recordReviewedDocRevision(frame) {
527
528
  if (frame.target.kind !== "plan" && frame.target.kind !== "spec")
528
529
  return;
529
530
  this.#recordDocRevisionOf(frame.key, frame.target.doc, frame.type);
530
531
  }
531
- /** The wave line's reviewed-brief write-back (D30) — bind the RENDERED brief's
532
- * revision for the wave's tasks to the row (the D30 wave-gate reopen basis) on a
533
- * completed review or fix round. Null plan path / underivable brief records nothing
534
- * (present facts only). */
532
+ /** The wave line's reviewed-brief write-back (D30 · P29 §2.2) — bind the wave's
533
+ * TASK-ONLY projection revision (`BriefRenderer#taskBody` — the same face the
534
+ * lifecycle hashes) to the row (the D30 wave-gate reopen basis) on a completed
535
+ * review or fix round. Null plan path / underivable brief records nothing (present
536
+ * facts only). */
535
537
  #recordReviewedWaveBrief(frame) {
536
538
  if (frame.target.kind !== "wave" || this.#planPath === null)
537
539
  return;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "4.5.0",
3
+ "version": "4.7.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {