@oscaner-skills/cdd-engine 2.0.0 → 3.0.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 (84) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/package.json +4 -3
  4. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  5. package/src-next/__tests__/floor.guard.test.ts +69 -0
  6. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  7. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  8. package/src-next/__tests__/smoke.integration.test.ts +60 -77
  9. package/src-next/__tests__/support/strip-comments.ts +99 -0
  10. package/src-next/__tests__/zero-dep.test.ts +6 -46
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +39 -21
  12. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +40 -28
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +40 -23
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +38 -21
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +21 -6
  16. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +22 -12
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +23 -8
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +21 -6
  19. package/src-next/contract/__tests__/declare.test.ts +251 -12
  20. package/src-next/contract/__tests__/doc.test.ts +214 -45
  21. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  22. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  23. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  24. package/src-next/contract/__tests__/judge.test.ts +410 -172
  25. package/src-next/contract/__tests__/lint.test.ts +49 -39
  26. package/src-next/contract/__tests__/project.test.ts +60 -19
  27. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  28. package/src-next/contract/declare.ts +179 -91
  29. package/src-next/contract/doc.ts +227 -164
  30. package/src-next/contract/frontmatter.ts +233 -0
  31. package/src-next/contract/home-extractors.ts +397 -0
  32. package/src-next/contract/invariants.ts +214 -69
  33. package/src-next/contract/judge.ts +28 -19
  34. package/src-next/contract/lint.ts +5 -41
  35. package/src-next/contract/project.ts +103 -43
  36. package/src-next/contract/skill-anatomy.ts +39 -11
  37. package/src-next/face/__tests__/board-view.test.ts +318 -115
  38. package/src-next/face/__tests__/capsule.test.ts +49 -25
  39. package/src-next/face/__tests__/channel-closure.guard.test.ts +28 -1
  40. package/src-next/face/__tests__/cli.test.ts +1091 -837
  41. package/src-next/face/__tests__/face.test.ts +5 -5
  42. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  43. package/src-next/face/__tests__/preview.test.ts +374 -0
  44. package/src-next/face/__tests__/projection.test.ts +5 -3
  45. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  46. package/src-next/face/__tests__/termination.test.ts +650 -0
  47. package/src-next/face/artifacts.ts +90 -37
  48. package/src-next/face/board-view.ts +128 -138
  49. package/src-next/face/capsule.ts +30 -16
  50. package/src-next/face/cli.ts +306 -97
  51. package/src-next/face/declare.ts +15 -18
  52. package/src-next/face/gate.ts +19 -18
  53. package/src-next/face/host.ts +6 -30
  54. package/src-next/face/lifecycle.ts +213 -188
  55. package/src-next/face/preview.ts +151 -0
  56. package/src-next/face/projection.ts +4 -1
  57. package/src-next/face/route-render.ts +39 -14
  58. package/src-next/face/termination.ts +573 -0
  59. package/src-next/face/words.ts +20 -2
  60. package/src-next/infra/__tests__/infra.test.ts +49 -3
  61. package/src-next/infra/__tests__/root.test.ts +56 -0
  62. package/src-next/infra/doc-roots.ts +29 -0
  63. package/src-next/infra/root.ts +73 -0
  64. package/src-next/infra/runtime.ts +12 -65
  65. package/src-next/infra/workspace.ts +95 -5
  66. package/src-next/render/__tests__/render.test.ts +92 -41
  67. package/src-next/render/__tests__/skeleton.test.ts +282 -64
  68. package/src-next/render/issue-body.ts +5 -2
  69. package/src-next/render/skeleton.ts +155 -90
  70. package/src-next/render/templates.ts +51 -56
  71. package/src-next/session/__tests__/graph.test.ts +11 -4
  72. package/src-next/session/__tests__/ledger.test.ts +3 -2
  73. package/src-next/session/__tests__/next.test.ts +100 -8
  74. package/src-next/session/__tests__/preflight.test.ts +79 -25
  75. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  76. package/src-next/session/__tests__/run.test.ts +140 -128
  77. package/src-next/session/__tests__/wave.test.ts +11 -4
  78. package/src-next/session/ledger.ts +96 -24
  79. package/src-next/session/next.ts +116 -15
  80. package/src-next/session/preflight.ts +41 -10
  81. package/src-next/session/round-naming.ts +84 -0
  82. package/src-next/session/run.ts +24 -20
  83. package/templates/report/issue-body.json +0 -46
  84. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
@@ -8,22 +8,36 @@
8
8
  // Issue inventory / Phase inventory / Change history) + the
9
9
  // dependency-graph edge lines; plan → the `### Task N:` blocks
10
10
  // and their fields; phase-spec → the `## Design` double-layer
11
- // skeleton (groups + items). Nothing is decided here — parse
12
- // extracts, the invariant family judges.
11
+ // skeleton (groups + items). The WHICH — which headings are
12
+ // sections, which lines are table rows, which lines are the
13
+ // declared column header — comes from the home extractors over
14
+ // the registry's declared anchors (home-extractors.ts, spec
15
+ // §3.2); this face only walks the resulting structure. Nothing
16
+ // is decided here — parse extracts, the invariant family judges.
13
17
  // · projection — each class consumes the derived projection face (project.ts):
14
18
  // the slices (parse regexes) and the shape (section skeleton) of
15
19
  // its own doc type are the locating data every extraction walks.
