@oscaner-skills/cdd-engine 3.1.0 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,325 @@
1
+ // packages/cdd-engine/src-next/infra/slug-index.ts
2
+ // The identity index (spec §2.1/§2.2): ONE scan over the doc roots
3
+ // (`ENGINE_RUNTIME.docRoots`) groups every document by its front-matter facts.
4
+ // The index is the single judgment surface for document identity:
5
+ // · lookups — `identityDoc` / `planOf` / `phaseSpecsOf` / `overallOf` / `entryAt`;
6
+ // · violations — duplicate identity document · duplicate plan · missing `slug:` ·
7
+ // illegal `slug:` value · `program:` target with no overall document.
8
+ // Identity is the `slug:` value, never the file name; a document's class is its
9
+ // declared `doc-type:`, never the directory it happens to live in. Both the board
10
+ // and the dispatch pre-flight read THIS judgment — zero second implementation.
11
+ //
12
+ // One directory listing per doc root (`#entryNames`) plus one content read per
13
+ // candidate (`#readDoc`) — the ONE document predicate both scan legs share: a
14
+ // `*.md` name whose content reads is a document, whatever produced the name list.
15
+ // Zero filename derivation, zero `existsSync` path guessing.
16
+ // Module-level exports are types / the class — zero behavior-carrying bare
17
+ // functions (the plan's zero-bare-function discipline).
18
+ import { readdirSync, readFileSync, statSync } from "node:fs";
19
+ import path from "node:path";
20
+ import { SLUG_VALUE_PATTERN } from "../contract/declare.js";
21
+ import { FrontMatterExtractor } from "../contract/frontmatter.js";
22
+ import { DOC_KEYS } from "../contract/project.js";
23
+ import { ENGINE_RUNTIME } from "./runtime.js";
24
+ /**
25
+ * SlugIndex — the identity index over the doc roots. Construct it through
26
+ * `build` (the one scanning entry point); every lookup and the violation list
27
+ * read the single materialized scan.
28
+ */
29
+ export class SlugIndex {
30
+ /** The legal `slug:` value form (spec §2.1): 1–128 characters, an alphanumeric
31
+ * first character, then alphanumerics / `.` / `_` / `-`. The slug doubles as a
32
+ * workspace directory name, so path separators and whitespace are rejected at
33
+ * the value surface. Compiled from the registry declaration's own source string
34
+ * (`SLUG_VALUE_PATTERN`) — one grammar, zero second spelling. */
35
+ static #SLUG_PATTERN = new RegExp(SLUG_VALUE_PATTERN);
36
+ /** Whether a raw `slug:` value is a legal identity value (spec §2.1) — the ONE
37
+ * spelling of the value judgment the board marker, the dispatch carrier and the
38
+ * pre-flight gate all read. Narrows a nullable raw value to a legal slug. */
39
+ static isLegalSlug(value) {
40
+ return value !== null && SlugIndex.#SLUG_PATTERN.test(value);
41
+ }
42
+ /** Whether a repo-relative path lies inside any doc root — pure path
43
+ * grammar, zero document reads. The board's not-found face uses this (plus an
44
+ * existence probe) to refuse an outside-root or absent path BEFORE the identity
45
+ * scan opens a single document (spec §3.1). */
46
+ static insideDocRoots(rel) {
47
+ const normalized = path.normalize(rel);
48
+ return Object.values(ENGINE_RUNTIME.docRoots).some((root) => {
49
+ const prefix = path.normalize(root);
50
+ return normalized === prefix || normalized.startsWith(`${prefix}${path.sep}`);
51
+ });
52
+ }
53
+ /** Every indexed document, ordered by repo-relative path. */
54
+ entries;
55
+ /** The rel → entry lookup. */
56
+ #byRel;
57
+ /** The valid-slug → entries lookup (an illegal value never groups). */
58
+ #bySlug;
59
+ /** The materialized judgment over this scan. */
60
+ #violations;
61
+ constructor(entries) {
62
+ this.entries = entries;
63
+ const byRel = new Map();
64
+ const bySlug = new Map();
65
+ for (const entry of entries) {
66
+ byRel.set(entry.rel, entry);
67
+ if (!SlugIndex.isLegalSlug(entry.slug))
68
+ continue;
69
+ const group = bySlug.get(entry.slug);
70
+ if (group === undefined)
71
+ bySlug.set(entry.slug, [entry]);
72
+ else
73
+ group.push(entry);
74
+ }
75
+ this.#byRel = byRel;
76
+ this.#bySlug = bySlug;
77
+ this.#violations = SlugIndex.#judge(entries, bySlug);
78
+ }
79
+ /** Scan every doc root once and index every `.md` document under them. The
80
+ * optional `fs` is the caller's scan seam (the judgment plane's in-memory
81
+ * `DocFs`); absent, the node:fs scan is the production default. */
82
+ static build(repoRoot, fs) {
83
+ const entries = [
84
+ ...SlugIndex.#scanRoot(repoRoot, ENGINE_RUNTIME.docRoots.overalls, fs),
85
+ ...SlugIndex.#scanRoot(repoRoot, ENGINE_RUNTIME.docRoots.specs, fs),
86
+ ...SlugIndex.#scanRoot(repoRoot, ENGINE_RUNTIME.docRoots.plans, fs),
87
+ ].sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
88
+ return new SlugIndex(entries);
89
+ }
90
+ /** The entry at one repo-root-relative path, or null when the path is not indexed. */
91
+ entryAt(rel) {
92
+ return this.#byRel.get(rel) ?? null;
93
+ }
94
+ /** The identity document (overall / phase-spec / single-spec) carrying the
95
+ * slug, or null when no identity document does. */
96
+ identityDoc(slug) {
97
+ for (const entry of this.#bySlug.get(slug) ?? []) {
98
+ if (SlugIndex.#isIdentity(entry))
99
+ return entry;
100
+ }
101
+ return null;
102
+ }
103
+ /** The plan document carrying the slug, or null when no plan does. */
104
+ planOf(slug) {
105
+ for (const entry of this.#bySlug.get(slug) ?? []) {
106
+ if (entry.docType === "plan")
107
+ return entry;
108
+ }
109
+ return null;
110
+ }
111
+ /** The phase-spec documents whose `program:` names the program slug, in program
112
+ * order: the slugs' `-p<major>[.<minor>…]` tail numerically (p2 before p10,
113
+ * `p4.1` after `p4`), then the slugs without that tail in rel order. */
114
+ phaseSpecsOf(programSlug) {
115
+ return this.entries
116
+ .filter((entry) => entry.docType === "phase-spec" && entry.program === programSlug)
117
+ .sort(SlugIndex.#phaseCompare);
118
+ }
119
+ /** The overall document carrying the program slug, or null. */
120
+ overallOf(programSlug) {
121
+ for (const entry of this.#bySlug.get(programSlug) ?? []) {
122
+ if (entry.docType === "overall")
123
+ return entry;
124
+ }
125
+ return null;
126
+ }
127
+ /** The materialized violation list (deterministic over the rel-ordered scan). */
128
+ violations() {
129
+ return this.#violations;
130
+ }
131
+ /** The duplicate roles the slug carries in this scan — empty when the slug is
132
+ * unique, `identity` when a second identity document declares it, `plan` when a
133
+ * second plan does (spec §2.1's uniqueness rule). The ONE duplicate judgment the
134
+ * board's row marker, the dispatch carrier and the pre-flight gate share. */
135
+ duplicatedRolesOf(slug) {
136
+ const roles = [];
137
+ for (const violation of this.#violations) {
138
+ if (violation.slug !== slug)
139
+ continue;
140
+ const role = violation.kind === "duplicate-identity"
141
+ ? "identity"
142
+ : violation.kind === "duplicate-plan"
143
+ ? "plan"
144
+ : null;
145
+ if (role !== null && !roles.includes(role))
146
+ roles.push(role);
147
+ }
148
+ return roles;
149
+ }
150
+ /** The identity gate for one document's declared `slug:` — the ONE four-way
151
+ * judgment the dispatch pre-flight and the dispatch carrier share (spec §2.1):
152
+ * present · legal · indexed · unique. The `entryAt` guard keeps a content read
153
+ * the scan did not re-index from judging a stale value. */
154
+ slugVerdict(rel, slug) {
155
+ if (slug === null)
156
+ return { kind: "missing" };
157
+ if (!SlugIndex.isLegalSlug(slug))
158
+ return { kind: "illegal", slug };
159
+ const entry = this.entryAt(rel);
160
+ const duplicated = entry !== null && entry.slug === slug && this.duplicatedRolesOf(slug).length > 0;
161
+ return duplicated ? { kind: "duplicated", slug } : { kind: "accepted", slug };
162
+ }
163
+ /** The phase ordinal a slug carries in its `-p<major>[.<minor>…]` tail — the
164
+ * numeric segments in order, or null when the slug carries no such tail. The
165
+ * segment is read off the IDENTITY value (never the file name). */
166
+ static #phaseOrdinal(slug) {
167
+ if (slug === null)
168
+ return null;
169
+ const match = /-p(\d+(?:\.\d+)*)$/.exec(slug);
170
+ return match === null ? null : match[1].split(".").map(Number);
171
+ }
172
+ /** Program order for phase rows: numbered slugs numerically (p2 before p10,
173
+ * `p4.1` after `p4`), then the unnumbered ones; rel path is the final tie-break
174
+ * so the order stays deterministic over one scan. */
175
+ static #phaseCompare(left, right) {
176
+ const leftOrdinal = SlugIndex.#phaseOrdinal(left.slug);
177
+ const rightOrdinal = SlugIndex.#phaseOrdinal(right.slug);
178
+ if (leftOrdinal !== null && rightOrdinal !== null) {
179
+ const width = Math.max(leftOrdinal.length, rightOrdinal.length);
180
+ for (let index = 0; index < width; index++) {
181
+ const delta = (leftOrdinal[index] ?? 0) - (rightOrdinal[index] ?? 0);
182
+ if (delta !== 0)
183
+ return delta;
184
+ }
185
+ }
186
+ else if (leftOrdinal !== null) {
187
+ return -1;
188
+ }
189
+ else if (rightOrdinal !== null) {
190
+ return 1;
191
+ }
192
+ return left.rel < right.rel ? -1 : left.rel > right.rel ? 1 : 0;
193
+ }
194
+ /** Scan one doc root — the names come from `#entryNames`, the document judgment
195
+ * from the shared `#readDoc` predicate (a `*.md` name whose content reads). An
196
+ * unreadable candidate is not a document. */
197
+ static #scanRoot(repoRoot, root, fs) {
198
+ const entries = [];
199
+ for (const name of SlugIndex.#entryNames(path.join(repoRoot, root), fs)) {
200
+ if (!name.endsWith(".md"))
201
+ continue;
202
+ const rel = path.join(root, name);
203
+ const abs = path.join(repoRoot, rel);
204
+ const content = SlugIndex.#readDoc(abs, fs);
205
+ if (content === null)
206
+ continue;
207
+ const { head } = FrontMatterExtractor.split(content);
208
+ entries.push({
209
+ path: abs,
210
+ rel,
211
+ docType: SlugIndex.#docTypeOf(head.docType),
212
+ slug: head.slug,
213
+ program: head.program,
214
+ version: head.version,
215
+ status: head.status,
216
+ title: head.title,
217
+ });
218
+ }
219
+ return entries;
220
+ }
221
+ /** The entry names of one doc root — the ONE `readdirSync` call site (the
222
+ * injected seam's `list` otherwise). Names only: the document judgment is
223
+ * `#readDoc`'s, so both legs classify the same set (a symlinked document is a
224
+ * document, a directory named `*.md` is not). A missing root lists nothing
225
+ * (ENOENT only); a permission or shape failure of an existing root is a real
226
+ * break — both legs rethrow it rather than index an empty root. */
227
+ static #entryNames(root, fs) {
228
+ if (fs !== undefined)
229
+ return fs.list(root);
230
+ try {
231
+ return readdirSync(root);
232
+ }
233
+ catch (err) {
234
+ if (err.code === "ENOENT")
235
+ return [];
236
+ throw err;
237
+ }
238
+ }
239
+ /** One candidate's content, or null when it is not a readable regular file —
240
+ * the ONE document predicate (read-through = document). The node:fs leg owns the
241
+ * regular-file guard here (a directory, device or broken symlink named `*.md`
242
+ * never reads); the injected leg's `read` answers the same question for its own
243
+ * store. */
244
+ static #readDoc(abs, fs) {
245
+ if (fs !== undefined)
246
+ return fs.read(abs);
247
+ try {
248
+ return statSync(abs).isFile() ? readFileSync(abs, "utf8") : null;
249
+ }
250
+ catch {
251
+ return null;
252
+ }
253
+ }
254
+ /** Narrow a raw `doc-type:` value to the declared domain (the ONE `DOC_KEYS`
255
+ * declaration) — anything else reads null. */
256
+ static #docTypeOf(raw) {
257
+ if (raw === null)
258
+ return null;
259
+ return DOC_KEYS.includes(raw) ? raw : null;
260
+ }
261
+ /** An identity document is any declared spec class — every key except `plan`. */
262
+ static #isIdentity(entry) {
263
+ return entry.docType !== null && entry.docType !== "plan";
264
+ }
265
+ /** Materialize the five violation classes over the scan and its slug groups. */
266
+ static #judge(entries, bySlug) {
267
+ const violations = [];
268
+ for (const entry of entries) {
269
+ if (entry.slug === null) {
270
+ violations.push({
271
+ kind: "missing-slug",
272
+ rel: entry.rel,
273
+ slug: null,
274
+ program: entry.program,
275
+ });
276
+ }
277
+ else if (!SlugIndex.isLegalSlug(entry.slug)) {
278
+ violations.push({
279
+ kind: "invalid-slug",
280
+ rel: entry.rel,
281
+ slug: entry.slug,
282
+ program: entry.program,
283
+ });
284
+ }
285
+ }
286
+ for (const [slug, group] of bySlug) {
287
+ const identities = group.filter((entry) => SlugIndex.#isIdentity(entry));
288
+ for (const duplicate of identities.slice(1)) {
289
+ violations.push({
290
+ kind: "duplicate-identity",
291
+ rel: duplicate.rel,
292
+ slug,
293
+ program: duplicate.program,
294
+ });
295
+ }
296
+ const plans = group.filter((entry) => entry.docType === "plan");
297
+ for (const duplicate of plans.slice(1)) {
298
+ violations.push({
299
+ kind: "duplicate-plan",
300
+ rel: duplicate.rel,
301
+ slug,
302
+ program: duplicate.program,
303
+ });
304
+ }
305
+ }
306
+ const overallSlugs = new Set();
307
+ for (const entry of entries) {
308
+ if (entry.docType === "overall" && entry.slug !== null)
309
+ overallSlugs.add(entry.slug);
310
+ }
311
+ for (const entry of entries) {
312
+ if (entry.docType !== "phase-spec" || entry.program === null)
313
+ continue;
314
+ if (overallSlugs.has(entry.program))
315
+ continue;
316
+ violations.push({
317
+ kind: "missing-program-target",
318
+ rel: entry.rel,
319
+ slug: entry.slug,
320
+ program: entry.program,
321
+ });
322
+ }
323
+ return violations;
324
+ }
325
+ }
@@ -10,28 +10,13 @@
10
10
  // the sub-agent-authored draft face (jsonc-parser + trailing-comma/comment
