@oscaner-skills/cdd-engine 4.10.0 → 4.12.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.
@@ -0,0 +1,359 @@
1
+ // packages/cdd-engine/src-next/infra/plan-source.ts
2
+ // Task 2 — the plan read + parse + classify seam (design spec §2.1 · §2.4 · §2.7):
3
+ // ONE deep class (`PlanSource`) with TWO entries — the derived face (`readFor`,
4
+ // `entry.slug` → `${docRoots.plans}/<slug>.md`) and the argv face (`readPath`) —
5
+ // and ONE value (`PlanRead`) that carries the behaviour the seven call sites used
6
+ // to re-spell. The tri-state is a class (a private discriminant field + a `kind`
7
+ // getter + the accessors), never a bare discriminated union: no consumer writes
8
+ // `switch (read.kind)` to recover a fact the value already owns.
9
+ //
10
+ // · The path basis is the `RepoRoot` conversion pair: every `DocFs` call takes
11
+ // `root.resolve(root.relativize(rel))`, so a plan under a repository sub-
12
+ // directory reads against the injected root — never `process.cwd()` (NodeFs
13
+ // resolves a literal against the process cwd, which would silently read a
14
+ // healthy plan as unreadable).
15
+ // · `undeclared` has exactly one producer — the derived face's own read (a null
16
+ // slug, or a derived path that is not on disk). There is no `undeclared`
17
+ // factory: "this phase has no plan yet" is a real read result, not a value a
18
+ // caller can mint. `readPath` never probes existence, so an absent argv path
19
+ // is an io read failure — the dispatch face keeps today's usage bytes.
20
+ // · The reverse lookup is part of the READ (§2.7): whether `<slug>-design.md`
21
+ // exists decides if this plan names a phase. It is a read fact, not a doc-shape
22
+ // violation — zero rules registered, zero `Finding`, zero new `kind` token. It
23
+ // runs on the argv face only (`readFor`'s entry IS the identity document, so
24
+ // `spec-absent` is structurally unreachable there) and it only probes
25
+ // existence (`DocFs.exists`), never a content predicate. The probe sits in the
26
+ // `readPath` entry itself, NOT in the shared read tail: the derived face passes
27
+ // `null`, so "the derived face never reverse-looks-up" is a fact of the seam
28
+ // rather than a flag each call site has to keep straight.
29
+ //
30
+ // Module-level exports are types / the class family — zero behavior-carrying bare
31
+ // functions (the plan's zero-bare-function discipline).
32
+ import { DocSyntaxError, PlanDocType } from "../contract/doc.js";
33
+ import { FrontMatterExtractor } from "../contract/frontmatter.js";
34
+ import { NodeFs } from "../contract/invariants.js";
35
+ import { TaskGraph } from "../session/graph.js";
36
+ import { ENGINE_RUNTIME } from "./runtime.js";
37
+ import { SlugIndex } from "./slug-index.js";
38
+ /** The state brand: a module-private symbol key that `PlanRead`'s constructor
39
+ * requires, so "exactly one producer family" is judged by `tsc` rather than by a
40
+ * comment. The symbol is not exported, therefore no other module can spell the key
41
+ * and a structural object literal there fails to type-check; every mint lives in
42
+ * this file (`PlanSource`'s three states and the fallbacks it threads). */
43
+ const READ_STATE_BRAND = Symbol("cdd.plan-read-state");
44
+ /** The undeclared doc-face wave row (`(none)` — today's bytes for "no plan yet"). */
45
+ const UNDECLARED_WAVE = "(none)";
46
+ /** The cell separator of the plan row (`<path> · <mark>`). */
47
+ const MARK_SEPARATOR = " · ";
48
+ /**
49
+ * PlanRead — the plan read value, one per document read. Every accessor answers one
50
+ * question the call sites used to re-derive with a `switch`; the producer's share is
51
+ * the degradation literal only (a healthy row / a healthy cell returns `null`, and
52
+ * the assembler keeps its byte-identical path).
53
+ */
54
+ export class PlanRead {
55
+ /** The private discriminant — the state is the single source of every accessor. */
56
+ #state;
57
+ /** The constructor takes the branded state, so a `PlanRead` can only be built from
58
+ * a value minted in this module — the single-producer claim is a type, not a
59
+ * convention. */
60
+ constructor(state) {
61
+ this.#state = state;
62
+ }
63
+ /** The tri-state discriminant (`undeclared` / `unreadable` / `ready`). */
64
+ get kind() {
65
+ return this.#state.kind;
66
+ }
67
+ /** The plan row's fact (§2.1): `undeclared` → null; `unreadable` and `ready` →
68
+ * the path (unreadable does not mean pathless). An empty string would disguise
69
+ * "no document" as "an empty path" and render half a plan row. */
70
+ path() {
71
+ const state = this.#state;
72
+ return state.kind === "undeclared" ? null : state.path;
73
+ }
74
+ /** The frontier's path (§2.1 · §2.5): the document reads out (its front matter
75
+ * parsed), NOT "it parses into a graph". `undeclared` → null (no document);
76
+ * `io` → null (no slug key, so no face is assemblable); `syntax` → the path (the
77
+ * front matter read out, the plan face assembles, and its doc-contract refusal
78
+ * is exactly the next face to point at); `ready` → the path. This is today's
79
+ * per-cause distribution, now a value behaviour. */
80
+ stationPath() {
81
+ const state = this.#state;
82
+ if (state.kind === "ready")
83
+ return state.path;
84
+ if (state.kind === "unreadable" && state.cause === "syntax")
85
+ return state.path;
86
+ return null;
87
+ }
88
+ /** The failure's three facts, the ONE place they are taken from; null unless the
89
+ * read was `unreadable`. The rendered sentence is the word port's, not this
90
+ * value's. */
91
+ failure() {
92
+ const state = this.#state;
93
+ if (state.kind !== "unreadable")
94
+ return null;
95
+ return { path: state.path, cause: state.cause, field: state.field };
96
+ }
97
+ /** The document text (the wave brief's and `#targetSlug`'s source); null when not ready. */
98
+ text() {
99
+ const state = this.#state;
100
+ return state.kind === "ready" ? state.text : null;
101
+ }
102
+ /** The parsed document (the brief's data face); null when not ready. */
103
+ doc() {
104
+ const state = this.#state;
105
+ return state.kind === "ready" ? state.doc : null;
106
+ }
107
+ /** The ready read's two document values in ONE hand-off — the kind contract
108
+ * written in the type, so a caller that already guarded `kind` never re-narrows
109
+ * what the read decided. `text` and `doc` are non-null exactly when `kind` is
110
+ * `ready`; any other kind is a BROKEN invariant (the caller's guard is the only
111
+ * legal entry), so it throws instead of degrading the fact to "no document". */
112
+ document() {
113
+ const state = this.#state;
114
+ if (state.kind !== "ready")
115
+ throw new Error("cdd: a plan read outside the ready state carries no document");
116
+ return { text: state.text, doc: state.doc };
117
+ }
118
+ /** The task graph (the gate's / frontier's / board's one graph input), derived
119
+ * eagerly from the same parse; null when not ready. */
120
+ graph() {
121
+ const state = this.#state;
122
+ return state.kind === "ready" ? state.graph : null;
123
+ }
124
+ /** The reverse-lookup read fact (§2.7); only an argv-face `ready` read can carry one. */
125
+ orphan() {
126
+ const state = this.#state;
127
+ return state.kind === "ready" ? state.orphan : null;
128
+ }
129
+ /** The board's wave data; the empty set when not ready (an empty set is NOT a
130
+ * render signal — `degradedWaveRow` / `cell` own the literals). */
131
+ waves() {
132
+ const state = this.#state;
133
+ return state.kind === "ready" ? state.graph.batches() : [];
134
+ }
135
+ /** The doc-face wave row's degradation literal (§2.4 + the §2.7 fold); null means
136
+ * "the healthy row is the assembler's", never "nothing to show". */
137
+ degradedWaveRow(words) {
138
+ return this.#degradedWord(words, UNDECLARED_WAVE);
139
+ }
140
+ /** The program-face wave cell's literal (§2.4 + the §2.7 fold); `""` is the
141
+ * undeclared program cell only, and null again hands the healthy cell back. */
142
+ cell(words) {
143
+ return this.#degradedWord(words, words.cellEmpty);
144
+ }
145
+ /** The plan row's cell content (§2.1): the degraded shapes carry the path plus
146
+ * the mark; a healthy `ready` is the bare path; `undeclared` / `slug-absent`
147
+ * return null (the row falls back to the existing identity bookkeeping). */
148
+ planLine(words) {
149
+ const state = this.#state;
150
+ if (state.kind === "undeclared")
151
+ return null;
152
+ if (state.kind === "unreadable")
153
+ return `${state.path}${MARK_SEPARATOR}${words.planReadWord(state.cause)}`;
154
+ const cause = this.#orphanCause();
155
+ if (cause === "spec-absent")
156
+ return `${state.path}${MARK_SEPARATOR}${words.planOrphanWord()}`;
157
+ if (cause === "slug-absent")
158
+ return null;
159
+ return state.path;
160
+ }
161
+ /** The spec row's cell content — the spec-absent orphan only; every other state
162
+ * (healthy, non-ready, `slug-absent`, undecided) returns null. */
163
+ specLine(words) {
164
+ return this.#orphanCause() === "spec-absent" ? words.planOrphanWord() : null;
165
+ }
166
+ /** The board's `CDD_WARN:` line (stderr): the two unreadable causes, the
167
+ * `spec-absent` orphan and the `slug-absent` fact each produce one; `undeclared`
168
+ * and a healthy `ready` produce null ("no plan yet" is normal, not a failure). */
169
+ warnLine(words) {
170
+ const diagnostic = this.#diagnostic(words);
171
+ return diagnostic === null ? null : `${words.warnPrefix} ${diagnostic}`;
172
+ }
173
+ /** The pre-flight refusal (§2.3): the two unreadable causes and the spec-absent
174
+ * orphan; `slug-absent` is stopped earlier by the identity channel and the
175
+ * healthy / undeclared states have nothing to refuse. */
176
+ refusal(words) {
177
+ const state = this.#state;
178
+ const message = state.kind === "unreadable"
179
+ ? this.#failureWords(words, state)
180
+ : this.#orphanCause() === "spec-absent"
181
+ ? this.#orphanWords(words)
182
+ : null;
183
+ return message === null ? null : { gate: "doc-contract", reason: "doc-contract", message };
184
+ }
185
+ // -------------------------------------------------------------------------
186
+ // the private behaviour — one place per semantic
187
+ // -------------------------------------------------------------------------
188
+ /** The degraded literal both faces share; the undeclared word is the only cell
189
+ * the two faces spell differently (`(none)` vs the empty program cell). */
190
+ #degradedWord(words, undeclared) {
191
+ const state = this.#state;
192
+ if (state.kind === "undeclared")
193
+ return undeclared;
194
+ if (state.kind === "unreadable")
195
+ return words.planReadWord(state.cause);
196
+ const cause = this.#orphanCause();
197
+ if (cause === "spec-absent")
198
+ return words.planOrphanWord();
199
+ if (cause === "slug-absent")
200
+ return null;
201
+ return state.doc.taskBlocks.length === 0 ? words.planEmptyWord() : null;
202
+ }
203
+ /** The ready state's orphan cause, or null (non-ready / healthy / undecided). */
204
+ #orphanCause() {
205
+ const state = this.#state;
206
+ if (state.kind !== "ready")
207
+ return null;
208
+ return state.orphan?.cause ?? null;
209
+ }
210
+ /** The ready state's declared slug, read off the parsed head it already carries. */
211
+ #slugOf() {
212
+ const state = this.#state;
213
+ if (state.kind !== "ready")
214
+ return null;
215
+ return state.doc.head?.slug ?? null;
216
+ }
217
+ /** The failure message of one unreadable state: `<word> <path>[: <field>]`. The
218
+ * io cause has no field, so it never renders a `null` tail. */
219
+ #failureWords(words, state) {
220
+ const head = `${words.planReadWord(state.cause)} ${state.path}`;
221
+ return state.field === null ? head : `${head}: ${state.field}`;
222
+ }
223
+ /** The orphan diagnostic of the ready state — the `spec-absent` sentence (slug +
224
+ * derived path) or the `slug-absent` one; null when neither applies. */
225
+ #orphanWords(words) {
226
+ const orphan = this.orphan();
227
+ if (orphan === null)
228
+ return null;
229
+ if (orphan.cause === "slug-absent")
230
+ return words.planSlugMissing();
231
+ const slug = this.#slugOf();
232
+ const specPath = orphan.specPath;
233
+ if (slug === null || specPath === null)
234
+ return null;
235
+ return words.planOrphanSpec(slug, specPath);
236
+ }
237
+ /** The one diagnostic source `warnLine` and `refusal` share. */
238
+ #diagnostic(words) {
239
+ const state = this.#state;
240
+ if (state.kind === "unreadable")
241
+ return this.#failureWords(words, state);
242
+ return this.#orphanWords(words);
243
+ }
244
+ }
245
+ /**
246
+ * PlanSource — the plan read seam: one instance per command, constructed in the
247
+ * command preamble (after the repo root resolves) and passed down as a parameter.
248
+ * It owns the read + parse + classify path both entries share; the reverse lookup
249
+ * rides the argv entry only.
250
+ */
251
+ export class PlanSource {
252
+ /** The path basis — the injected repo root (required: the root is a per-command fact). */
253
+ #root;
254
+ /** The filesystem seam (defaults to node:fs). */
255
+ #fs;
256
+ /** The ONE plan parser this source reads through (the plan doc type's single
257
+ * read point, beside the `docTypeParsers` registry row). */
258
+ #parser = new PlanDocType("plan");
259
+ constructor(root, fs = new NodeFs()) {
260
+ this.#root = root;
261
+ this.#fs = fs;
262
+ }
263
+ /** The derived face: `entry.slug` is the whole identity, the path is derived from
264
+ * it. An absent derived path is `undeclared` (this phase has no plan yet); an
265
+ * existing path whose bytes do not read is `unreadable`/`io`. No reverse lookup
266
+ * and no index: the entry IS the identity document. A null entry (an identity the
267
+ * index did not register) carries no slug, so it reads exactly like a slug-less
268
+ * entry: `undeclared` — never a minted value. */
269
+ readFor(entry) {
270
+ const slug = entry?.slug ?? null;
271
+ if (slug === null)
272
+ return new PlanRead({ kind: "undeclared", [READ_STATE_BRAND]: true });
273
+ const rel = `${ENGINE_RUNTIME.docRoots.plans}/${slug}.md`;
274
+ if (!this.#fs.exists(this.#abs(rel)))
275
+ return new PlanRead({ kind: "undeclared", [READ_STATE_BRAND]: true });
276
+ const content = this.#fs.read(this.#abs(rel));
277
+ if (content === null)
278
+ return this.#ioFailure(rel);
279
+ return this.#classify(rel, content, null);
280
+ }
281
+ /** The argv face: the caller names the path, so a failed read is NEVER
282
+ * `undeclared` — the dispatch face keeps today's usage bytes. The reverse
283
+ * lookup runs once, here, and its result rides into the shared tail as a
284
+ * parameter; the tail itself probes nothing. */
285
+ readPath(rel) {
286
+ const path = this.#root.relativize(rel);
287
+ const content = this.#fs.read(this.#root.resolve(path));
288
+ if (content === null)
289
+ return this.#ioFailure(path);
290
+ const { head } = FrontMatterExtractor.split(content);
291
+ return this.#classify(path, content, this.#orphanOf(head));
292
+ }
293
+ // -------------------------------------------------------------------------
294
+ // the private read chain
295
+ // -------------------------------------------------------------------------
296
+ /** The absolute syscall form of one repo-relative path — the ONE conversion pair
297
+ * every `DocFs` call goes through (never a bare path resolved by the process cwd). */
298
+ #abs(rel) {
299
+ return this.#root.resolve(this.#root.relativize(rel));
300
+ }
301
+ /** The io read failure — the bytes did not read. `DocFs.read` carries no errno,
302
+ * so the failure records the path and the cause only; the sentence the reader
303
+ * sees is composed by the diagnostics (`#failureWords`), never stored. */
304
+ #ioFailure(path) {
305
+ return new PlanRead({
306
+ kind: "unreadable",
307
+ path,
308
+ cause: "io",
309
+ field: null,
310
+ [READ_STATE_BRAND]: true,
311
+ });
312
+ }
313
+ /** The shared read tail: front-matter split, ONE parse, the eager graph. The
314
+ * reverse-lookup result arrives as a parameter (`null` on the derived face), so
315
+ * this tail contains no probe. A grammar break is the typed `DocSyntaxError` and
316
+ * becomes the `syntax` failure; any other throw is a programming break. */
317
+ #classify(path, content, orphan) {
318
+ const { head } = FrontMatterExtractor.split(content);
319
+ try {
320
+ const doc = this.#parser.parse(content.split("\n"), head);
321
+ const graph = new TaskGraph(doc);
322
+ return new PlanRead({
323
+ kind: "ready",
324
+ path,
325
+ text: content,
326
+ doc,
327
+ graph,
328
+ orphan,
329
+ [READ_STATE_BRAND]: true,
330
+ });
331
+ }
332
+ catch (error) {
333
+ if (!(error instanceof DocSyntaxError))
334
+ throw error;
335
+ return new PlanRead({
336
+ kind: "unreadable",
337
+ path,
338
+ cause: "syntax",
339
+ field: error.field,
340
+ [READ_STATE_BRAND]: true,
341
+ });
342
+ }
343
+ }
344
+ /** The reverse lookup (§2.7) — existence only. A legal slug derives
345
+ * `<slug>-design.md` and the probe answers "does this plan name a phase"; an
346
+ * illegal slug derives nothing (that is an identity break, not an orphan), and
347
+ * an absent slug is the `slug-absent` read fact. */
348
+ #orphanOf(head) {
349
+ const slug = head.slug;
350
+ if (slug === null)
351
+ return { cause: "slug-absent", specPath: null };
352
+ if (!SlugIndex.isLegalSlug(slug))
353
+ return null;
354
+ const specRel = `${ENGINE_RUNTIME.docRoots.specs}/${slug}-design.md`;
355
+ if (this.#fs.exists(this.#abs(specRel)))
356
+ return null;
357
+ return { cause: "spec-absent", specPath: specRel };
358
+ }
359
+ }
@@ -8,8 +8,9 @@
8
8
  // · contextContract — the environment contract's view of the argv channel