16
- // · chain root — the Class-A/B anchors of the document (the plan's `**Spec:**`
17
- // link, the `**Parent program**` link + its version tokens, the
18
- // overall's Phase-inventory rows as the chain's anchor set) are
19
- // extracted into a ChainRoot and LEFT as an interface — the
20
+ // · chain root — the Class-A/B anchors of the document (the plan/spec head
21
+ // scalars `spec:` / `parent-program:` / `parent-version:` and
22
+ // the overall's Phase-inventory rows as the chain's anchor set)
23
+ // are extracted into a ChainRoot and LEFT as an interface — the
20
24
  // resolution judgment belongs to the cross-doc-chain invariant,
21
25
  // never to a DocType method.
22
26
  //
23
27
  // Module-level exports are types / the class family / one composition root — zero
24
28
  // behavior-carrying bare functions (the plan's zero-bare-function discipline).
25
29
 
30
+ import type { ElementRegistry } from "./declare.ts";
26
31
  import { declaredRegistries } from "./declare.ts";
32
+ import type { FrontMatterHead } from "./frontmatter.ts";
33
+ import type { ExtractionMap } from "./home-extractors.ts";
34
+ import {
35
+ DesignBodyExtractor,
36
+ GraphExtractor,
37
+ HeadingScanner,
38
+ TableExtractor,
39
+ TaskExtractor,
40
+ } from "./home-extractors.ts";
27
41
  import type { DocKey, DocShape, DocSlices, ElementSlice } from "./project.ts";
28
42
  import { Projector } from "./project.ts";
29
43
 
@@ -31,6 +45,15 @@ import { Projector } from "./project.ts";
31
45
  * shared by the four parser classes (each binds its own doc-type faces). */
32
46
  const projector = new Projector(declaredRegistries);
33
47
 
48
+ /** The home-driven extractors — the fixed structure rules of the task / design /
49
+ * graph / table / section homes (spec §3.2), shared by the parsers that read
50
+ * those surfaces. */
51
+ const taskExtractor = new TaskExtractor();
52
+ const designExtractor = new DesignBodyExtractor();
53
+ const graphExtractor = new GraphExtractor();
54
+ const tableExtractor = new TableExtractor();
55
+ const headingScanner = new HeadingScanner();
56
+
34
57
  // ---------------------------------------------------------------------------
35
58
  // shared structural types
36
59
  // ---------------------------------------------------------------------------