11
11
  // tolerance — a child-LLM slip never voids a round, a real break still reports
12
12
  // malformed; D39), resolve() is the
13
- // child-path single fact, slugFromDoc is the doc-file → slug derivation
14
- // (`-design`/`-plan` suffix strip), docsOfSlug is the slug → doc-tree reverse
15
- // derivation (the board's file-system-only truth, phase-suffix parse included).
13
+ // child-path single fact. Document identity is NOT derived here: the workspace
14
+ // key is the document's declared `slug:`, judged by the ONE identity index
15
+ // (infra/slug-index.ts).
16
16
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
17
17
  import path from "node:path";
18
18
  import { parse } from "jsonc-parser";
19
19
  import { RepoRoot } from "./root.js";
20
- import { ENGINE_RUNTIME } from "./runtime.js";
21
- /** The slug phase-suffix syntax — the trailing `-p<major>(.<minor>)*` segment
22
- * (spec §3.2 ⑬). This is the ONE source of the phase-suffix grammar: both the
23
- * suffix parse (`Workspace.phaseSuffixOf`, the `-p…$` form) and the board's
24
- * suffix-only match (`BoardView.scanPhases`, the `^p…$` form) compose their
25
- * patterns from this fragment. (Distinct from the doc-contract design-unit value
26
- * syntax `P\d+(\.\d+)*-design` — uppercase + `-design` tail — which is another
27
- * fact, never merged here.) */
28
- export const PHASE_SUFFIX_CORE = "p\\d+(?:\\.\\d+)*";
29
- /** The phase-suffix parse — the trailing `-p<major>(.<minor>)*` segment captured
30
- * as the named `suffix` group (composed from PHASE_SUFFIX_CORE: the ONE grammar). */
31
- const PHASE_SUFFIX_TAIL = new RegExp(`(?<program>.+?)(?<suffix>-${PHASE_SUFFIX_CORE})$`);
32
- /** The suffix-only match — a bare `<major>(.<minor>)*` phase path (composed from
33
- * the SAME PHASE_SUFFIX_CORE; the board's scan uses this form). */
34
- export const PHASE_SUFFIX_BARE = new RegExp(`^${PHASE_SUFFIX_CORE}$`);
35
20
  /** The persisted path-field keys — the JSON fields whose value is a PATH (the
36
21
  * progress.json `reviewedRevision.doc` / `.plan` layers · the base.json `plan`
37
22
  * field). The read-time normalization (P9 T4 §2.11) relativizes exactly these
@@ -87,64 +72,6 @@ export class Workspace {
87
72
  this.slug = slug;
88
73
  this.path = path.join(root.path, slug);
89
74
  }
90
- /** The doc-file → slug derivation: strip `.md`, then one trailing `-design` or
91
- * `-plan` suffix (anchored, mutually exclusive — spec and plan converge). */
92
- static slugFromDoc(doc) {
93
- const base = path.basename(doc).replace(/\.md$/, "");
94
- return base.replace(/-(?:design|plan)$/, "");
95
- }
96
- /** The slug's phase-suffix parse — the trailing `-p<major>(.<minor>)*` segment
97
- * (null when the slug is a program slug, i.e. carries no phase suffix). The
98
- * grammar is PHASE_SUFFIX_TAIL, composed from the shared PHASE_SUFFIX_CORE. */
99
- static phaseSuffixOf(slug) {
100
- const match = PHASE_SUFFIX_TAIL.exec(slug);
101
- return match?.groups?.suffix ?? null;
102
- }
103
- /** The slug → doc-tree reverse derivation: from a program or phase slug, derive
104
- * the artifact paths the doc tree should carry, judged by `existsSync` (the
105
- * file system is the only truth — an absent file is null, never synthesized).
106
- * A phase slug's overall anchors at the nearest existing `<ancestor>-overall.md`
107
- * walking up the dotted phase path (`-p7.1` → `-p7` → program root) — no
108
- * overall-declared table is parsed (the Phase inventory is stale-prone). */
109
- static docsOfSlug(slug, repoRoot) {
110
- const specs = path.join(repoRoot, ENGINE_RUNTIME.docRoots.specs);
111
- const plans = path.join(repoRoot, ENGINE_RUNTIME.docRoots.plans);
112
- const suffix = Workspace.phaseSuffixOf(slug);
113
- if (suffix === null) {
114
- const overall = path.join(specs, `${slug}-overall.md`);
115
- return {
116
- overall: existsSync(overall) ? overall : null,
117
- spec: null,
118
- plan: null,
119
- phaseSuffix: null,
120
- };
121
- }
122
- const overall = Workspace.#nearestOverall(specs, slug, suffix);
123
- const spec = path.join(specs, `${slug}-design.md`);
124
- const plan = path.join(plans, `${slug}.md`);
125
- return {
126
- overall,
127
- spec: existsSync(spec) ? spec : null,
128
- plan: existsSync(plan) ? plan : null,
129
- phaseSuffix: suffix,
130
- };
131
- }
132
- /** The nearest existing overall anchor walking up the dotted phase path: for a
133
- * deep suffix (`-p7.1`) the candidates are `<program>-p7`, then the program
134
- * root; for a single-segment suffix the program root only. Null when no
135
- * candidate's overall file exists — nothing synthesized. */
136
- static #nearestOverall(specs, slug, suffix) {
137
- const stem = slug.slice(0, slug.length - suffix.length);
138
- const segments = suffix.slice(2).split(".");
139
- for (let keep = segments.length - 1; keep >= 0; keep--) {
140
- const candidate = keep === 0
141
- ? path.join(specs, `${stem}-overall.md`)
142
- : path.join(specs, `${stem}-p${segments.slice(0, keep).join(".")}-overall.md`);
143
- if (existsSync(candidate))
144
- return candidate;
145
- }
146
- return null;
147
- }
148
75
  /** Idempotently create the workspace directory. */
