@oscaner-skills/cdd-engine 4.1.0 → 4.3.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.
Files changed (59) hide show
  1. package/README.md +39 -9
  2. package/README.zh-CN.md +44 -9
  3. package/dist/contract/completion-criterion.js +351 -0
  4. package/dist/contract/declare.js +181 -43
  5. package/dist/contract/doc.js +84 -271
  6. package/dist/contract/frontmatter.js +2 -1
  7. package/dist/contract/home-extractors.js +49 -316
  8. package/dist/contract/invariants.js +400 -296
  9. package/dist/contract/judge.js +74 -49
  10. package/dist/contract/lint.js +3 -2
  11. package/dist/contract/liveness-signal.js +103 -0
  12. package/dist/contract/markdown-document.js +410 -0
  13. package/dist/contract/markdown-tree-types.js +6 -0
  14. package/dist/contract/markdown-tree.js +137 -0
  15. package/dist/contract/project.js +1 -1
  16. package/dist/contract/rules.js +106 -0
  17. package/dist/contract/selector-engine.js +332 -0
  18. package/dist/contract/selector-spec.js +74 -0
  19. package/dist/contract/skill-anatomy.js +29 -1
  20. package/dist/contract/task-block-grammar.js +285 -0
  21. package/dist/contract/task-blocks.js +65 -0
  22. package/dist/contract/translate.js +21 -0
  23. package/dist/contract/wave-width.js +15 -0
  24. package/dist/face/board-view.js +401 -131
  25. package/dist/face/capsule.js +66 -89
  26. package/dist/face/cli.js +174 -48
  27. package/dist/face/declare.js +59 -23
  28. package/dist/face/gate.js +117 -40
  29. package/dist/face/host.js +9 -35
  30. package/dist/face/init.js +108 -0
  31. package/dist/face/lifecycle.js +540 -123
  32. package/dist/face/plugins.js +73 -0
  33. package/dist/face/preview.js +43 -10
  34. package/dist/face/projection.js +3 -3
  35. package/dist/face/route-render.js +51 -21
  36. package/dist/face/termination.js +135 -261
  37. package/dist/face/words.js +134 -12
  38. package/dist/infra/atomic.js +15 -0
  39. package/dist/infra/git.js +25 -0
  40. package/dist/infra/proc.js +150 -0
  41. package/dist/infra/round-log.js +104 -0
  42. package/dist/infra/runtime.js +16 -4
  43. package/dist/infra/workspace.js +7 -2
  44. package/dist/render/brief.js +15 -17
  45. package/dist/render/skeleton.js +41 -28
  46. package/dist/render/templates.js +128 -84
  47. package/dist/session/faces.js +47 -20
  48. package/dist/session/graph.js +13 -37
  49. package/dist/session/handoff-schema.js +16 -8
  50. package/dist/session/inflight.js +282 -0
  51. package/dist/session/ledger.js +581 -136
  52. package/dist/session/line-identity.js +33 -0
  53. package/dist/session/next.js +138 -80
  54. package/dist/session/preflight.js +276 -68
  55. package/dist/session/round-naming.js +56 -8
  56. package/dist/session/run.js +317 -78
  57. package/dist/session/wave.js +94 -14
  58. package/package.json +13 -3
  59. package/dist/infra/process.js +0 -22