9
9
  // table (the CLI declaration single surface — face/declare.ts §2.4 — is the
10
10
  // channel's home; the runtime references the same table, never a second list).
11
- // · handoffNamespace — the workspace-root segment + the handoff family naming
12
- // table (the ledger's family resolution reads it).
11
+ // · handoffNamespace — the workspace-root segment + the handoff family key set
12
+ // (the ledger's unknown-family check reads it; the file names are the session
13
+ // plane's ONE mint, never a table here).
13
14
  //
14
15
  // The JSON plane's dead fields are not carried (the delete-dead-empties iron rule):
15
16
  // · failureCategories — the new tree keeps no failure-category counter data; the
@@ -24,56 +25,23 @@
24
25
  // carrying bare functions (the plan's zero-bare-function discipline).
25
26
  import { ARGV_CHANNEL } from "../face/declare.js";
26
27
  import { ENGINE_DOC_ROOTS } from "./doc-roots.js";
27
- /** The handoff family naming table — the canonical per-family file-name patterns
28
- * keyed by `op.type` (implement.wave / review.wave / … — the ledger's single
29
- * naming truth, verbatim from the engine-config handoff namespace). The v1.9
30
- * reparametrization: `returnFormat` is gone (RETURN_PROSE is the one return
31
- * contract) and each family is a pure name row — the carrier plane derives from the
32
- * op, never from this table (`planeOf`, session plane). */
33
- export const HANDOFF_FAMILIES = {
34
- "implement.wave": {
35
- name: "tasks-{tasks}-implement.json",
36
- },
37
- "review.wave": {
38
- name: "tasks-{tasks}-review-{round}.json",
39
- },
40
- "fix.wave": {
41
- name: "tasks-{tasks}-fix-{round}.json",
42
- },
43
- "review.phase-spec": {
44
- name: "phase-spec-review-{round}.json",
45
- },
46
- "fix.phase-spec": {
47
- name: "phase-spec-fix-{round}.json",
48
- },
49
- "review.overall": {
50
- name: "overall-review-{round}.json",
51
- },
52
- "fix.overall": {
53
- name: "overall-fix-{round}.json",
54
- },
55
- "review.plan": {
56
- name: "plan-review-{round}.json",
57
- },
58
- "fix.plan": {
59
- name: "plan-fix-{round}.json",
60
- },
61
- "review.single-spec": {
62
- name: "single-spec-review-{round}.json",
63
- },
64
- "fix.single-spec": {
65
- name: "single-spec-fix-{round}.json",
66
- },
67
- "review.branch": {
68
- // find #9 (spec §6.5): the range token leaves the file name — the workspace
69
- // slug is the plan-slug (the fix face carries --plan) · round accumulates
70
- // across re-reviews (lineKey pins "branch").
71
- name: "branch-review-{round}.json",
72
- },
73
- "fix.branch": {
74
- name: "branch-fix-{round}.json",
75
- },
76
- };
28
+ /** The handoff families the ledger resolves — the loud unknown-family key set, keyed by
29
+ * `op.type` (implement.wave · review.wave · …). */
30
+ export const HANDOFF_FAMILIES = [
31
+ "implement.wave",
32
+ "review.wave",
33
+ "fix.wave",
34
+ "review.phase-spec",
35
+ "fix.phase-spec",
36
+ "review.overall",
37
+ "fix.overall",
38
+ "review.plan",
39
+ "fix.plan",
40
+ "review.single-spec",
41
+ "fix.single-spec",
42
+ "review.branch",
43
+ "fix.branch",
44
+ ];
77
45
  /** The engine runtime — the typed engine-config surface, one constant (the argv
78
46
  * channel table is the CLI declaration single surface, face/declare.ts §2.4 —
79
47
  * referenced here, never re-declared). */