@@ -84,52 +107,59 @@ export interface GraphEdge {
84
107
  export interface ChainPhase {
85
108
  /** The registered phase id (e.g. "P2.1"). */
86
109
  id: string;
87
- /** The Design-spec cell text (link tokens, e.g. `[P2-design](docs/kairos/specs/x-design.md)`). */
110
+ /** The Design-spec cell text (link tokens, e.g. a spec-root link under the
111
+ * declared spec doc root — `[P2-design](<spec-root>/x-design.md)`). */
88
112
  designCell: string;
89
- /** The Implementation-plan cell text (link tokens, e.g. `[plan](docs/kairos/plans/x.md)`). */
113
+ /** The Implementation-plan cell text (link tokens, e.g. a plan-root link under
114
+ * the declared plan doc root — `[plan](<plan-root>/x.md)`). */
90
115
  planCell: string;
91
116
  /** The Dependency cell text (e.g. "P1 -> P2"). */
92
117
  dependencyCell: string;
93
118
  }
94
119
 
95
- /** A `[label](target)` link parsed from a line. */
120
+ /** A `[text](target)` link parsed from a line — only the target surfaces: the
121
+ * link-text face retired with the front-matter flip (the chain root reads the
122
+ * head scalars, and the drift judgments are gone — zero consumer ever reads the
123
+ * text part). */
96
124
  export interface ChainLink {
97
- /** The link's label text. */
98
- label: string;
99
125
  /** The link's target path. */
100
126
  target: string;
101
127
  }
102
128
 
103
129
  /**
104
- * The cross-doc chain root — the Class-A/B anchors a document carries, extracted
105
- * verbatim and left unresolved. Every resolution judgment (target existence, label
106
- * vs. basename drift, version-token lineage membership) belongs to the
107
- * cross-doc-chain / file-existence / sibling-scan invariants.
130
+ * The cross-doc chain root — the Class-A/B anchors a document carries, read from
131
+ * the front-matter head scalars (the §2.3 key set: `spec:` · `parent-program:` ·
132
+ * `parent-version:` · `depends-on:`), plus the overall's Phase-inventory rows.
133
+ * Extracted and LEFT as an interface — every resolution judgment (target
134
+ * existence, version-token lineage membership) belongs to the cross-doc-chain /
135
+ * file-existence / sibling-scan invariants, never to a DocType method.
108
136
  */
109
137
  export interface ChainRoot {
110
138
  /** The doc-type identity of the chain root's document. */
111
- docType: "overall-spec" | "plan" | "phase-spec" | "single-spec";
112
- /** The `**Parent program**` link (Class-B) — the parent overall reference of a
139
+ docType: DocKey;
140
+ /** The `parent-program:` link (Class-B) — the parent overall reference of a
113
141
  * plan/spec document; null for the overall (the chain root itself). */
114
142
  parentLink: ChainLink | null;
115
- /** The `**Spec:**` link (Class-A) — the plan's design-spec reference; null for the
143
+ /** The `spec:` link (Class-A) — the plan's design-spec reference; null for the
116
144
  * overall (no spec to reference) and for a spec (the document IS the design spec). */
117
145
  specLink: ChainLink | null;
118
- /** The version tokens carried on the `**Parent program**` line (Class-B lineage). */
146
+ /** The version tokens carried on the `parent-program:` key (Class-B lineage). */
119
147
  parentTokens: readonly string[];
120
148
  /** The overall's phase-inventory rows — the chain's anchor set (overall only). */
121
149
  phases: readonly ChainPhase[];
122
- /** The `**Depends on**` header value (plan/spec), verbatim, when the line is present. */
150
+ /** The `depends-on:` front-matter value (plan/spec), verbatim, when the key is present. */
123
151
  dependsOn: string | null;
124
152
  }
125
153
 
126
154
  /** The overall parse record — the four tables, the graph edges and the chain root. */
127
155
  export interface OverallParsed {
128
156
  docType: "overall-spec";
129
- /** The `# Title` line verbatim. */
157
+ /** The document's front-matter head — the typed head record (the §2.3 key set),
158
+ * or null when parsed without one (the chainDocs producers MUST parse
159
+ * dual-param — a head-less plan/spec parse reads a null chain face). */
160
+ head: FrontMatterHead | null;
161
+ /** The document title — the front-matter `title:` scalar ("" without a head). */
130
162
  title: string;
131
- /** The header bullet lines (between the title and the first section heading). */
132
- headerLines: readonly string[];
133
163
  /** The `##`-ranked sections in document order. */
134
164
  sections: readonly SectionBlock[];
135
165
  /** The parsed overall tables (each present only when its section was found). */
@@ -176,8 +206,10 @@ export interface TaskBlock {
176
206
  /** The plan parse record — the header, the constraints section and the task blocks. */
177
207
  export interface PlanParsed {
178
208
  docType: "plan";
209
+ /** The document's front-matter head, or null when parsed without one. */
210
+ head: FrontMatterHead | null;
211
+ /** The document title — the front-matter `title:` scalar ("" without a head). */
179
212
  title: string;
180
- headerLines: readonly string[];
181
213
  sections: readonly SectionBlock[];
182
214
  /** The `### Task N:` blocks in document order. */
183
215
  taskBlocks: readonly TaskBlock[];
@@ -205,8 +237,10 @@ export interface DesignItem {
205
237
  /** The phase-spec parse record — the header tuple and the design-body skeleton. */
206
238
  export interface PhaseSpecParsed {
207
239
  docType: "phase-spec";
240
+ /** The document's front-matter head, or null when parsed without one. */
241
+ head: FrontMatterHead | null;
242
+ /** The document title — the front-matter `title:` scalar ("" without a head). */
208
243
  title: string;
209
- headerLines: readonly string[];
210
244
  sections: readonly SectionBlock[];
211
245
  /** The `## Design` double-layer skeleton (groups + items), when the section is present. */
212
246
  design: readonly DesignGroup[];
@@ -216,8 +250,10 @@ export interface PhaseSpecParsed {
216
250
  /** The single-spec parse record — the header five-tuple and the prose section surface. */
217
251
  export interface SingleSpecParsed {
218
252
  docType: "single-spec";
253
+ /** The document's front-matter head, or null when parsed without one. */
254
+ head: FrontMatterHead | null;
255
+ /** The document title — the front-matter `title:` scalar ("" without a head). */
219
256
  title: string;
220
- headerLines: readonly string[];
221
257
  sections: readonly SectionBlock[];
222
258
  chain: ChainRoot;
223
259
  }
@@ -230,21 +266,23 @@ export type ParsedDoc = OverallParsed | PlanParsed | PhaseSpecParsed | SingleSpe
230
266
  // ---------------------------------------------------------------------------
231
267
 
232
268
  /**
233
- * The shared extraction primitives: `[label](target)` links, `v<n>.<m>` version
269
+ * The shared extraction primitives: `[text](target)` links, `v<n>.<m>` version
234
270
  * tokens and `|…|` table-row parsing. Both the parse face (DocType) and the
235
271
  * judgment face (the Invariant base in invariants.ts) extend this base — the
236
272
  * link/token/table parse logic lives in exactly one place of the new tree. The
237
273
  * version-token grammar additionally exposes the public static `versionTokensOf`
238
- * — the face plane's doc-line BLOCK reads the SAME grammar through it (one home,
239
- * zero dual-write).
274
+ * — the board's header-fact read (face/board-view.ts) reads the SAME grammar
275
+ * through it (one home, zero dual-write).
240
276
  */
241
277
  export abstract class MarkdownPrimitives {
242
- /** The `[label](target)` pairs parsed from one line. */
278
+ /** The `[text](target)` pairs parsed from one line — the target only (the
279
+ * retired link-text face; the remaining consumers — the overall's phase-cell
280
+ * links — resolve targets, never the text). */
243
281
  protected linksOnLine(line: string): readonly ChainLink[] {
244
282
  const links: ChainLink[] = [];
245
283
  const linkPattern = /\[([^\]]*)\]\(([^)]+)\)/g;
246
284
  for (const match of line.matchAll(linkPattern)) {
247
- links.push({ label: match[1], target: match[2] });
285
+ links.push({ target: match[2] });
248
286
  }
249
287
  return links;
250
288
  }
@@ -267,21 +305,24 @@ export abstract class MarkdownPrimitives {
267
305
  }
268
306
 
269
307
  /** The cells of one `|…|` table line (trimmed, wrapper bars excluded); null for a
270
- * non-table line or a separator row. */
308
+ * non-table line or a separator row. The separator-row rule is the
309
+ * TableExtractor's (the table home's fixed structure rule — one home). */
271
310
  protected tableRowCells(line: string): readonly string[] | null {
272
311
  const trimmed = line.trim();
273
312
  if (!trimmed.startsWith("|") || !trimmed.endsWith("|")) return null;
274
- if (/^\|[\s:|-]+\|$/.test(trimmed)) return null; // separator row
313
+ if (TableExtractor.isSeparatorRow(trimmed)) return null;
275
314
  return trimmed
276
315
  .split("|")
277
316
  .slice(1, -1)
278
317
  .map((cell) => cell.trim());
279
318
  }
280
319
 
281
- /** The non-separator `|…|` rows of a line run (the first row is the column header). */
320
+ /** The non-separator `|…|` rows of a line run (the first row is the column
321
+ * header). The table-line / separator recognition is the TableExtractor's
322
+ * table-home rule; this method only splits the recognized rows into cells. */
282
323
  protected tableRows(lines: readonly string[]): readonly string[][] {
283
324
  const rows: string[][] = [];
284
- for (const line of lines) {
325
+ for (const line of tableExtractor.tableLinesOf(lines)) {
285
326
  const cells = this.tableRowCells(line);
286
327
  if (cells !== null) rows.push([...cells]);
287
328
  }
@@ -297,18 +338,21 @@ export abstract class MarkdownPrimitives {
297
338
  * The abstract doc-type base. Each subclass binds its registry-derived projection
298
339
  * face (slices + shape) and implements parse — pure structural extraction into a
299
340
  * typed record. The base carries the shared extraction primitives (heading blocks,
300
- * table rows, header lines, `[label](target)` link parsing) as class methods: the
341
+ * table rows, header lines, `[text](target)` link parsing) as class methods: the
301
342
  * class face stays judgment-free (zero validate/audit/detect methods).
302
343
  */
303
344
  export abstract class DocType<P extends ParsedDoc> extends MarkdownPrimitives {
304
345
  /** The doc-type record key — the projection-face identity. */
305
346
  readonly key: DocKey;
347
+ /** The declared registry of this doc type — the extractors read their anchor
348
+ * rosters from it (the registry stays the single knowledge source). */
349
+ readonly registry: ElementRegistry;
306
350
  /** The derived parse face (per-element anchor slices) of this doc type. */
307
351
  readonly slices: DocSlices;
308
352
  /** The derived section skeleton (shape projection) of this doc type. */
309
353
  readonly shape: DocShape;
310
354
  /** The doc-type name as carried by a conforming document's parse record. */
311
- abstract readonly docTypeName: "overall-spec" | "plan" | "phase-spec" | "single-spec";
355
+ abstract readonly docTypeName: DocKey;
312
356
 
313
357
  /** The per-anchor slice lookup — the parse face's locating patterns. */
314
358
  readonly #slicesByAnchor: ReadonlyMap<string, ElementSlice>;
@@ -316,13 +360,17 @@ export abstract class DocType<P extends ParsedDoc> extends MarkdownPrimitives {
316
360
  constructor(key: DocKey) {
317
361
  super();
318
362
  this.key = key;
363
+ this.registry = declaredRegistries[key];
319
364
  this.slices = projector.slices()[key];
320
365
  this.shape = projector.shape()[key];
321
366
  this.#slicesByAnchor = new Map(this.slices.slices.map((slice) => [slice.anchor, slice]));
322
367
  }
323
368
 
324
- /** The pure structural parse — what the invariants and the graph read. */
325
- abstract parse(lines: readonly string[]): P;
369
+ /** The pure structural parse — what the invariants and the graph read. The head
370
+ * is the typed front-matter head (the §2.2 delivery seam: the chain-docs
371
+ * producers MUST parse dual-param, so the chain root reads the head scalars — a
372
+ * single-param parse yields the null-head face: title "" and a null chain). */
373
+ abstract parse(lines: readonly string[], head?: FrontMatterHead | null): P;
326
374
 
327
375
  // -------------------------------------------------------------------------
328
376
  // shared extraction primitives (parse-only, never judgment)
@@ -355,44 +403,60 @@ export abstract class DocType<P extends ParsedDoc> extends MarkdownPrimitives {
355
403
  return blocks;
356
404
  }
357
405
 
358
- /** The header lines — the `# Title` block's body (metadata lines before the first
359
- * rank-2/rank-3 heading block; heading blocks split at every heading, so the title
360
- * block body already ends where the sections/task blocks begin). */
361
- protected headerLines(blocks: readonly HeadingBlock[]): readonly string[] {
362
- if (blocks.length === 0) return [];
363
- return blocks[0].body;
364
- }
365
-
366
- /** The rank-2 section blocks in document order. */
367
- protected sections(blocks: readonly HeadingBlock[]): SectionBlock[] {
368
- const out: SectionBlock[] = [];
369
- for (const block of blocks) {
370
- if (this.headingRank(block.heading) === 2)
371
- out.push({ heading: block.heading, lines: block.body });
372
- }
373
- return out;
406
+ /** The rank-2 section blocks in document order — the HeadingScanner's section
407
+ * walk over the registry's declared section anchors (spec §3.2: WHICH rank-2
408
+ * headings are sections comes from the registry, never a second hand-written
409
+ * filter here). An undeclared prose rank-2 heading is not a section, and a
410
+ * declared conditional `##` heading is one. */
411
+ protected sections(lines: readonly string[]): SectionBlock[] {
412
+ return headingScanner.sectionsOf(this.registry, lines);
374
413
  }
375
414
 
376
- /** The `### Task N:` blocks in document order, with their field + step surfaces. */
415
+ /** The `### Task N:` blocks in document order, with their field + step surfaces.
416
+ * The block-head / field-marker / step-line grammars live in the TaskExtractor
417
+ * (the task home's fixed structure rules over the registry's declared anchors):
418
+ * each block is extracted over its own lines, so the extractor's own scoping
419
+ * (the fields, and the steps riding inside the `**Steps**` field) yields that
420
+ * block's occurrence buckets directly — step recognition never re-appears here. */
377
421
  protected taskBlocks(blocks: readonly HeadingBlock[]): TaskBlock[] {
378
422
  const out: TaskBlock[] = [];
379
423
  for (const block of blocks) {
380
- const match = block.heading.match(/^### Task (\d+):/);
381
- if (match === null) continue;
382
- const fields = this.parseTaskFields(block.body);
383
- const stepsField = fields.find((field) => field.key === "Steps");
424
+ const lines = [block.heading, ...block.body];
425
+ const extracted = taskExtractor.extract(this.registry, lines);
426
+ const headings = extracted["### Task N:"] ?? [];
427
+ if (headings.length === 0) continue;
428
+ const ids = extracted["Task id token"] ?? [];
429
+ const id = Number(ids[0] ?? "");
430
+ if (Number.isNaN(id)) continue;
431
+ const fields = this.#taskFieldsOf(block.body, this.#taskFieldMarkers(extracted));
384
432
  out.push({
385
- id: Number(match[1]),
433
+ id,
386
434
  heading: block.heading,
387
435
  fields,
388
- steps: this.parseSteps(stepsField),
436
+ steps: this.#taskStepsOf(
437
+ extracted["Step action"] ?? [],
438
+ new Set(extracted["Step checkable"] ?? []),
439
+ ),
389
440
  });
390
441
  }
391
442
  return out;
392
443
  }
393
444
 
394
- /** Parse a task block's body into keyed fields. */
395
- protected parseTaskFields(body: readonly string[]): TaskField[] {
445
+ /** The task-field anchor lookup — each declared field anchor's marker line maps
446
+ * to its anchor (the retired per-anchor field grammar collapses to one map). */
447
+ #taskFieldMarkers(extracted: ExtractionMap): ReadonlyMap<string, string> {
448
+ const markers = new Map<string, string>();
449
+ for (const [anchor, lines] of Object.entries(extracted)) {
450
+ if (!anchor.startsWith("**")) continue;
451
+ for (const line of lines) markers.set(line, anchor);
452
+ }
453
+ return markers;
454
+ }
455
+
456
+ /** Parse a task block's body into keyed fields — the marker membership comes
457
+ * from the extractor's field-anchor map; the remainder and continuation
458
+ * handling mirror the retired grammar's behavior exactly. */
459
+ #taskFieldsOf(body: readonly string[], markers: ReadonlyMap<string, string>): TaskField[] {
396
460
  const fields: TaskField[] = [];
397
461
  let openKey: string | null = null;
398
462
  let openLines: string[] = [];
@@ -402,11 +466,11 @@ export abstract class DocType<P extends ParsedDoc> extends MarkdownPrimitives {
402
466
  openLines = [];
403
467
  };
404
468
  for (const line of body) {
405
- const fieldMarker = line.match(/^-\s+\*\*([A-Za-z ]+)\*\*:\s*(.*)$/);
406
- if (fieldMarker !== null) {
469
+ const anchor = markers.get(line);
470
+ if (anchor !== undefined) {
407
471
  close();
408
- openKey = fieldMarker[1];
409
- openLines = [fieldMarker[2].trim()];
472
+ openKey = anchor.slice(2, -2);
473
+ openLines = [line.slice(`- ${anchor}:`.length).trim()];
410
474
  } else if (openKey !== null && line.trim().length > 0) {
411
475
  openLines.push(line.trim());
412
476
  }
@@ -415,15 +479,17 @@ export abstract class DocType<P extends ParsedDoc> extends MarkdownPrimitives {
415
479
  return fields;
416
480
  }
417
481
 
418
- /** Parse a `**Steps**` field's value lines into step records. */
419
- protected parseSteps(field: TaskField | undefined): TaskStep[] {
420
- if (field === undefined) return [];
482
+ /** Parse a block's recognized step lines into step records — the lines come
483
+ * from the extractor's `Step action` bucket (the registry's `^- ` shape, so
484
+ * no `- `-bullet re-recognition here); the action cell is a value read after
485
+ * the anchor's bullet prefix (mirroring the `#taskIdOf` slot read), and
486
+ * membership in the `Step checkable` bucket marks which lines carry a
487
+ * verbatim `— checkable:` clause that the split then reads off. */
488
+ #taskStepsOf(stepLines: readonly string[], checkableLines: ReadonlySet<string>): TaskStep[] {
421
489
  const steps: TaskStep[] = [];
422
- for (const line of field.lines) {
423
- const bullet = line.match(/^-\s+(.*)$/);
424
- if (bullet === null) continue;
425
- const text = bullet[1];
426
- const checkableMarker = text.indexOf("— checkable:");
490
+ for (const line of stepLines) {
491
+ const text = line.trim().slice(2).trim();
492
+ const checkableMarker = checkableLines.has(line) ? text.indexOf("— checkable:") : -1;
427
493
  if (checkableMarker === -1) {
428
494
  steps.push({ action: text, checkable: null });
429
495
  } else {
@@ -436,31 +502,22 @@ export abstract class DocType<P extends ParsedDoc> extends MarkdownPrimitives {
436
502
  return steps;
437
503
  }
438
504
 
439
- /** Parse a section's table: the column-header row + the data rows. */
505
+ /** Parse a section's table: the column-header row + the data rows. The header
506
+ * row is the one the registry's `… columns` anchors claim (the TableExtractor's
507
+ * declared-home set); a table with no registered column anchor falls back to
508
+ * the first row, the shape's positional default. The data rows are every
509
+ * remaining row plus any leading row ahead of the declared header — a
510
+ * mispositioned header never silently drops a data row. */
440
511
  protected parseTable(lines: readonly string[]): ParsedTable {
441
512
  const rows = this.tableRows(lines);
442
- const headerRow = rows.length > 0 ? rows[0] : null;
443
- return { heading: "", headerRow, rows: rows.slice(1) };
444
- }
445
-
446
- /** The first `**Marker**:`-style header line by its literal marker. */
447
- protected markerLine(lines: readonly string[], marker: string): string | null {
448
- for (const line of lines) if (line.includes(marker)) return line;
449
- return null;
450
- }
451
-
452
- /** The value token of a `- **Key**: <value>` header line (the text after the marker). */
453
- protected markerValue(line: string, marker: string): string {
454
- const markerIndex = line.indexOf(marker);
455
- if (markerIndex === -1) return "";
456
- const payload = line.slice(markerIndex + marker.length).trim();
457
- return payload.replace(/^:\s*/, "").trim();
458
- }
459
-
460
- /** The line number (1-indexed) the anchor first occurs on, or -1. */
461
- protected indexOfLine(lines: readonly string[], text: string): number {
462
- const index = lines.findIndex((line) => line.includes(text));
463
- return index === -1 ? -1 : index + 1;
513
+ const declaredHeader = tableExtractor.headerLineOf(this.registry, lines);
514
+ if (declaredHeader === null) {
515
+ const headerRow = rows.length > 0 ? rows[0] : null;
516
+ return { heading: "", headerRow, rows: rows.slice(1) };
517
+ }
518
+ const headerCells = this.tableRowCells(declaredHeader);
519
+ const dataRows = rows.filter((row) => row.join("|") !== (headerCells ?? []).join("|"));
520
+ return { heading: "", headerRow: headerCells, rows: dataRows };
464
521
  }
465
522
 
466
523
  /** The slice of one registered anchor (undefined when the anchor is not registered here). */
@@ -494,11 +551,9 @@ export abstract class DocType<P extends ParsedDoc> extends MarkdownPrimitives {
494
551
  export class OverallDocType extends DocType<OverallParsed> {
495
552
  readonly docTypeName = "overall-spec" as const;
496
553
 
497
- parse(lines: readonly string[]): OverallParsed {
498
- const title = lines[0] ?? "";
499
- const blocks = this.headingBlocks(lines);
500
- const headerLines = this.headerLines(blocks);
501
- const sections = this.sections(blocks);
554
+ parse(lines: readonly string[], head: FrontMatterHead | null = null): OverallParsed {
555
+ const title = head?.title ?? "";
556
+ const sections = this.sections(lines);
502
557
 
503
558
  const tables: OverallParsed["tables"] = {
504
559
  "File paths": this.#tableSection(sections, "## File paths"),
@@ -510,8 +565,8 @@ export class OverallDocType extends DocType<OverallParsed> {
510
565
  const phases = this.#phaseRows(tables["Phase inventory"]);
511
566
  return {
512
567
  docType: "overall-spec",
568
+ head,
513
569
  title,
514
- headerLines,
515
570
  sections,
516
571
  tables,
517
572
  graphEdges,
@@ -526,14 +581,22 @@ export class OverallDocType extends DocType<OverallParsed> {
526
581
  };
527
582
  }
528
583
 
529
- /** The `## Dependency graph` edge lines, parsed into from/to tokens. */
584
+ /** The `## Dependency graph` edge lines — the graph-home occurrence map (the
585
+ * declared Hard/Soft edge anchors) identified by the extractor; the from/to
586
+ * token grammar stays the preserved graph-edge primitive. */
530
587
  #graphEdges(sections: readonly SectionBlock[]): GraphEdge[] {
531
588
  for (const section of sections) {
532
589
  if (!this.sectionConforms(section.heading, "## Dependency graph")) continue;
590
+ const extracted = graphExtractor.extract(this.registry, section.lines);
591
+ const edgeLines = new Set<string>([
592
+ ...(extracted["Hard edge"] ?? []),
593
+ ...(extracted["Soft edge"] ?? []),
594
+ ]);
533
595
  const edges: GraphEdge[] = [];
534
596
  const edgePattern = /^P(\d+(?:\.\d+)*)\s*->\s*P(\d+(?:\.\d+)*)$/;
535
597
  for (const line of section.lines) {
536
598
  const trimmed = line.trim();
599
+ if (!edgeLines.has(trimmed)) continue;
537
600
  const match = trimmed.match(edgePattern);
538
601
  if (match !== null) edges.push({ text: trimmed, from: `P${match[1]}`, to: `P${match[2]}` });
539
602
  }
@@ -567,11 +630,12 @@ export class OverallDocType extends DocType<OverallParsed> {
567
630
  return phases;
568
631
  }
569
632
 
570
- /** The phase id of a Phase-inventory data row — the cell carrying a phase-id token
571
- * (the first `#` column cell in the canonical repo row form, where the `Phase`
572
- * column holds the phase name). A numeric-led row falls back to its `Phase` cell. */
633
+ /** The phase id of a Phase-inventory data row — the cell carrying a phase-id
634
+ * token (the token shape judged through the declared `Phase id token` value
635
+ * pattern — the retired literal grammar now sourced from the registry). */
573
636
  #phaseId(row: readonly string[]): string {
574
- const idCell = row.find((cell) => /^P\d+(\.\d+)*$/.test(cell.trim()));
637
+ const pattern = this.sliceOf("Phase id token")?.valuePattern;
638
+ const idCell = row.find((cell) => pattern?.test(cell.trim()) === true);
575
639
  return idCell === undefined ? "" : idCell.trim();
576
640
  }
577
641
 
@@ -588,40 +652,37 @@ export class OverallDocType extends DocType<OverallParsed> {
588
652
  }
589
653
 
590
654
  /**
591
- * The plan doc type — parses the header (Class-A `**Spec:**` + Class-B parent
655
+ * The plan doc type — parses the head (Class-A `spec:` + Class-B parent
592
656
  * lineage) and the `### Task N:` task blocks.
593
657
  */
594
658
  export class PlanDocType extends DocType<PlanParsed> {
595
659
  readonly docTypeName = "plan" as const;
596
660
 
597
- parse(lines: readonly string[]): PlanParsed {
598
- const title = lines[0] ?? "";
661
+ parse(lines: readonly string[], head: FrontMatterHead | null = null): PlanParsed {
662
+ const title = head?.title ?? "";
599
663
  const blocks = this.headingBlocks(lines);
600
- const headerLines = this.headerLines(blocks);
601
664
  return {
602
665
  docType: "plan",
666
+ head,
603
667
  title,
604
- headerLines,
605
- sections: this.sections(blocks),
668
+ sections: this.sections(lines),
606
669
  taskBlocks: this.taskBlocks(blocks),
607
- chain: this.chainRoot(headerLines),
670
+ chain: this.chainRoot(head),
608
671
  };
609
672
  }
610
673
 
611
- /** The plan's cross-doc chain root: Class-A `**Spec:**` + Class-B `**Parent program**`. */
612
- chainRoot(headerLines: readonly string[]): ChainRoot {
613
- const specLine = this.markerLine(headerLines, "**Spec:**");
614
- const specLinks = specLine === null ? [] : this.linksOnLine(specLine);
615
- const parentLine = this.markerLine(headerLines, "**Parent program**");
616
- const parentLinks = parentLine === null ? [] : this.linksOnLine(parentLine);
617
- const dependsOnLine = this.markerLine(headerLines, "**Depends on**");
674
+ /** The plan's cross-doc chain root — the Class-A `spec:` + Class-B
675
+ * `parent-program:`/`parent-version:` head scalars (the §2.2 delivery seam:
676
+ * the chain facts ride the typed head, never a body line scan). */
677
+ chainRoot(head: FrontMatterHead | null): ChainRoot {
618
678
  return {
619
679
  docType: "plan",
620
- parentLink: parentLinks.length > 0 ? parentLinks[0] : null,
621
- specLink: specLinks.length > 0 ? specLinks[0] : null,
622
- parentTokens: parentLine === null ? [] : this.versionTokens(parentLine),
680
+ parentLink:
681
+ head === null || head.parentProgram === null ? null : { target: head.parentProgram },
682
+ specLink: head === null || head.spec === null ? null : { target: head.spec },
683
+ parentTokens: head === null || head.parentVersion === null ? [] : [head.parentVersion],
623
684
  phases: [],
624
- dependsOn: dependsOnLine === null ? null : this.markerValue(dependsOnLine, "**Depends on**"),
685
+ dependsOn: head?.dependsOn ?? null,
625
686
  };
626
687
  }
627
688
  }
@@ -633,23 +694,30 @@ export class PlanDocType extends DocType<PlanParsed> {
633
694
  export class PhaseSpecDocType extends DocType<PhaseSpecParsed> {
634
695
  readonly docTypeName = "phase-spec" as const;
635
696
 
636
- parse(lines: readonly string[]): PhaseSpecParsed {
637
- const title = lines[0] ?? "";
697
+ parse(lines: readonly string[], head: FrontMatterHead | null = null): PhaseSpecParsed {
698
+ const title = head?.title ?? "";
638
699
  const blocks = this.headingBlocks(lines);
639
- const headerLines = this.headerLines(blocks);
640
700
  return {
641
701
  docType: "phase-spec",
702
+ head,
642
703
  title,
643
- headerLines,
644
- sections: this.sections(blocks),
704
+ sections: this.sections(lines),
645
705
  design: this.designFromBlocks(blocks),
646
- chain: this.chainRoot(headerLines),
706
+ chain: this.chainRoot(head),
647
707
  };
648
708
  }
649
709
 
650
- /** The design double-layer skeleton — the `### N.` groups + their `#### N.M` items
651
- * between the `## Design` section and the next rank-2 heading. */
710
+ /** The design double-layer skeleton — the `### N.` groups + their `#### N.M`
711
+ * items between the `## Design` section and the next rank-2 heading. The
712
+ * numbered-heading grammars (and their number/text decomposition) live in the
713
+ * DesignBodyExtractor; this method walks the declared groups/items from its
714
+ * occurrence map. */
652
715
  designFromBlocks(blocks: readonly HeadingBlock[]): DesignGroup[] {
716
+ const lines = blocks.flatMap((block) => [block.heading, ...block.body]);
717
+ const extracted = designExtractor.extract(this.registry, lines);
718
+ const designHeadings = new Set(extracted["## Design"] ?? []);
719
+ const groupHeadings = new Set(extracted["### N. group heading"] ?? []);
720
+ const itemHeadings = new Set(extracted["#### N.M item heading"] ?? []);
653
721
  const groups: DesignGroup[] = [];
654
722
  let openNumber: string | null = null;
655
723
  let openHeading = "";
@@ -667,38 +735,36 @@ export class PhaseSpecDocType extends DocType<PhaseSpecParsed> {
667
735
  const rank = this.headingRank(block.heading);
668
736
  if (rank === 2) {
669
737
  if (inDesign) break;
670
- if (this.sectionConforms(block.heading, "## Design")) inDesign = true;
738
+ if (designHeadings.has(block.heading)) inDesign = true;
671
739
  continue;
672
740
  }
673
741
  if (!inDesign || (rank !== 3 && rank !== 4)) continue;
674
- const groupMatch = block.heading.match(/^### (\d+)\.\s+(.*)$/);
675
- if (groupMatch !== null) {
742
+ if (groupHeadings.has(block.heading)) {
676
743
  close();
677
- openNumber = groupMatch[1];
678
- openHeading = groupMatch[2];
744
+ const group = designExtractor.groupOf(block.heading);
745
+ openNumber = group.number;
746
+ openHeading = group.heading;
679
747
  continue;
680
748
  }
681
- const itemMatch = block.heading.match(/^#### (\d+)\.(\d+)\s+(.*)$/);
682
- if (itemMatch !== null && openNumber !== null) {
683
- openItems.push({ number: `${itemMatch[1]}.${itemMatch[2]}`, heading: itemMatch[3] });
749
+ if (openNumber !== null && itemHeadings.has(block.heading)) {
750
+ openItems.push(designExtractor.itemOf(block.heading));
684
751
  }
685
752
  }
686
753
  close();
687
754
  return groups;
688
755
  }
689
756
 
690
- /** The phase-spec's cross-doc chain root: the Class-B `**Parent program**` lineage. */
691
- chainRoot(headerLines: readonly string[]): ChainRoot {
692
- const parentLine = this.markerLine(headerLines, "**Parent program**");
693
- const parentLinks = parentLine === null ? [] : this.linksOnLine(parentLine);
694
- const dependsOnLine = this.markerLine(headerLines, "**Depends on**");
757
+ /** The phase-spec's cross-doc chain root: the Class-B `parent-program:`
758
+ * `parent-version:` head scalars. */
759
+ chainRoot(head: FrontMatterHead | null): ChainRoot {
695
760
  return {
696
761
  docType: "phase-spec",
697
- parentLink: parentLinks.length > 0 ? parentLinks[0] : null,
762
+ parentLink:
763
+ head === null || head.parentProgram === null ? null : { target: head.parentProgram },
698
764
  specLink: null,
699
- parentTokens: parentLine === null ? [] : this.versionTokens(parentLine),
765
+ parentTokens: head === null || head.parentVersion === null ? [] : [head.parentVersion],
700
766
  phases: [],
701
- dependsOn: dependsOnLine === null ? null : this.markerValue(dependsOnLine, "**Depends on**"),
767
+ dependsOn: head?.dependsOn ?? null,
702
768
  };
703
769
  }
704
770
  }
@@ -707,35 +773,32 @@ export class PhaseSpecDocType extends DocType<PhaseSpecParsed> {
707
773
  * The single-spec doc type — parses the header five-tuple surface and the prose
708
774
  * section surface. A single-spec carries no parent overall and no `### N.`
709
775
  * design outline, so the parse degrades the chain root to its null-link face
710
- * (the `**Depends on**` header value is the only chain fact carried).
776
+ * (the `depends-on:` front-matter value is the only chain fact carried).
711
777
  */
712
778
  export class SingleSpecDocType extends DocType<SingleSpecParsed> {
713
779
  readonly docTypeName = "single-spec" as const;
714
780
 
715
- parse(lines: readonly string[]): SingleSpecParsed {
716
- const title = lines[0] ?? "";
717
- const blocks = this.headingBlocks(lines);
718
- const headerLines = this.headerLines(blocks);
781
+ parse(lines: readonly string[], head: FrontMatterHead | null = null): SingleSpecParsed {
782
+ const title = head?.title ?? "";
719
783
  return {
720
784
  docType: "single-spec",
785
+ head,
721
786
  title,
722
- headerLines,
723
- sections: this.sections(blocks),
724
- chain: this.chainRoot(headerLines),
787
+ sections: this.sections(lines),
788
+ chain: this.chainRoot(head),
725
789
  };
726
790
  }
727
791
 
728
792
  /** The single-spec chain root — the degraded face: no parent link / no spec
729
- * link (the independent-program shape), the `**Depends on**` value only. */
730
- chainRoot(headerLines: readonly string[]): ChainRoot {
731
- const dependsOnLine = this.markerLine(headerLines, "**Depends on**");
793
+ * link (the independent-program shape), the `depends-on:` value only. */
794
+ chainRoot(head: FrontMatterHead | null): ChainRoot {
732
795
  return {
733
796
  docType: "single-spec",
734
797
  parentLink: null,
735
798
  specLink: null,
736
799
  parentTokens: [],
737
800
  phases: [],
738
- dependsOn: dependsOnLine === null ? null : this.markerValue(dependsOnLine, "**Depends on**"),
801
+ dependsOn: head?.dependsOn ?? null,
739
802
  };
740
803
  }
741
804
  }