149
76
  ensure() {
150
77
  this.root.ensure();
@@ -12,9 +12,9 @@
12
12
  // standard parser): the frontmatter-home slots render as a `---`-fenced YAML
13
13
  // record emitted by `yaml.stringify` in one call — an independent line set, never
14
14
  // hand-spun header lines and never part of the slot/probe channel. §4.2's
15
- // placeholder three-way split: the link-typed keys (`spec` · `parent-program`)
16
- // emit a `<…>` scalar on the judge's placeholder-exemption chain; the content
17
- // keys (`title` · `author` · `depends-on` · `base`) emit `:::fill <key>`; the
15
+ // placeholder three-way split: the slug-reference key (`program`) emits a `<…>`
16
+ // scalar on the judge's placeholder-exemption chain; the content keys (`title` ·
17
+ // `author` · `base` · `slug`) emit `:::fill <key>`; the
18
18
  // truth keys (`doc-type` · `version` · `date` · `status`) emit true values. The
19
19
  // optional `parent-version` key is deliberately NOT emitted — its shape is typed
20
20
  // (`v<n>.<m>`, so a fill or a link scalar would violate the domain) and absence
@@ -31,19 +31,17 @@
31
31
  // Module-level exports are types / the class — zero behavior-carrying bare
32
32
  // functions (the plan's zero-bare-function discipline).
33
33
  import { Pair, Scalar, stringify as stringifyYaml, YAMLMap } from "yaml";
34
- /** The placeholder scalars of the front-matter link keys (spec §4.2 + D3) — the
35
- * link-typed head keys (`spec` · `parent-program`) render a `<…>`-shaped value
36
- * that rides the judge's placeholder-exemption chain (a bare `^<[^>]+>$` target
37
- * the file-existence / sibling-scan / cross-doc-chain strategies all skip),
38
- * never a `:::fill` (a fill in a link slot is a guaranteed finding). The
39
- * placeholder IS the fill contract (show-don't-tell — zero prose rules): its
40
- * inner shape is a BARE relative-path exemplar (`docs/kairos/specs/…-overall.md`),
41
- * the exact form the consumer must fill — the <>-shell keeps the exemption, the
42
- * path inside both bookends the value and doubles as the shape sample (#342: a
43
- * consumer copying the exemplar fills a bare path, never a markdown link). */
34
+ /** The placeholder scalars of the front-matter slug-reference keys (spec §4.2 + D3)
35
+ * — the phase-spec `program:` head key renders a `<…>`-shaped value that rides
36
+ * the judge's placeholder-exemption chain (a bare `^<[^>]+>$` target the
37
+ * file-existence / sibling-scan / slug-reference strategies all skip), never a
38
+ * `:::fill` (a fill in a link slot is a guaranteed finding). The placeholder IS
39
+ * the fill contract (show-don't-tell — zero prose rules): its inner shape is the
40
+ * SLUG of the parent overall document, the exact form the consumer must fill
41
+ * (the value domain of `program:` is `SLUG_VALUE_PATTERN`, so a path exemplar
42
+ * would seed a violating document). */
44
43
  const FRONT_MATTER_LINKS = {
45
- spec: "<docs/kairos/specs/…-design.md>",
46
- "parent-program": "<docs/kairos/specs/…-overall.md>",
44
+ program: "<overall-slug>",
47
45
  };
48
46
  /** The generator truths of the pattern-typed body slots (spec §3.2/§4.1) —
49
47
  * hand-pinned legal literals consistent with each declared value domain (the
@@ -107,8 +105,8 @@ export class SkeletonAssembler {
107
105
  * the probe set (each composition helper probes the anchors it emits). */
108
106
  #compose(probe) {
109
107
  switch (this.#docType) {
110
- case "overall-spec":
111
- return this.#renderOverallSpec(probe);
108
+ case "overall":
109
+ return this.#renderOverall(probe);
112
110
  case "plan":
113
111
  return this.#renderPlan(probe);
114
112
  case "phase-spec":
@@ -145,15 +143,14 @@ export class SkeletonAssembler {
145
143
  // -------------------------------------------------------------------------
146
144
  // the per-doc-type compositions — the doc section sequence + its scaffolds
147
145
  // -------------------------------------------------------------------------
148
- /** The overall-spec skeleton — the front-matter head, the section sequence
149
- * (the four table sections, the charter facets, the dependency graph, the
146
+ /** The overall skeleton — the front-matter head, the section sequence
147
+ * (the three table sections, the charter facets, the dependency graph, the
150
148
  * Form-A constraints surface and the change-history table): every required
151
- * overall-spec element lands in its structural position. */
152
- #renderOverallSpec(probe) {
149
+ * overall element lands in its structural position. */
150
+ #renderOverall(probe) {
153
151
  const lines = [];
154
152
  this.#pushFrontmatter(lines);
155
153
  lines.push(...this.#section("## Document scope", [":::fill document-scope"], probe));
156
- lines.push(...this.#section("## File paths", this.#filePathsTable(probe), probe));
157
154
  lines.push(...this.#section("## Program charter", this.#programCharter(probe), probe));
158
155
  lines.push(...this.#section("## Issue inventory", this.#issueTable(probe), probe));
159
156
  lines.push(...this.#section("## Phase inventory", this.#phaseTable(probe), probe));
@@ -212,7 +209,7 @@ export class SkeletonAssembler {
212
209
  /** The single-spec skeleton — the front-matter head, the four prose sections
213
210
  * (`:::fill` slots) and the change-history table: the lightweight scaffold of
214
211
  * the free-form spec (P6 T2 · spec §2.1). No `### N.` double-layer outline and
215
- * no parent-program key — the single-spec's deliberate deviations from the
212
+ * no `program:` key — the single-spec's deliberate deviations from the
216
213
  * phase-spec form. */
217
214
  #renderSingleSpec(probe) {
218
215
  const lines = [];
@@ -247,7 +244,7 @@ export class SkeletonAssembler {
247
244
  // the link placeholders plain (the <>-bookended exemplar — exemption-shaped).
248
245
  const fields = new YAMLMap();
249
246
  // The emission list is the projection's independent front-matter set — the
250
- // required head keys plus the type's optional keys (`base` / `depends-on`);
247
+ // required head keys plus the type's optional keys (`base` / `issues`);
251
248
  // `parent-version` never appears (the projection excludes it — §4.2's
252
249
  // optional shape-typed key, whose `v<n>.<m>` domain admits no placeholder).
253
250
  for (const slot of this.#frontmatterSlots) {
@@ -315,12 +312,6 @@ export class SkeletonAssembler {
315
312
  probe.add(anchor);
316
313
  return [heading, "", ...body, ""];
317
314
  }
318
- /** The File-paths artifact table — the two-column header + the minimal one-row
319
- * scaffold (the backticked path cell keeps the `File path row` shape). */
320
- #filePathsTable(probe) {
321
- probe.add("File path row");
322
- return ["| Artifact | Path |", "| --- | --- |", "| overall-spec | `:::fill overall-path` |"];
323
- }
324
315
  /** The charter facets — the three required `###` facet headings with their
325
316
  * content bullets (the optional decision-group / endorsements leaves generate
326
317
  * no slot — the optional/conditional zero-gen contract). */