@@ -1,37 +1,39 @@
1
1
  // packages/cdd-engine/src-next/render/brief.ts
2
2
  // T12 — BriefRenderer: the task-brief renderer. The brief materializes the
3
- // dispatch's `### Task N:` sections from a plan: extraction rides the contract
4
- // parse face (doc.ts PlanDocType.parse — the same task-block parse instance the
5
- // graph and the dispatch reuse), the step surface carries the `— checkable:`
6
- // clause (the dispatch contract's evidence gate), and the rendered brief appends
7
- // the plan's `## Constraints` section (the complete plan mirror). The checkable
8
- // gate blocks step surfaces that carry a step
9
- // with no checkable clause; a requested task with no matching heading blocks the
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.
13
- import { PlanDocType } from "../contract/doc.js";
3
+ // dispatch's `### Task N:` sections from a plan: the task BLOCKS ride the plan
4
+ // read value (`PlanParsed#taskBlocks` — the same parse the graph and the dispatch
5
+ // reuse), the step surface carries the `— checkable:` clause (the dispatch
6
+ // contract's evidence gate), and the rendered brief appends the plan's
7
+ // `## Constraints` section (the complete plan mirror). The brief owns no parser: a
8
+ // second parse here would be a second fact source beside the plan read seam, so
9
+ // the three faces take the document text AND the parsed document from the caller.
10
+ // The checkable gate blocks step surfaces that carry a step with no checkable
11
+ // clause; a requested task with no matching heading blocks the whole render (the
12
+ // group-level out-of-bounds contract). The task sections are also exposed alone
13
+ // (`taskBody`) — the wave's reviewed-basis projection (P29 §2.2), so the child's
14
+ // bytes and the reopen fingerprint share one assembly.
15
+ //
16
+ // The raw line slices (a task block's `TaskBlock.range`, the `## Constraints`
17
+ // section) still read the TEXT: the brief is hashed (D30 · P29), and rebuilding a
18
+ // heading from `fields[].lines` would move the bytes of every already-reviewed
19
+ // wave.
14
20
  import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