@@ -0,0 +1,410 @@
1
+ // packages/cdd-engine/src-next/contract/markdown-document.ts
2
+ // P21 §7.5 — the document INDEX: one mdast parse of one markdown document and the
3
+ // structural facts every walk reads (the source lines, the headings and their
4
+ // spans, the front-matter keys, the tables, the inline-code column spans).
5
+ //
6
+ // The index is immutable after construction and answers location questions only —
7
+ // it never evaluates a selector and never parses a task block. The selector engine
8
+ // (selector-engine.ts) walks it, the block grammar (task-block-grammar.ts) parses
9
+ // its task blocks, and `MarkdownTree` (markdown-tree.ts) is the facade over all
10
+ // three. Splitting the index out keeps the one parse face free of the query and
11
+ // block-grammar concerns (the repo's per-class size standard).
12
+ var _a;
13
+ import { fromMarkdown } from "mdast-util-from-markdown";
14
+ import { frontmatterFromMarkdown } from "mdast-util-frontmatter";
15
+ import { gfmFromMarkdown } from "mdast-util-gfm";
16
+ import { frontmatter } from "micromark-extension-frontmatter";
17
+ import { gfm } from "micromark-extension-gfm";
18
+ /**
19
+ * MarkdownDocument — the parsed document index: its lines, headings, front-matter
20
+ * keys, tables and inline-code spans. Instances are immutable; every read is pure.
21
+ *
22
+ * Rule zero (over the 200-line class limit): the index stays one class because every
23
+ * member is a pure read of the SAME immutable mdast parse — splitting the heading,
24
+ * table and front-matter readers would share that one parse through a second seam
25
+ * without removing a single variation.
26
+ */
27
+ export class MarkdownDocument {
28
+ /** A pipe-delimited row line (`| a | b |`) — the loose continuation-row shape. */
29
+ static LOOSE_ROW = /^\|.*\|$/;
30
+ /** The GFM delimiter row (`| --- | --- |`) — table syntax, never a data row. */
31
+ static DELIMITER_ROW = /^\|?[\s:|-]*-[\s:|-]*\|?$/;
32
+ /** The document's raw lines (1-based line n is index n-1). */
33
+ #lines;
34
+ /** The mdast root. */
35
+ #root;
36
+ /** Every heading of the document, in document order. */
37
+ #headings;
38
+ /** The front-matter keys of the document (empty without a head). */
39
+ #frontMatter;
40
+ /** Every table of the document, in document order. */
41
+ #tables;
42
+ /** Inline-code column spans, keyed by 1-based line (the citation boundary). */
43
+ #codeSpans;
44
+ /** The lines covered by a fenced / indented code block — the code surface the
45
+ * loose continuation-row recovery must never read as table data. */
46
+ #codeLines;
47
+ constructor(content) {
48
+ this.#lines = content.split(/\r?\n/);
49
+ this.#root = _a.#parseRoot(content);
50
+ this.#codeSpans = _a.#codeSpansOf(this.#root);
51
+ this.#codeLines = _a.#codeLinesOf(this.#root);
52
+ this.#headings = this.#headingsOf();
53
+ this.#frontMatter = this.#frontMatterOf();
54
+ const tables = this.#tablesOf();
55
+ this.#tables = [...tables, ...this.#looseTablesOf(tables)].sort((left, right) => left.from - right.from);
56
+ }
57
+ /** Parse a document — the single `from-markdown` entry of the tree. The input
58
+ * text is expected already normalized (the canonicalize view at the row
59
+ * source); the document index never rewrites it. */
60
+ static parse(content) {
61
+ return new _a(content);
62
+ }
63
+ /** The index's own markup entry — gfm tables + YAML front matter. */
64
+ static #parseRoot(content) {
65
+ return fromMarkdown(content, {
66
+ extensions: [gfm(), frontmatter()],
67
+ mdastExtensions: [gfmFromMarkdown(), frontmatterFromMarkdown()],
68
+ });
69
+ }
70
+ /** One raw source line (1-based; "" past the end). */
71
+ line(line) {
72
+ return this.#lines[line - 1] ?? "";
73
+ }
74
+ /** The document's line count (a trailing newline's empty tail included, exactly as
75
+ * the source splits). */
76
+ lineCount() {
77
+ return this.#lines.length;
78
+ }
79
+ /** The line with its inline-code spans removed (the citation boundary read from
80
+ * the document's own `inlineCode` node spans). */
81
+ bareOf(line) {
82
+ return _a.#stripSpans(this.line(line), this.#codeSpans.get(line) ?? []);
83
+ }
84
+ /** The headings of the document (any rank), in document order. */
85
+ headings() {
86
+ return this.#headings;
87
+ }
88
+ /** The heading spans of the document (any rank), in document order — the child
89
+ * walks' scope (a heading's span runs to the next rank-2-or-shallower heading,
90
+ * the SAME section boundary every walk scopes to). */
91
+ headingScopes() {
92
+ return this.#headings.map((heading, index) => ({
93
+ text: heading.text,
94
+ line: heading.line,
95
+ from: heading.line,
96
+ to: this.#sectionEnd(index),
97
+ }));
98
+ }
99
+ /** The rank-2 sections of the document, in document order (the section surface
100
+ * every doc type's `##`-heading read rides). */
101
+ sections() {
102
+ const out = [];
103
+ for (const [index, heading] of this.#headings.entries()) {
104
+ if (heading.depth !== 2)
105
+ continue;
106
+ const end = this.#sectionEnd(index);
107
+ out.push({
108
+ text: heading.text,
109
+ lines: this.#lines.slice(heading.line, end),
110
+ line: heading.line,
111
+ });
112
+ }
113
+ return out;
114
+ }
115
+ /** The front-matter keys of the document, in document order. */
116
+ frontMatterKeys() {
117
+ return this.#frontMatter;
118
+ }
119
+ /** Every table of the document, in document order. */
120
+ tables() {
121
+ return this.#tables;
122
+ }
123
+ /** The tables scoped to a parent selection — the parents' line spans, or every
124
+ * table when no parent was given. */
125
+ tablesInScope(parents) {
126
+ if (parents === null)
127
+ return this.#tables;
128
+ return this.#tables.filter((table) => parents.some((parent) => table.from >= parent.from && table.to <= parent.to));
129
+ }
130
+ /** The document's top-level mdast nodes, in document order (the block grammar's
131
+ * task-heading scan reads this). */
132
+ topNodes() {
133
+ return this.#root.children ?? [];
134
+ }
135
+ /** Every mdast node of one type, in document order (a bounded recursive walk). */
136
+ collect(type) {
137
+ const out = [];
138
+ const stack = [this.#root];
139
+ while (stack.length > 0) {
140
+ const node = stack.shift();
141
+ if (node === undefined)
142
+ continue;
143
+ if (node.type === type)
144
+ out.push(node);
145
+ stack.push(...(node.children ?? []));
146
+ }
147
+ return out;
148
+ }
149
+ /** The plain text of one mdast node (the heading text / key surface). */
150
+ textOf(node) {
151
+ if (node === undefined)
152
+ return "";
153
+ if (typeof node.value === "string")
154
+ return node.value;
155
+ return (node.children ?? []).map((child) => this.textOf(child)).join("");
156
+ }
157
+ /** The 1-based line span of one node. */
158
+ static spanOf(node) {
159
+ const start = node.position?.start?.line;
160
+ const end = node.position?.end?.line;
161
+ if (start === undefined || end === undefined)
162
+ return null;
163
+ return { start, end };
164
+ }
165
+ /** The document headings with their bodies, in document order. */
166
+ #headingsOf() {
167
+ const nodes = (this.#root.children ?? []).filter((node) => node.type === "heading");
168
+ const out = [];
169
+ for (const [index, node] of nodes.entries()) {
170
+ const span = _a.spanOf(node);
171
+ if (span === null)
172
+ continue;
173
+ const next = nodes[index + 1];
174
+ const nextSpan = next === undefined ? null : _a.spanOf(next);
175
+ const end = nextSpan === null ? this.#lines.length : nextSpan.start - 1;
176
+ out.push({
177
+ text: this.line(span.start).trim(),
178
+ depth: node.depth ?? 1,
179
+ line: span.start,
180
+ bodyLines: this.#lines.slice(span.end, Math.max(end, span.end)),
181
+ });
182
+ }
183
+ return out;
184
+ }
185
+ /** The front-matter key locators — the YAML block's `key: value` lines. The
186
+ * block's TYPED values stay the front-matter extractor's job; the index only
187
+ * locates the key's line (identity versus location). */
188
+ #frontMatterOf() {
189
+ const out = [];
190
+ for (const node of this.#root.children ?? []) {
191
+ if (node.type !== "yaml")
192
+ continue;
193
+ const span = _a.spanOf(node);
194
+ if (span === null)
195
+ continue;
196
+ for (let line = span.start + 1; line < span.end; line += 1) {
197
+ const match = /^([A-Za-z0-9_-]+):(.*)$/.exec(this.line(line).trim());
198
+ if (match === null)
199
+ continue;
200
+ out.push({ key: match[1] ?? "", value: (match[2] ?? "").trim(), line });
201
+ }
202
+ return out;
203
+ }
204
+ return out;
205
+ }
206
+ /** The tables of the document in document order — the mdast GFM tables plus the
207
+ * headerless continuation runs a blank line detaches from their table (see
208
+ * `#looseTablesOf`). */
209
+ #tablesOf() {
210
+ const out = [];
211
+ for (const node of this.collect("table")) {
212
+ const span = _a.spanOf(node);
213
+ if (span === null)
214
+ continue;
215
+ const rows = (node.children ?? [])
216
+ .map((row) => this.#rowOf(row))
217
+ .filter((row) => row !== null);
218
+ const [header, ...body] = rows;
219
+ out.push({
220
+ header: header === undefined ? null : { ...header, header: true },
221
+ body: body.map((row) => ({ ...row, header: false })),
222
+ from: span.start,
223
+ to: span.end,
224
+ });
225
+ }
226
+ return out;
227
+ }
228
+ /** The headerless table rows a blank line detaches from their GFM table: a GFM
229
+ * table ends at a blank line, and a continuation run carries bare `| a | b |`
230
+ * rows with no delimiter row, so mdast reads them as paragraphs. A SECTION span
231
+ * is the table's real boundary (the repository's own Phase / Issue inventories
232
+ * are written this way), so the run is read back as a headerless table record;
233
+ * the merge then keeps the first table's header and concatenates the rows in
234
+ * document order. Lines already covered by an mdast table OR by an mdast code
235
+ * block are skipped: a fenced block that shows the table shape is sample prose,
236
+ * never table data (no row is ever read twice). */
237
+ #looseTablesOf(tables) {
238
+ const out = [];
239
+ const inTableSpan = (line) => tables.some((table) => line >= table.from && line <= table.to);
240
+ for (const [index, heading] of this.#headings.entries()) {
241
+ if (heading.depth !== 2)
242
+ continue;
243
+ const end = this.#sectionEnd(index);
244
+ let run = [];
245
+ const flush = () => {
246
+ const [first] = run;
247
+ if (first === undefined)
248
+ return;
249
+ out.push({ header: null, body: run, from: first.from, to: first.to });
250
+ run = [];
251
+ };
252
+ for (let line = heading.line + 1; line <= end; line += 1) {
253
+ const text = this.line(line).trim();
254
+ if (inTableSpan(line) ||
255
+ this.#codeLines.has(line) ||
256
+ !_a.LOOSE_ROW.test(text)) {
257
+ flush();
258
+ continue;
259
+ }
260
+ if (_a.DELIMITER_ROW.test(text))
261
+ continue;
262
+ run.push({
263
+ text,
264
+ bare: this.bareOf(line),
265
+ lines: [text],
266
+ line,
267
+ cells: _a.cellsOfLooseRow(text),
268
+ from: line,
269
+ to: line,
270
+ });
271
+ }
272
+ flush();
273
+ }
274
+ return out;
275
+ }
276
+ /** The cells of one headerless table row — split on the unescaped `|`
277
+ * delimiters (a `\|` stays inside its cell), the outer pipes stripped. */
278
+ static cellsOfLooseRow(text) {
279
+ const inner = text.replace(/^\|/, "").replace(/\|$/, "");
280
+ const cells = [];
281
+ let current = "";
282
+ let escaped = false;
283
+ for (const character of inner) {
284
+ if (escaped) {
285
+ current += character;
286
+ escaped = false;
287
+ continue;
288
+ }
289
+ if (character === "\\") {
290
+ escaped = true;
291
+ current += character;
292
+ continue;
293
+ }
294
+ if (character !== "|") {
295
+ current += character;
296
+ continue;
297
+ }
298
+ cells.push(current);
299
+ current = "";
300
+ }
301
+ cells.push(current);
302
+ return cells.map((cell) => cell.replace(/\\\|/g, "|").trim());
303
+ }
304
+ /** One table cell's value — the raw source slice of the cell's span with its
305
+ * delimiters stripped and the GFM `\|` escape resolved, so a cell keeps its
306
+ * inline markdown (a link target, a code span). The mdast cell span includes the
307
+ * leading pipe (its start column sits on the delimiter), hence the strip. */
308
+ static #cellText(cell, lines) {
309
+ const start = cell.position?.start;
310
+ const end = cell.position?.end;
311
+ if (start?.line !== undefined && start.column !== undefined && end?.column !== undefined) {
312
+ if (start.line === end.line) {
313
+ const raw = (lines[start.line - 1] ?? "").slice(start.column - 1, end.column - 1);
314
+ return raw.replace(/^\|/, "").replace(/\|$/, "").replace(/\\\|/g, "|").trim();
315
+ }
316
+ }
317
+ return "";
318
+ }
319
+ /** One mdast table row → its cells (each cell the raw source slice of the cell's
320
+ * own span; an escaped `\|` and a backticked pipe stay inside their cell). */
321
+ #rowOf(node) {
322
+ const span = _a.spanOf(node);
323
+ if (span === null)
324
+ return null;
325
+ const cells = (node.children ?? [])
326
+ .filter((cell) => cell.type === "tableCell")
327
+ .map((cell) => _a.#cellText(cell, this.#lines));
328
+ const text = this.line(span.start).trim();
329
+ return {
330
+ text,
331
+ bare: text,
332
+ lines: [text],
333
+ line: span.start,
334
+ cells,
335
+ from: span.start,
336
+ to: span.end,
337
+ };
338
+ }
339
+ /** The section end line of the heading at `index` — the line before the next
340
+ * rank-2-or-shallower heading, or the document's last line. */
341
+ #sectionEnd(index) {
342
+ const heading = this.#headings[index];
343
+ if (heading === undefined)
344
+ return this.#lines.length;
345
+ for (let next = index + 1; next < this.#headings.length; next += 1) {
346
+ const candidate = this.#headings[next];
347
+ if (candidate === undefined)
348
+ continue;
349
+ if (candidate.depth <= 2)
350
+ return candidate.line - 1;
351
+ }
352
+ return this.#lines.length;
353
+ }
354
+ /** The text with every inline-code span removed (a line's citation boundary). */
355
+ static #stripSpans(text, spans) {
356
+ if (spans.length === 0)
357
+ return text;
358
+ let out = "";
359
+ let cursor = 0;
360
+ for (const [start, end] of [...spans].sort((left, right) => left[0] - right[0])) {
361
+ if (start < cursor)
362
+ continue;
363
+ out += text.slice(cursor, start);
364
+ cursor = end;
365
+ }
366
+ return out + text.slice(cursor);
367
+ }
368
+ /** The inline-code column spans of the document, keyed by line (1-based columns). */
369
+ static #codeSpansOf(root) {
370
+ const map = new Map();
371
+ const stack = [root];
372
+ while (stack.length > 0) {
373
+ const node = stack.shift();
374
+ if (node === undefined)
375
+ continue;
376
+ if (node.type === "inlineCode") {
377
+ const start = node.position?.start;
378
+ const end = node.position?.end;
379
+ if (start?.line !== undefined && start.column !== undefined && end?.column !== undefined) {
380
+ const bucket = map.get(start.line) ?? [];
381
+ bucket.push([start.column - 1, end.column - 1]);
382
+ map.set(start.line, bucket);
383
+ }
384
+ }
385
+ stack.push(...(node.children ?? []));
386
+ }
387
+ return map;
388
+ }
389
+ /** The lines occupied by a fenced / indented code block (the code surface a
390
+ * loose-row read must never treat as table data). */
391
+ static #codeLinesOf(root) {
392
+ const lines = new Set();
393
+ const stack = [root];
394
+ while (stack.length > 0) {
395
+ const node = stack.shift();
396
+ if (node === undefined)
397
+ continue;
398
+ if (node.type === "code") {
399
+ const span = _a.spanOf(node);
400
+ if (span !== null) {
401
+ for (let line = span.start; line <= span.end; line += 1)
402
+ lines.add(line);
403
+ }
404
+ }
405
+ stack.push(...(node.children ?? []));
406
+ }
407
+ return lines;
408
+ }
409
+ }
410
+ _a = MarkdownDocument;
@@ -0,0 +1,6 @@
1
+ // packages/cdd-engine/src-next/contract/markdown-tree-types.ts
2
+ // P21 §7.5 — the tree's shared vocabulary: the selector query, the resolved node
3
+ // and the structural records the three tree classes exchange (the document index,
4
+ // the selector engine and the block grammar). Types only — the runtime lives in
5
+ // those three classes, so the vocabulary never pulls an implementation in.
6
+ export {};
@@ -0,0 +1,137 @@
1
+ // packages/cdd-engine/src-next/contract/markdown-tree.ts
2
+ // P21 §7.5 — the ONE parse face of the contract plane: the markdown tree.
3
+ //
4
+ // The four doc types (overall / plan / phase-spec / single-spec) share one
5
+ // document model. `MarkdownTree.parse(content)` is the single `from-markdown`
6
+ // entry of the tree (gfm + YAML front matter extensions): every consumer — the
7
+ // doc parsers, the home extractors, the invariant strategies, the skeleton
8
+ // round-trip pin — locates structure through it, never through a hand-written
9
+ // line scan.
10
+ //
11
+ // The face is three classes behind one facade, split along their responsibilities:
12
+ // · `MarkdownDocument` (markdown-document.ts) — the document index: one mdast
13
+ // parse, the headings, the front-matter keys, the tables, the code spans.
14
+ // · `SelectorEngine` (selector-engine.ts) — selector evaluation: `from` a parent
15
+ // selector or the root, `walk` one of the nine structural surfaces, `match`,
16
+ // `when`.
17
+ // · `TaskBlocksParser` (task-block-grammar.ts) — the ONE task-block grammar.
18
+ // This class is the thin composition facade; it adds the cross-cutting section-text
19
+ // read and re-exports the vocabulary, so no consumer pays for the split.
20
+ //
21
+ // The two axes the tree keeps apart (the P21 identity/locator split):
22
+ // · IDENTITY — a registry element's `anchor` (the schema property name, the
23
+ // `required[]` key, the skeleton truth-table key, the lint lookup key, the
24
+ // `field:` of a finding). The tree never touches it.
25
+ // · LOCATION — an element's `selector`: a composable query (`from` a parent
26
+ // selector or the document root, `walk` one of the nine structural walks,
27
+ // an optional `match` and an optional `when` guard). A selector answers
28
+ // WHERE, never WHAT.
29
+ //
30
+ // A resolved node is line-faithful: `text` is the node's own raw source line
31
+ // (the value-shape judgments run on it, exactly as the declared `valuePattern`
32
+ // rows were written) and `bare` is the same line with its inline-code spans
33
+ // removed (a cited anchor is not a value carrier — the code-span boundary is
34
+ // read from the tree's inline-code node spans, never from a first/last-backtick
35
+ // guess). `line` is 1-based, so a finding can point at the row it judges.
36
+ //
37
+ // Module-level exports are types / the class — zero behavior-carrying bare
38
+ // functions (the plan's zero-bare-function discipline).
39
+ import { MarkdownDocument } from "./markdown-document.js";
40
+ import { SelectorEngine } from "./selector-engine.js";
41
+ import { TaskBlockGrammar, TaskBlocksParser } from "./task-block-grammar.js";
42
+ export { TaskBlockGrammar } from "./task-block-grammar.js";
43
+ /**
44
+ * MarkdownTree — the ONE parse face: one document, one selector evaluation, one
45
+ * block parse, composed behind a stable read surface. Instances are immutable after
46
+ * construction; the walks are pure reads, so one tree serves the parse face, the
47
+ * extractors and the judgment face alike.
48
+ */
49
+ export class MarkdownTree {
50
+ /** The document index — the one parse every walk reads. */
51
+ #document;
52
+ /** The composable locator face over the index. */
53
+ #selectors;
54
+ /** The ONE `### Task N:` block parse over the index. */
55
+ #blocks;
56
+ constructor(document) {
57
+ this.#document = document;
58
+ this.#blocks = new TaskBlocksParser(document);
59
+ this.#selectors = new SelectorEngine(document, this.#blocks);
60
+ }
61
+ /** Parse a document — the single `from-markdown` entry of the tree. The input
62
+ * text is expected already normalized (the canonicalize view at the row
63
+ * source); the tree never rewrites it. */
64
+ static parse(content) {
65
+ return new MarkdownTree(MarkdownDocument.parse(content));
66
+ }
67
+ /** The first node matching the selector — null when nothing matches (the
68
+ * presence read). */
69
+ resolve(selector) {
70
+ return this.#selectors.resolve(selector);
71
+ }
72
+ /** Every node matching the selector, in document order. */
73
+ occurrences(selector) {
74
+ return this.#selectors.occurrences(selector);
75
+ }
76
+ /** The rank-2 sections of the document, in document order (the section surface
77
+ * every doc type's `##`-heading read rides). */
78
+ sections() {
79
+ return this.#document.sections();
80
+ }
81
+ /** The headings of the document (any rank), in document order. */
82
+ headings() {
83
+ return this.#document.headings();
84
+ }
85
+ /** The front-matter keys of the document, in document order. */
86
+ frontMatterKeys() {
87
+ return this.#document.frontMatterKeys();
88
+ }
89
+ /** The cell rows of the selector's row matches (the parse face's table read). */
90
+ rows(selector) {
91
+ return this.#selectors.rows(selector);
92
+ }
93
+ /** The table of the section under one heading — the section's first table plus
94
+ * its headerless continuation runs, header from the first (see SelectorEngine). */
95
+ tableUnder(heading) {
96
+ return this.#selectors.tableUnder(heading);
97
+ }
98
+ /** The list items whose first child is itself a list — the doubled-marker shape
99
+ * (`- - x`); a thematic break is exempt by construction. */
100
+ doubledMarkerItems() {
101
+ return this.#selectors.doubledMarkerItems();
102
+ }
103
+ /** The `## Dependency graph` edges of the document, in document order. */
104
+ edges() {
105
+ return this.#selectors.edges();
106
+ }
107
+ /** The `### Task N:` blocks of the document, in document order — the ONE block
108
+ * structure parse (the heading shape and the legacy bullet shape normalize into
109
+ * the same record). */
110
+ tasks() {
111
+ return this.#blocks.tasks();
112
+ }
113
+ /** The body text of one rank-2 section (the brief's `## Constraints` mirror),
114
+ * heading line included; "" when the section is absent. */
115
+ sectionText(heading) {
116
+ for (const section of this.sections()) {
117
+ const text = section.text.trim();
118
+ if (text !== heading && text.replace(/^#+\s*/, "") !== heading)
119
+ continue;
120
+ const body = [];
121
+ for (const line of section.lines) {
122
+ // A `### Task N:` head ends the section — a task block never lives inside a
123
+ // rank-2 section body — while a deeper plain heading stays in the body.
124
+ if (TaskBlockGrammar.TASK_HEADING.test(line.trim().replace(/^### /, "")))
125
+ break;
126
+ body.push(line);
127
+ }
128
+ return [section.text, ...body].join("\n").replace(/\s+$/, "");
129
+ }
130
+ return "";
131
+ }
132
+ /** Whether a text conforms to a selector's match face (the section/registry
133
+ * conformance read — the same match semantics the walks apply). */
134
+ matches(selector, text) {
135
+ return this.#selectors.matches(selector, text);
136
+ }
137
+ }
@@ -284,7 +284,7 @@ export class Projector {
284
284
  * literal `N` (a literal `N` punctures the declared
285
285
  * digit-shaped value pattern);
286
286
  * · generator-truth — a pattern-typed value row: a fully-anchored enum domain
287
- * (the first legal literal — `status: Draft`) or a
287
+ * (the `doc-type` key's closed `DOC_TYPE_VALUES` set) or a
288
288
  * graph row (hard edge / legend conforming lines);
289
289
  * · table-header / table-row / scaffold — the table column headers, the data
290
290
  * rows and the fixed scaffold rows (the version line, the
@@ -0,0 +1,106 @@
1
+ // packages/cdd-engine/src-next/contract/rules.ts
2
+ // The rule declaration surface — the ONE source of the structural rule list (P21
3
+ // §3.1/§3.4). A row is `id + applicable docKeys + scope`, and it is itself the
4
+ // factory: `create()` yields the strategy, whose `name` is verbatim the row id. The
5
+ // `Contract` policy composition walks these declarations (zero hard-coded `new`
6
+ // family), and the pre-flight `checked` list renders the SAME rows — "which rule
7
+ // ran" and "what it judged" cannot drift apart because neither has a second list.
8
+ //
9
+ // Two scopes, two entry shapes (one entry per judgment kind):
10
+ // · `doc` — an `Invariant`, judged over the document (`evaluate(ctx)`), by the
11
+ // `doc-contract` gate;
12
+ // · `ledger` — a `LedgerRule`, judged over the document AND the ledger fact bundle
13
+ // (`evaluate(ctx, ledger)`), by the `plan-ledger` gate. The ledger facts
14
+ // are deliberately NOT a `ContractInput` field: one entry, one judgment.
15
+ //
16
+ // The element registry (`ElementRegistry`) is the skeleton element table, not a rule
17
+ // list — these declarations are the rule surface. One rule = one strategy: the
18
+ // multi-surface strategies of the old family were split per leg (uniqueness → three,
19
+ // order → one section-order row, selfBounded → one lineage row), so a declaration row
20
+ // never hides a second rule. The version-order leg and the header-equals-last-row leg
21
+ // are not declared at all: ordering is presentation, not data integrity, and the
22
+ // lineage judgment is membership-only.
23
+ //
24
+ // Module-level exports are types / the declared data — zero behavior-carrying bare
25
+ // functions.
26
+ import { ChangeHistoryVersionUniqueInvariant, ContinuityInvariant, CrossDocChainInvariant, CrosslinkInvariant, DomainInvariant, FileExistenceInvariant, FrontMatterVersionInLineageInvariant, HollowInvariant, LedgerLayeringRule, LedgerTaskSetRule, LinkShapeInvariant, ListMarkerInvariant, PhaseIdUniqueInvariant, PresenceInvariant, ResidueInvariant, RowHomeInvariant, SectionOrderInvariant, SectionScopedDomainInvariant, SiblingScanInvariant, SlugRefInvariant, TaskIdUniqueInvariant, WaveWidthInvariant, } from "./invariants.js";
27
+ /** The rule registry — doc scope 20 rows + ledger scope 2 rows = 22. */
28
+ export const RULE_REGISTRY = [
29
+ { scope: "doc", id: "presence", docKeys: "all", create: () => new PresenceInvariant() },
30
+ {
31
+ scope: "doc",
32
+ id: "change-history-version-unique",
33
+ docKeys: "all",
34
+ create: () => new ChangeHistoryVersionUniqueInvariant(),
35
+ },
36
+ { scope: "doc", id: "task-id-unique", docKeys: "all", create: () => new TaskIdUniqueInvariant() },
37
+ {
38
+ scope: "doc",
39
+ id: "phase-id-unique",
40
+ docKeys: "all",
41
+ create: () => new PhaseIdUniqueInvariant(),
42
+ },
43
+ { scope: "doc", id: "domain", docKeys: "all", create: () => new DomainInvariant() },
44
+ { scope: "doc", id: "crosslink", docKeys: "all", create: () => new CrosslinkInvariant() },
45
+ { scope: "doc", id: "section-order", docKeys: "all", create: () => new SectionOrderInvariant() },
46
+ {
47
+ scope: "doc",
48
+ id: "front-matter-version-in-lineage",
49
+ docKeys: "all",
50
+ create: () => new FrontMatterVersionInLineageInvariant(),
51
+ },
52
+ { scope: "doc", id: "continuity", docKeys: "all", create: () => new ContinuityInvariant() },
53
+ { scope: "doc", id: "residue", docKeys: "all", create: () => new ResidueInvariant() },
54
+ { scope: "doc", id: "hollow", docKeys: "all", create: () => new HollowInvariant() },
55
+ { scope: "doc", id: "link-shape", docKeys: "all", create: () => new LinkShapeInvariant() },
56
+ {
57
+ scope: "doc",
58
+ id: "file-existence",
59
+ docKeys: "all",
60
+ create: () => new FileExistenceInvariant(),
61
+ },
62
+ { scope: "doc", id: "sibling-scan", docKeys: "all", create: () => new SiblingScanInvariant() },
63
+ { scope: "doc", id: "slug-ref", docKeys: "all", create: () => new SlugRefInvariant() },
64
+ {
65
+ scope: "doc",
66
+ id: "cross-doc-chain",
67
+ docKeys: "all",
68
+ create: () => new CrossDocChainInvariant(),
69
+ },
70
+ {
71
+ scope: "doc",
72
+ id: "section-scoped-domain",
73
+ docKeys: "all",
74
+ create: () => new SectionScopedDomainInvariant(),
75
+ },
76
+ {
77
+ scope: "doc",
78
+ id: "change-history-row-not-in-other-table",
79
+ docKeys: "all",
80
+ create: () => new RowHomeInvariant(),
81
+ },
82
+ {
83
+ scope: "doc",
84
+ id: "list-marker-not-doubled",
85
+ docKeys: "all",
86
+ create: () => new ListMarkerInvariant(),
87
+ },
88
+ {
89
+ scope: "doc",
90
+ id: "wave-width-at-most-three",
91
+ docKeys: ["plan"],
92
+ create: () => new WaveWidthInvariant(),
93
+ },
94
+ {
95
+ scope: "ledger",
96
+ id: "closed-wave-fits-depends-on-layers",
97
+ docKeys: ["plan"],
98
+ create: () => new LedgerLayeringRule(),
99
+ },
100
+ {
101
+ scope: "ledger",
102
+ id: "planned-tasks-vs-recorded-tasks",
103
+ docKeys: ["plan"],
104
+ create: () => new LedgerTaskSetRule(),
105
+ },
106
+ ];