@oscaner-skills/cdd-engine 2.0.0 → 3.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.
Files changed (127) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/{src-next/bin.ts → dist/bin.js} +18 -21
  4. package/dist/contract/declare.js +998 -0
  5. package/dist/contract/doc.js +565 -0
  6. package/dist/contract/frontmatter.js +209 -0
  7. package/dist/contract/home-extractors.js +379 -0
  8. package/dist/contract/invariants.js +1030 -0
  9. package/dist/contract/judge.js +109 -0
  10. package/dist/contract/lint.js +206 -0
  11. package/dist/contract/project.js +371 -0
  12. package/dist/contract/skill-anatomy.js +156 -0
  13. package/dist/contract/translate.js +85 -0
  14. package/dist/face/artifacts.js +189 -0
  15. package/dist/face/board-view.js +522 -0
  16. package/dist/face/capsule.js +141 -0
  17. package/dist/face/cli.js +891 -0
  18. package/dist/face/declare.js +241 -0
  19. package/dist/face/gate.js +158 -0
  20. package/dist/face/graph-view.js +66 -0
  21. package/dist/face/host.js +211 -0
  22. package/dist/face/lifecycle.js +603 -0
  23. package/dist/face/preview.js +136 -0
  24. package/dist/face/projection.js +259 -0
  25. package/dist/face/route-render.js +162 -0
  26. package/dist/face/termination.js +482 -0
  27. package/dist/face/words.js +220 -0
  28. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  29. package/dist/infra/doc-roots.js +19 -0
  30. package/dist/infra/git.js +37 -0
  31. package/dist/infra/process.js +22 -0
  32. package/dist/infra/root.js +62 -0
  33. package/dist/infra/runtime.js +85 -0
  34. package/dist/infra/workspace.js +276 -0
  35. package/dist/render/brief.js +82 -0
  36. package/dist/render/issue-body.js +129 -0
  37. package/dist/render/skeleton.js +434 -0
  38. package/dist/render/templates.js +520 -0
  39. package/dist/session/faces.js +38 -0
  40. package/dist/session/graph.js +309 -0
  41. package/dist/session/handoff-schema.js +295 -0
  42. package/dist/session/ledger.js +762 -0
  43. package/dist/session/next.js +211 -0
  44. package/dist/session/preflight.js +194 -0
  45. package/dist/session/round-naming.js +73 -0
  46. package/dist/session/run.js +441 -0
  47. package/dist/session/state.js +8 -0
  48. package/dist/session/wave.js +92 -0
  49. package/package.json +8 -7
  50. package/templates/report/issue-body.json +0 -46
  51. package/src-next/__tests__/bin.test.ts +0 -128
  52. package/src-next/__tests__/smoke.integration.test.ts +0 -202
  53. package/src-next/__tests__/zero-dep.test.ts +0 -134
  54. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -238
  55. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -153
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -173
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -89
  58. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -225
  59. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -155
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -175
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -85
  62. package/src-next/contract/__tests__/declare.test.ts +0 -242
  63. package/src-next/contract/__tests__/doc.test.ts +0 -358
  64. package/src-next/contract/__tests__/judge.test.ts +0 -873
  65. package/src-next/contract/__tests__/lint.test.ts +0 -314
  66. package/src-next/contract/__tests__/project.test.ts +0 -419
  67. package/src-next/contract/__tests__/translate.test.ts +0 -96
  68. package/src-next/contract/declare.ts +0 -983
  69. package/src-next/contract/doc.ts +0 -753
  70. package/src-next/contract/invariants.ts +0 -1268
  71. package/src-next/contract/judge.ts +0 -142
  72. package/src-next/contract/lint.ts +0 -275
  73. package/src-next/contract/project.ts +0 -596
  74. package/src-next/contract/skill-anatomy.ts +0 -273
  75. package/src-next/contract/translate.ts +0 -113
  76. package/src-next/face/__tests__/board-view.test.ts +0 -948
  77. package/src-next/face/__tests__/capsule.test.ts +0 -276
  78. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -102
  79. package/src-next/face/__tests__/cli.test.ts +0 -4643
  80. package/src-next/face/__tests__/face.test.ts +0 -289
  81. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  82. package/src-next/face/__tests__/host.test.ts +0 -24
  83. package/src-next/face/__tests__/negation.ts +0 -6
  84. package/src-next/face/__tests__/projection.test.ts +0 -301
  85. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
  86. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  87. package/src-next/face/artifacts.ts +0 -195
  88. package/src-next/face/board-view.ts +0 -662
  89. package/src-next/face/capsule.ts +0 -149
  90. package/src-next/face/cli.ts +0 -819
  91. package/src-next/face/declare.ts +0 -326
  92. package/src-next/face/gate.ts +0 -170
  93. package/src-next/face/graph-view.ts +0 -74
  94. package/src-next/face/host.ts +0 -326
  95. package/src-next/face/lifecycle.ts +0 -700
  96. package/src-next/face/projection.ts +0 -282
  97. package/src-next/face/route-render.ts +0 -160
  98. package/src-next/face/words.ts +0 -296
  99. package/src-next/infra/__tests__/infra.test.ts +0 -287
  100. package/src-next/infra/git.ts +0 -39
  101. package/src-next/infra/process.ts +0 -34
  102. package/src-next/infra/runtime.ts +0 -185
  103. package/src-next/infra/workspace.ts +0 -232
  104. package/src-next/render/__tests__/render.test.ts +0 -499
  105. package/src-next/render/__tests__/skeleton.test.ts +0 -466
  106. package/src-next/render/brief.ts +0 -121
  107. package/src-next/render/issue-body.ts +0 -159
  108. package/src-next/render/skeleton.ts +0 -437
  109. package/src-next/render/templates.ts +0 -650
  110. package/src-next/session/__tests__/graph.test.ts +0 -270
  111. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  112. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  113. package/src-next/session/__tests__/ledger.test.ts +0 -744
  114. package/src-next/session/__tests__/next.test.ts +0 -368
  115. package/src-next/session/__tests__/preflight.test.ts +0 -491
  116. package/src-next/session/__tests__/run.test.ts +0 -1014
  117. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  118. package/src-next/session/__tests__/wave.test.ts +0 -469
  119. package/src-next/session/faces.ts +0 -110
  120. package/src-next/session/graph.ts +0 -411
  121. package/src-next/session/handoff-schema.ts +0 -373
  122. package/src-next/session/ledger.ts +0 -1004
  123. package/src-next/session/next.ts +0 -192
  124. package/src-next/session/preflight.ts +0 -240
  125. package/src-next/session/run.ts +0 -606
  126. package/src-next/session/state.ts +0 -30
  127. package/src-next/session/wave.ts +0 -139
