@oscaner-skills/cdd-engine 4.11.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.
- package/dist/contract/doc.js +24 -0
- package/dist/contract/judge.js +45 -4
- package/dist/contract/project.js +12 -1
- package/dist/contract/task-block-grammar.js +3 -1
- package/dist/face/board-view.js +179 -77
- package/dist/face/cli.js +172 -63
- package/dist/face/gate.js +6 -3
- package/dist/face/lifecycle.js +23 -13
- package/dist/face/words.js +51 -0
- package/dist/infra/plan-source.js +359 -0
- package/dist/render/brief.js +34 -32
- package/dist/session/dispatch-authority.js +1 -1
- package/dist/session/ledger.js +35 -5
- package/dist/session/pipeline.js +2 -2
- package/dist/session/preflight.js +60 -32
- package/dist/session/run.js +44 -41
- package/package.json +1 -1
|
@@ -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
|
+
}
|
package/dist/render/brief.js
CHANGED
|
@@ -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:
|
|
4
|
-
//
|
|
5
|
-
//
|
|
6
|
-
//
|
|
7
|
-
//
|
|
8
|
-
//
|
|
9
|
-
//
|
|
10
|
-
//
|
|
11
|
-
//
|
|
12
|
-
//
|
|
13
|
-
|
|
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
|
-
|
|
21
|
-
|
|
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
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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(
|
|
66
|
-
const { data, missing } = this.extract(
|
|
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 =
|
|
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(
|
|
77
|
-
const body = this.taskBody(
|
|
78
|
-
const constraints = this.#reader.section(
|
|
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
|
|
@@ -181,7 +181,7 @@ export class DispatchAuthority {
|
|
|
181
181
|
* finished run's plan edit blocked the branch review). Only an OPEN batch's brief
|
|
182
182
|
* movement refuses the faces below the wave face. */
|
|
183
183
|
#waveStation(facts) {
|
|
184
|
-
const graph = facts.pipeline.
|
|
184
|
+
const graph = facts.pipeline.plan.graph();
|
|
185
185
|
if (graph === null)
|
|
186
186
|
return null;
|
|
187
187
|
const frontier = this.#frontierOf(facts);
|
package/dist/session/ledger.js
CHANGED
|
@@ -241,12 +241,19 @@ export class Ledger {
|
|
|
241
241
|
* dispatch input (a backfill touching other tasks, or a Constraints reword, must
|
|
242
242
|
* not void a reviewed wave). */
|
|
243
243
|
#brief = new BriefRenderer();
|
|
244
|
+
/** The plan read seam (D30) — the reviewed brief's ONLY read of `reviewed.plan`:
|
|
245
|
+
* the drift judgment re-reads the path the round recorded, through the same
|
|
246
|
+
* per-command `PlanSource` the dispatch read its plan through. The ledger itself
|
|
247
|
+
* never opens a file for the brief, so the observation face can never make the
|
|
248
|
+
* hash subject drift. */
|
|
249
|
+
#plan;
|
|
244
250
|
/** The round-naming single source over this ledger's workspace — the crash
|
|
245
251
|
* artifact names derive here (zero second derivation). */
|
|
246
252
|
#naming;
|
|
247
|
-
constructor(workspace, config) {
|
|
253
|
+
constructor(workspace, config, plan) {
|
|
248
254
|
this.#workspace = workspace;
|
|
249
255
|
this.#families = config.handoffNamespace().families;
|
|
256
|
+
this.#plan = plan;
|
|
250
257
|
this.#naming = new RoundNaming(workspace);
|
|
251
258
|
}
|
|
252
259
|
/** The review-reference face — the refKind three-type derivation + binding (T25). */
|
|
@@ -450,6 +457,22 @@ export class Ledger {
|
|
|
450
457
|
row.reviewedRevision = revision;
|
|
451
458
|
this.writeProgress(data);
|
|
452
459
|
}
|
|
460
|
+
/** Record a branch line's reviewed PLAN revision (P21 §4.1) — the plan
|
|
461
|
+
* document's body revision as the round LEFT it. The read rides the ledger's own
|
|
462
|
+
* `PlanSource` (the ONE plan read point), so a round that edited its plan binds the
|
|
463
|
+
* edited bytes — never the dispatch-time snapshot — while a non-ready read records
|
|
464
|
+
* nothing (present facts only, the symmetric failure face to `recordReviewedBrief`).
|
|
465
|
+
* The recorded path is normalized HERE, not by the caller (the same discipline
|
|
466
|
+
* `#briefRevision` keeps): the drift comparator relativizes only its current side,
|
|
467
|
+
* so an absolute argv-erasure shape handed in by a future caller would otherwise
|
|
468
|
+
* read as a false drift. */
|
|
469
|
+
recordReviewedPlanRevision(key, planPath, identity) {
|
|
470
|
+
const read = this.#plan.readPath(planPath);
|
|
471
|
+
const text = read.text();
|
|
472
|
+
if (text === null)
|
|
473
|
+
return;
|
|
474
|
+
this.recordReviewedRevision(key, this.#refs.docRevision(this.#rel(planPath), text), identity);
|
|
475
|
+
}
|
|
453
476
|
/** Record a wave line's reviewed BRIEF revision (D30) — the hash of the wave's
|
|
454
477
|
* TASK-ONLY projection (P29 §2.2: the task sections, `## Constraints` excluded).
|
|
455
478
|
* A backfill touching OTHER tasks leaves this projection byte-identical, and so
|
|
@@ -463,14 +486,21 @@ export class Ledger {
|
|
|
463
486
|
/** The wave line's reviewed-basis revision (D30) — the hash of the wave's TASK-ONLY
|
|
464
487
|
* projection (`BriefRenderer#taskBody`: the task sections, `## Constraints`
|
|
465
488
|
* excluded — P29 §2.2). The `plan` layer is the plan the brief renders from, the
|
|
466
|
-
* `brief_hash` layer the projection's own digest.
|
|
467
|
-
*
|
|
489
|
+
* `brief_hash` layer the projection's own digest. The read rides the injected
|
|
490
|
+
* `PlanSource` (the ONE plan read seam), so a non-ready read — an unreadable plan,
|
|
491
|
+
* a grammar break — records nothing. Null when the plan is unreadable or a
|
|
492
|
+
* requested task is absent (present facts only). */
|
|
468
493
|
#briefRevision(waveKey, planPath) {
|
|
494
|
+
const read = this.#plan.readPath(planPath);
|
|
495
|
+
const text = read.text();
|
|
496
|
+
const doc = read.doc();
|
|
497
|
+
if (text === null || doc === null)
|
|
498
|
+
return null;
|
|
469
499
|
try {
|
|
470
500
|
const tasks = waveKey.split(",").map((part) => Number(part));
|
|
501
|
+
const brief = this.#brief.taskBody(text, doc, tasks);
|
|
471
502
|
// The plan layer is stored repoRoot-relative (P9 T4 §2.7) — one basis with
|
|
472
|
-
// every persisted path field
|
|
473
|
-
const brief = this.#brief.taskBody(readFileSync(this.#abs(planPath), "utf8"), tasks);
|
|
503
|
+
// every persisted path field.
|
|
474
504
|
return this.#refs.briefRevision(this.#rel(planPath), brief);
|
|
475
505
|
}
|
|
476
506
|
catch {
|
package/dist/session/pipeline.js
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
//
|
|
13
13
|
// Constructed with the node's `Ledger` (the `Ledger` / `Lifecycle` shape: one read
|
|
14
14
|
// face injected, no global state). The plan is never read here — the guarded plan
|
|
15
|
-
// read stays on the board side and rides in as `
|
|
15
|
+
// read stays on the board side and rides in as `plan`, so this module holds
|
|
16
16
|
// zero file-system read and no second plan parse.
|
|
17
17
|
//
|
|
18
18
|
// The four rules over the ONE `PIPELINE_FACES` order:
|
|
@@ -172,7 +172,7 @@ export class PipelineFrontier {
|
|
|
172
172
|
* alone would fall into rule 2 and render the wave face's own exit
|
|
173
173
|
* (`PIPELINE_NEXT.wave`), a worse literal than the one being removed. */
|
|
174
174
|
#waveState(input) {
|
|
175
|
-
const graph = input.
|
|
175
|
+
const graph = input.plan.graph();
|
|
176
176
|
const waveKey = graph === null ? null : this.#waveKeyOf(graph);
|
|
177
177
|
const entered = graph !== null && this.#wavesEntered(graph);
|
|
178
178
|
return {
|