@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.
- package/dist/contract/completion-criterion.js +19 -28
- package/dist/contract/doc.js +24 -0
- package/dist/contract/invariants.js +11 -8
- 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 +327 -138
- package/dist/face/cli.js +172 -63
- package/dist/face/gate.js +6 -3
- package/dist/face/lifecycle.js +191 -128
- package/dist/face/words.js +51 -0
- package/dist/infra/plan-source.js +359 -0
- package/dist/infra/runtime.js +20 -52
- package/dist/render/brief.js +34 -32
- package/dist/render/templates.js +63 -29
- package/dist/session/carrier-integrity.js +0 -8
- package/dist/session/dispatch-authority.js +1 -1
- package/dist/session/handoff-schema.js +135 -73
- package/dist/session/ledger.js +269 -104
- package/dist/session/pipeline.js +2 -2
- package/dist/session/preflight.js +65 -34
- package/dist/session/round-naming.js +138 -89
- package/dist/session/run.js +73 -74
- 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/infra/runtime.js
CHANGED
|
@@ -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
|
|
12
|
-
//
|
|
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
|
|
28
|
-
*
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
"
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
"review.
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
"fix.
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
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). */
|
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
|