@@ -0,0 +1,434 @@
1
+ // packages/cdd-engine/src-next/render/skeleton.ts
2
+ // The SkeletonAssembler — the render face of the skeleton projection (spec §3/§4.1,
3
+ // the `cdd schema get <type> --output skeleton` rendering): a DocSkeleton (contract/project.ts — the
4
+ // required-only derived face, every element classified into its
5
+ // placeholder-anchoring slot kind) is assembled into the markdown skeleton bytes
6
+ // the consumer fills. The structure is the same registry-derived surface the
7
+ // judge reads — the skeleton is green by construction, never an exemption channel
8
+ // (spec §4.1: pure content slots take `:::fill`, link-shaped anchors a placeholder
9
+ // link, structure is true value — the doc-contract pin judges the rendered bytes).
10
+ //
11
+ // The front-matter head is the ONE structured-metadata channel (spec §2.2's
12
+ // standard parser): the frontmatter-home slots render as a `---`-fenced YAML
13
+ // record emitted by `yaml.stringify` in one call — an independent line set, never
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
18
+ // truth keys (`doc-type` · `version` · `date` · `status`) emit true values. The
19
+ // optional `parent-version` key is deliberately NOT emitted — its shape is typed
20
+ // (`v<n>.<m>`, so a fill or a link scalar would violate the domain) and absence
21
+ // is legal. The markdown body stays the registry-driven scaffold. render() is a
22
+ // pure byte renderer — it never appends a trailing newline (the CLI appends the
23
+ // single `\n`, so a redirected fixture ends with exactly one newline). The
24
+ // composition is the judgment site of the projection: after assembly render()
25
+ // asserts slot consumption over the BODY slots — every registered body slot emits
26
+ // a probe and every probe names a registered body slot, so a registry/composition
27
+ // drift is a loud throw in the renderer, never a silent byte gap (the front-matter
28
+ // key set is registry-faithful by construction — the assertion domain is the body
29
+ // the composition hand-assembles).
30
+ //
31
+ // Module-level exports are types / the class — zero behavior-carrying bare
32
+ // functions (the plan's zero-bare-function discipline).
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). */
44
+ const FRONT_MATTER_LINKS = {
45
+ spec: "<docs/kairos/specs/…-design.md>",
46
+ "parent-program": "<docs/kairos/specs/…-overall.md>",
47
+ };
48
+ /** The generator truths of the pattern-typed body slots (spec §3.2/§4.1) —
49
+ * hand-pinned legal literals consistent with each declared value domain (the
50
+ * `none` issue-ref default; the `[Pending]` design cell — the only pending form
51
+ * its valuePattern admits, never bare `Pending` — and the bare `Pending` plan
52
+ * cell, a legal alternative of its domain) and the conforming graph rows (the
53
+ * `P1 -> P2` hard edge + the legend line). The head's `status` truth lives in
54
+ * the front-matter emission (`status: Draft` — the first legal literal of every
55
+ * status enum — via `#frontmatterTruth`, never a body fill). */
56
+ const TRUTH_LINES = {
57
+ "Issue ref cell": "none",
58
+ "Implementation plan cell": "Pending",
59
+ "Design spec cell": "[Pending]",
60
+ "Hard edge": "P1 -> P2",
61
+ "Graph legend": "- `->` = hard block",
62
+ };
63
+ /** The change-history table scaffold — the registered `Change history row` /
64
+ * `Version token` / `Change history date` cells composed into the shared
65
+ * header + separator + first-row shape (the version row must equal the header
66
+ * version — v0.1 — and stay version-ascending, spec §3.2). */
67
+ const HISTORY_HEADER = "| Version | date | summary | author |";
68
+ /**
69
+ * The skeleton assembler — one DocSkeleton (contract/project.ts, the required-only
70
+ * sixth projection) → the markdown skeleton bytes. Constructed on the projection
71
+ * and the run date (the CLI injects the run day; tests inject a fixed date), the
72
+ * instance is stateless after construction, so sharing one instance composes
73
+ * safely. The composition per doc type mirrors the doc's section sequence; every
74
+ * required element of the type lands in its structural position — the front-
75
+ * matter keys in the head record (the registry's frontmatter-home slot order),
76
+ * the body elements in the section scaffold (the doc-contract pin judges the
77
+ * rendered bytes — a missing required anchor is a finding).
78
+ */
79
+ export class SkeletonAssembler {
80
+ /** The doc type of the projected skeleton. */
81
+ #docType;
82
+ /** The injected run date — the front-matter `date:` truth (`YYYY-MM-DD`). */
83
+ #date;
84
+ /** The projection's slots in shape-group order (the body slot channel). */
85
+ #slots;
86
+ /** The front-matter emission list — the head's required + optional keys. */
87
+ #frontmatterSlots;
88
+ constructor(projection, date) {
89
+ this.#docType = projection.docType;
90
+ this.#date = date;
91
+ this.#slots = projection.slots;
92
+ this.#frontmatterSlots = projection.frontmatter;
93
+ }
94
+ /** Render the doc skeleton's markdown bytes — no trailing newline (the CLI owns
95
+ * the appended `\n`; the EOF-newline rule lands on the redirected fixture).
96
+ * The front-matter head is emitted as the registry's key set (never probed);
97
+ * every body anchor registers a probe; the composition completes only when
98
+ * the probes and the projection's body slots coincide (a drift is a loud
99
+ * throw below, never silent bytes). */
100
+ render() {
101
+ const probe = new Set();
102
+ const lines = this.#compose(probe);
103
+ this.#assertConsumed(probe);
104
+ return this.#join(lines);
105
+ }
106
+ /** Compose the doc-type lines, registering every emitted registered anchor in
107
+ * the probe set (each composition helper probes the anchors it emits). */
108
+ #compose(probe) {
109
+ switch (this.#docType) {
110
+ case "overall-spec":
111
+ return this.#renderOverallSpec(probe);
112
+ case "plan":
113
+ return this.#renderPlan(probe);
114
+ case "phase-spec":
115
+ return this.#renderPhaseSpec(probe);
116
+ case "single-spec":
117
+ return this.#renderSingleSpec(probe);
118
+ }
119
+ }
120
+ /** The slot-consumption invariant — the composition-side tripwire of the
121
+ * registry-derived structure (the finding hardened in: the projection is the
122
+ * single structure source, the hand-written compositions must not drift from
123
+ * it). The assertion domain is the BODY slots — the front-matter head is
124
+ * emitted from the projection's independent emission list (the §2.2
125
+ * structured channel, never probed), so the tripwire covers the
126
+ * hand-assembled body:
127
+ * every required body slot of the projection is emitted by the composition,
128
+ * and no composition probe names an anchor the registry does not require — a
129
+ * registered element with no composition position, or a composed anchor no
130
+ * longer required, is registry drift, loud never silent. */
131
+ #assertConsumed(probe) {
132
+ const registered = new Set(this.#slots.filter((slot) => slot.home !== "frontmatter").map((slot) => slot.anchor));
133
+ const unemitted = this.#slots
134
+ .filter((slot) => slot.home !== "frontmatter" && !probe.has(slot.anchor))
135
+ .map((slot) => slot.anchor);
136
+ if (unemitted.length > 0) {
137
+ throw new Error(`skeleton composition omits the registered required slot(s): ${unemitted.join(", ")}`);
138
+ }
139
+ for (const anchor of probe) {
140
+ if (!registered.has(anchor)) {
141
+ throw new Error(`skeleton composition emits the unregistered anchor: ${anchor}`);
142
+ }
143
+ }
144
+ }
145
+ // -------------------------------------------------------------------------
146
+ // the per-doc-type compositions — the doc section sequence + its scaffolds
147
+ // -------------------------------------------------------------------------
148
+ /** The overall-spec skeleton — the front-matter head, the section sequence
149
+ * (the four table sections, the charter facets, the dependency graph, the
150
+ * Form-A constraints surface and the change-history table): every required
151
+ * overall-spec element lands in its structural position. */
152
+ #renderOverallSpec(probe) {
153
+ const lines = [];
154
+ this.#pushFrontmatter(lines);
155
+ lines.push(...this.#section("## Document scope", [":::fill document-scope"], probe));
156
+ lines.push(...this.#section("## File paths", this.#filePathsTable(probe), probe));
157
+ lines.push(...this.#section("## Program charter", this.#programCharter(probe), probe));
158
+ lines.push(...this.#section("## Issue inventory", this.#issueTable(probe), probe));
159
+ lines.push(...this.#section("## Phase inventory", this.#phaseTable(probe), probe));
160
+ lines.push(...this.#section("## Dependency graph", this.#dependencyGraph(probe), probe));
161
+ lines.push(...this.#section("## Boundary rules", ["- :::fill boundary-rule"], probe));
162
+ // The overall Constraints section — the Form-A delta-only surface shared
163
+ // with the plan/phase-spec: the heading + the `Constraint delta bullet`,
164
+ // composed at the declared registry position (between Boundary rules and
165
+ // Maintenance). The section heading line and its delta bullet land in the
166
+ // SAME composition step — the three same-order parts (the declared section
167
+ // anchor, the composed heading, the composed bullet) must move together, or
168
+ // the `#assertConsumed` tripwire throws (a heading without its bullet omits
169
+ // a registered required slot).
170
+ lines.push(...this.#section("## Constraints", ["- :::fill constraint"], probe, "Constraint delta bullet"));
171
+ lines.push(...this.#section("## Maintenance", ["- :::fill maintenance-note"], probe));
172
+ lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
173
+ return lines;
174
+ }
175
+ /** The plan skeleton — the front-matter head, the constraints section, the first
176
+ * task block (`### Task 1:` with the seven required task fields) and the
177
+ * change-history table (§3.2 — one task block, more blocks appended when
178
+ * filling). */
179
+ #renderPlan(probe) {
180
+ const lines = [];
181
+ this.#pushFrontmatter(lines);
182
+ lines.push(...this.#section("## Constraints", ["- :::fill constraint"], probe, "Constraint delta bullet"));
183
+ lines.push(...this.#taskBlock(probe));
184
+ lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
185
+ return lines;
186
+ }
187
+ /** The phase-spec skeleton — the front-matter head, the Design double layer
188
+ * (one `### 1.` group + one `#### 1.1` item + the acceptance surface), the
189
+ * constraints section and the change-history table (§3.2 — more groups/items
190
+ * appended in numeric order when filling). */
191
+ #renderPhaseSpec(probe) {
192
+ const lines = [];
193
+ this.#pushFrontmatter(lines);
194
+ lines.push(...this.#section("## Design", [
195
+ // The design intro is the Design section's one prose position — a rank-3
196
+ // group heading closes the rank-2 section block, so the intro line (not a
197
+ // blank) is what keeps the section non-hollow.
198
+ ":::fill design-intro",
199
+ "",
200
+ "### 1. :::fill group-title",
201
+ "#### 1.1 :::fill item-title",
202
+ "- :::fill item-body",
203
+ "",
204
+ "### Acceptance criteria",
205
+ "",
206
+ "- `:::fill acceptance-entry`",
207
+ ], probe, "### N. group heading", "#### N.M item heading", "### Acceptance criteria", "Acceptance entry"));
208
+ lines.push(...this.#section("## Constraints", ["- :::fill constraint"], probe, "Constraint delta bullet"));
209
+ lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
210
+ return lines;
211
+ }
212
+ /** The single-spec skeleton — the front-matter head, the four prose sections
213
+ * (`:::fill` slots) and the change-history table: the lightweight scaffold of
214
+ * 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
216
+ * phase-spec form. */
217
+ #renderSingleSpec(probe) {
218
+ const lines = [];
219
+ this.#pushFrontmatter(lines);
220
+ lines.push(...this.#section("## Background & root cause", [":::fill background-root-cause"], probe));
221
+ lines.push(...this.#section("## Design decisions", [":::fill design-ruling"], probe));
222
+ lines.push(...this.#section("## Acceptance", [":::fill acceptance"], probe));
223
+ lines.push(...this.#section("## Constraints", [":::fill constraints"], probe));
224
+ lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
225
+ return lines;
226
+ }
227
+ // -------------------------------------------------------------------------
228
+ // the shared scaffolds — the front-matter head, tables, sections, the join
229
+ // -------------------------------------------------------------------------
230
+ /** The front-matter head block — the projection's front-matter emission list
231
+ * (the head's required keys plus the type's optional keys) in registry order,
232
+ * emitted by `yaml.stringify` in one call (§2.2's standard structured-metadata
233
+ * channel): §4.2's placeholder three-way split — the link keys a `<…>` scalar,
234
+ * the content keys a `:::fill <key>`, the truth keys their true values. An
235
+ * independent line set — never part of the slot/probe channel (the
236
+ * `#assertConsumed` domain is the body the composition hand-assembles). The
237
+ * head's `doc-type:` key is the canonical machine read (spec §3.1 ⑩ · D34 —
238
+ * the read faces consume the front-matter record, zero header-line marker
239
+ * grammar). */
240
+ #pushFrontmatter(lines) {
241
+ // The front-matter record is emitted by `yaml.stringify` in ONE call over the
242
+ // projection's emission list (spec §2.2's structured channel — the
243
+ // parsed-nodes form keeps the keys ordered and the emission single: D3 quotes
244
+ // the content-fill values so a consumer filling `[human] · …` / `Title: …`
245
+ // into the slot never breaks the scalar (the #341 fill class dies at the
246
+ // skeleton's default form, not at report time). The truth values stay plain,
247
+ // the link placeholders plain (the <>-bookended exemplar — exemption-shaped).
248
+ const fields = new YAMLMap();
249
+ // 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`);
251
+ // `parent-version` never appears (the projection excludes it — §4.2's
252
+ // optional shape-typed key, whose `v<n>.<m>` domain admits no placeholder).
253
+ for (const slot of this.#frontmatterSlots) {
254
+ const value = new Scalar(this.#frontmatterValue(slot));
255
+ // D3: the content fills emit single-quoted — the consumer may fill
256
+ // `[human] · …` / `Title: …` into the slot; the quote keeps the scalar
257
+ // intact regardless of the leading character (the #341 class dies at the
258
+ // skeleton's default form). The truths and the link placeholders stay
259
+ // plain.
260
+ value.type = slot.slot === "content" ? Scalar.QUOTE_SINGLE : Scalar.PLAIN;
261
+ fields.items.push(new Pair(new Scalar(slot.anchor), value));
262
+ }
263
+ const block = stringifyYaml(fields).trimEnd().split("\n");
264
+ lines.push("---", ...block, "---", "");
265
+ }
266
+ /** One front-matter value — the §4.2 placeholder three-way split over the slot
267
+ * kind: the link keys a `<…>` placeholder scalar, the content keys a content
268
+ * fill (`:::fill <key>`), the truth keys (the fixed version/date scaffold and
269
+ * the doc-type / status patterns) their true values. */
270
+ #frontmatterValue(slot) {
271
+ if (slot.slot === "link") {
272
+ const placeholder = FRONT_MATTER_LINKS[slot.anchor];
273
+ if (placeholder === undefined) {
274
+ throw new Error(`no skeleton front-matter link placeholder for the ${slot.anchor} anchor`);
275
+ }
276
+ return placeholder;
277
+ }
278
+ if (slot.slot === "content")
279
+ return `:::fill ${slot.anchor}`;
280
+ return this.#frontmatterTruth(slot);
281
+ }
282
+ /** The true front-matter value of a fixed/patterned front-matter key — the doc
283
+ * type from the projection, the injected run date, the fixed first version and
284
+ * the first legal status literal (`Draft`, the shared head of every status
285
+ * enum domain). An unknown truth key is a registry drift, loud never silent. */
286
+ #frontmatterTruth(slot) {
287
+ switch (slot.anchor) {
288
+ case "doc-type":
289
+ return this.#docType;
290
+ case "version":
291
+ return "v0.1";
292
+ case "date":
293
+ return this.#date;
294
+ case "status":
295
+ return "Draft";
296
+ }
297
+ throw new Error(`no skeleton front-matter truth for the ${slot.anchor} anchor`);
298
+ }
299
+ /** The generator truth of one pattern-typed body slot — an unknown anchor is a
300
+ * registry drift, loud never silent. */
301
+ #truth(anchor) {
302
+ const truth = TRUTH_LINES[anchor];
303
+ if (truth === undefined)
304
+ throw new Error(`no skeleton truth for the ${anchor} anchor`);
305
+ return truth;
306
+ }
307
+ /** One markdown section — the heading (probed as its registered section-heading
308
+ * anchor), a blank, the body and a trailing blank. The body anchors are the
309
+ * registered anchors the body emits beyond the heading (the table rows/cells,
310
+ * the delta bullets, the design-body headings) — every one must be a required
311
+ * slot of the doc type. */
312
+ #section(heading, body, probe, ...bodyAnchors) {
313
+ probe.add(heading);
314
+ for (const anchor of bodyAnchors)
315
+ probe.add(anchor);
316
+ return [heading, "", ...body, ""];
317
+ }
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
+ /** The charter facets — the three required `###` facet headings with their
325
+ * content bullets (the optional decision-group / endorsements leaves generate
326
+ * no slot — the optional/conditional zero-gen contract). */
327
+ #programCharter(probe) {
328
+ probe.add("### Goal");
329
+ probe.add("### Non-goals");
330
+ probe.add("### Cross-cutting");
331
+ return [
332
+ "### Goal",
333
+ "",
334
+ "- :::fill goal-description",
335
+ "",
336
+ "### Non-goals",
337
+ "",
338
+ "- :::fill non-goal-description",
339
+ "",
340
+ "### Cross-cutting",
341
+ "",
342
+ "- :::fill cross-cutting-description",
343
+ ];
344
+ }
345
+ /** The Issue-inventory table — the registered columns + the minimal row (the `P1`
346
+ * phase cell registers the inventory id, the issue-ref cell the enum's first
347
+ * legal literal (`none`), the title cell a content fill). */
348
+ #issueTable(probe) {
349
+ probe.add("Issue inventory columns");
350
+ probe.add("Issue row");
351
+ probe.add("Issue ref cell");
352
+ return [
353
+ "| Phase | Issue (ref) | Title summary |",
354
+ "| --- | --- | --- |",
355
+ `| P1 | ${this.#truth("Issue ref cell")} | :::fill issue-title |`,
356
+ ];
357
+ }
358
+ /** The Phase-inventory table — the registered columns + two rows (the `P1 -> P2`
359
+ * graph edge cross-links both ids, so both phases register; the cells carry the
360
+ * pending-form truths (`[Pending]` design — the design domain's pending form —
361
+ * and `Pending` plan, each legal in its declared domain), the phase-id cell the
362
+ * structural id). */
363
+ #phaseTable(probe) {
364
+ probe.add("Phase inventory columns");
365
+ probe.add("Phase row");
366
+ probe.add("Phase id token");
367
+ probe.add("Implementation plan cell");
368
+ probe.add("Design spec cell");
369
+ probe.add("Dependency cell");
370
+ const phaseRow = `:::fill phase-name | :::fill scope | ${this.#truth("Design spec cell")} | ${this.#truth("Implementation plan cell")} | :::fill acceptance-criteria | :::fill dependency`;
371
+ return [
372
+ "| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
373
+ "| --- | --- | --- | --- | --- | --- | --- |",
374
+ `| P1 | ${phaseRow} |`,
375
+ `| P2 | ${phaseRow} |`,
376
+ ];
377
+ }
378
+ /** The Dependency-graph block — the hard-edge truth row + the legend line. */
379
+ #dependencyGraph(probe) {
380
+ probe.add("Hard edge");
381
+ probe.add("Graph legend");
382
+ return [this.#truth("Hard edge"), this.#truth("Graph legend")];
383
+ }
384
+ /** The Change-history table — the header + separator + the first-row scaffold. */
385
+ #historyTable(probe) {
386
+ probe.add("Change history row");
387
+ probe.add("Version token");
388
+ probe.add("Change history date");
389
+ return [HISTORY_HEADER, "| --- | --- | --- | --- |", this.#historyRow()];
390
+ }
391
+ /** The change-history first row — the v0.1 version token (the header version),
392
+ * the injected run date and the summary/author content fills. */
393
+ #historyRow() {
394
+ return `| v0.1 | ${this.#date} | :::fill summary | :::fill author |`;
395
+ }
396
+ /** The first task block — the true-numbered `### Task 1:` heading (the title a
397
+ * content fill) plus the seven required task fields: the content markers with
398
+ * their values, the Steps field with the checkable step form (§3.2), and the
399
+ * `none` DependsOn default. */
400
+ #taskBlock(probe) {
401
+ probe.add("### Task N:");
402
+ probe.add("Task id token");
403
+ probe.add("**Objective**");
404
+ probe.add("**Files**");
405
+ probe.add("File path token");
406
+ probe.add("**Consumes**");
407
+ probe.add("**Produces**");
408
+ probe.add("**Steps**");
409
+ probe.add("Step action");
410
+ probe.add("Step checkable");
411
+ probe.add("**Acceptance**");
412
+ probe.add("**DependsOn**");
413
+ return [
414
+ "### Task 1: :::fill task-title",
415
+ "- **Objective**: :::fill objective",
416
+ "- **Files**: :::fill file-paths",
417
+ "- **Consumes**: :::fill consumes",
418
+ "- **Produces**: :::fill produces",
419
+ "- **Steps**:",
420
+ " - :::fill step-action — checkable: :::fill step-checkable",
421
+ "- **Acceptance**: :::fill acceptance",
422
+ "- **DependsOn**: none",
423
+ "",
424
+ ];
425
+ }
426
+ /** Join the assembled lines — the trailing blank of the last section dropped
427
+ * (render() never ends with a blank line or a newline). */
428
+ #join(lines) {
429
+ const out = [...lines];
430
+ while (out.length > 0 && out[out.length - 1] === "")
431
+ out.pop();
432
+ return out.join("\n");
433
+ }
434
+ }