15
21
  /**
16
22
  * The brief single renderer — pure data + content (no direct file system writes;
17
- * the caller/CLI writes the rendered content into the workspace).
23
+ * the caller/CLI writes the rendered content into the workspace). It carries no
24
+ * parser collaborator and no constructor: the document text and the parsed document
25
+ * arrive together from the caller's ONE plan read, so the brief can never judge a
26
+ * different parse than the graph the same round dispatched on.
18
27
  */
19
28
  export class BriefRenderer {
20
- #parser;
21
- /** The ONE task-block parse face — the block ranges and the `## Constraints`
22
- * mirror both read its AST positions (zero `^#` truncation residue). */
29
+ /** The ONE task-block parse face — the `## Constraints` mirror reads its AST
30
+ * position (zero `^#` truncation residue). */
23
31
  #reader = new PlanTaskBlocksReader();
24
- constructor(parser = new PlanDocType("plan")) {
25
- this.#parser = parser;
26
- }
27
- /** The task-heading slices of the plan parse face (the render's parse-face consumption). */
28
- taskHeadingPattern() {
29
- return this.#parser.slices.slices.find((slice) => slice.anchor === "### Task N:")?.valuePattern;
30
- }
31
- /** Extract the requested task blocks from a plan's content — the brief data. */
32
- extract(planContent, tasks) {
33
- const parsed = this.#parser.parse(planContent.split("\n"));
34
- const byId = new Map(parsed.taskBlocks.map((block) => [block.id, block]));
32
+ /** Extract the requested task blocks from a plan — the brief data. The blocks
33
+ * come from the caller's parsed document; `text` is carried for the three-face
34
+ * shape (the projections slice it) and is not read here. */
35
+ extract(_text, doc, tasks) {
36
+ const byId = new Map(doc.taskBlocks.map((block) => [block.id, block]));
35
37
  const missing = [];
36
38
  const data = [];
37
39
  for (const id of new Set(tasks)) {
@@ -62,20 +64,20 @@ export class BriefRenderer {
62
64
  * (`Ledger#briefRevision` / `#briefDrifted`) covers this projection alone (P29 §2.2
63
65
  * — a Constraints reword is dispatch input, never a brief drift). One assembly,
64
66
  * two consumers: zero second slicing logic. */
65
- taskBody(planContent, tasks) {
66
- const { data, missing } = this.extract(planContent, tasks);
67
+ taskBody(text, doc, tasks) {
68
+ const { data, missing } = this.extract(text, doc, tasks);
67
69
  if (missing.length > 0) {
68
70
  throw new Error(`task${missing.length > 1 ? "s" : ""} ${missing.join(", ")} not found in the plan`);
69
71
  }
70
- const lines = planContent.split("\n");
72
+ const lines = text.split("\n");
71
73
  return data.map((task) => this.#slice(lines, task.range)).join("\n\n");
72
74
  }
73
75
  /** Render the brief content — the task-only projection + the plan's `## Constraints`
74
76
  * section (the complete plan mirror the child reads). Any requested task without a
75
77
  * heading blocks the whole render (out-of-bounds). */
76
- render(planContent, tasks) {
77
- const body = this.taskBody(planContent, tasks);
78
- const constraints = this.#reader.section(planContent, "Constraints");
78
+ render(text, doc, tasks) {
79
+ const body = this.taskBody(text, doc, tasks);
80
+ const constraints = this.#reader.section(text, "Constraints");
79
81
  return constraints === "" ? `${body}\n` : `${body}\n\n${constraints}\n`;
80
82
  }
81
83
  /** The AST-range slice of one task block — the block's own lines verbatim, its