@oscaner-skills/cdd-engine 3.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 (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +141 -0
  15. package/dist/face/cli.js +891 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +603 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +482 -0
  25. package/dist/face/words.js +220 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +441 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. 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
+ }