@oscaner-skills/cdd-engine 1.0.0 → 2.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 (99) hide show
  1. package/README.md +9 -8
  2. package/README.zh-CN.md +9 -8
  3. package/package.json +15 -22
  4. package/src-next/__tests__/bin.test.ts +128 -0
  5. package/src-next/__tests__/smoke.integration.test.ts +202 -0
  6. package/src-next/__tests__/zero-dep.test.ts +134 -0
  7. package/src-next/bin.ts +61 -0
  8. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +238 -0
  9. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +153 -0
  10. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +173 -0
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +89 -0
  12. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +225 -0
  13. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +155 -0
  14. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +175 -0
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +85 -0
  16. package/src-next/contract/__tests__/declare.test.ts +242 -0
  17. package/src-next/contract/__tests__/doc.test.ts +358 -0
  18. package/src-next/contract/__tests__/judge.test.ts +873 -0
  19. package/src-next/contract/__tests__/lint.test.ts +314 -0
  20. package/src-next/contract/__tests__/project.test.ts +419 -0
  21. package/src-next/contract/__tests__/translate.test.ts +96 -0
  22. package/src-next/contract/declare.ts +983 -0
  23. package/src-next/contract/doc.ts +753 -0
  24. package/src-next/contract/invariants.ts +1268 -0
  25. package/src-next/contract/judge.ts +142 -0
  26. package/src-next/contract/lint.ts +275 -0
  27. package/src-next/contract/project.ts +596 -0
  28. package/src-next/contract/skill-anatomy.ts +273 -0
  29. package/src-next/contract/translate.ts +113 -0
  30. package/src-next/face/__tests__/board-view.test.ts +948 -0
  31. package/src-next/face/__tests__/capsule.test.ts +276 -0
  32. package/src-next/face/__tests__/channel-closure.guard.test.ts +102 -0
  33. package/src-next/face/__tests__/cli.test.ts +4643 -0
  34. package/src-next/face/__tests__/face.test.ts +289 -0
  35. package/src-next/face/__tests__/graph-view.test.ts +61 -0
  36. package/src-next/face/__tests__/host.test.ts +24 -0
  37. package/src-next/face/__tests__/negation.ts +6 -0
  38. package/src-next/face/__tests__/projection.test.ts +301 -0
  39. package/src-next/face/__tests__/sync-runner.test.ts +70 -0
  40. package/src-next/face/__tests__/words.guard.test.ts +93 -0
  41. package/src-next/face/artifacts.ts +195 -0
  42. package/src-next/face/board-view.ts +662 -0
  43. package/src-next/face/capsule.ts +149 -0
  44. package/src-next/face/cli.ts +819 -0
  45. package/src-next/face/declare.ts +326 -0
  46. package/src-next/face/gate.ts +170 -0
  47. package/src-next/face/graph-view.ts +74 -0
  48. package/src-next/face/host.ts +326 -0
  49. package/src-next/face/lifecycle.ts +700 -0
  50. package/src-next/face/projection.ts +282 -0
  51. package/src-next/face/route-render.ts +160 -0
  52. package/src-next/face/words.ts +296 -0
  53. package/src-next/infra/__tests__/infra.test.ts +287 -0
  54. package/src-next/infra/config.ts +42 -0
  55. package/src-next/infra/git.ts +39 -0
  56. package/src-next/infra/process.ts +34 -0
  57. package/src-next/infra/runtime.ts +185 -0
  58. package/src-next/infra/workspace.ts +232 -0
  59. package/src-next/render/__tests__/render.test.ts +499 -0
  60. package/src-next/render/__tests__/skeleton.test.ts +466 -0
  61. package/src-next/render/brief.ts +121 -0
  62. package/src-next/render/issue-body.ts +159 -0
  63. package/src-next/render/skeleton.ts +437 -0
  64. package/src-next/render/templates.ts +650 -0
  65. package/src-next/session/__tests__/graph.test.ts +270 -0
  66. package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
  67. package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
  68. package/src-next/session/__tests__/ledger.test.ts +744 -0
  69. package/src-next/session/__tests__/next.test.ts +368 -0
  70. package/src-next/session/__tests__/preflight.test.ts +491 -0
  71. package/src-next/session/__tests__/run.test.ts +1014 -0
  72. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
  73. package/src-next/session/__tests__/wave.test.ts +469 -0
  74. package/src-next/session/faces.ts +110 -0
  75. package/src-next/session/graph.ts +411 -0
  76. package/src-next/session/handoff-schema.ts +373 -0
  77. package/src-next/session/ledger.ts +1004 -0
  78. package/src-next/session/next.ts +192 -0
  79. package/src-next/session/preflight.ts +240 -0
  80. package/src-next/session/run.ts +606 -0
  81. package/src-next/session/state.ts +30 -0
  82. package/src-next/session/wave.ts +139 -0
  83. package/templates/report/issue-body.json +18 -20
  84. package/dist/chunks/branch.mjs +0 -480
  85. package/dist/chunks/docs.mjs +0 -253
  86. package/dist/chunks/task.mjs +0 -913
  87. package/dist/cli.mjs +0 -5457
  88. package/dist/documents/schema/add-phase-protocol.json +0 -126
  89. package/dist/documents/schema/overall.json +0 -361
  90. package/dist/documents/schema/phase-spec.json +0 -145
  91. package/dist/documents/schema/plan.json +0 -191
  92. package/dist/documents/schema/skill-anatomy.json +0 -233
  93. package/dist/resources/harness-registry.json +0 -49
  94. package/dist/shared/cdd-engine.liioziig.mjs +0 -184
  95. package/templates/engine-config.json +0 -302
  96. package/templates/schema/cache-profile-schema.json +0 -23
  97. package/templates/schema/docs-handoff-schema.json +0 -129
  98. package/templates/schema/task-handoff-schema.json +0 -332
  99. package/templates/template-contract.json +0 -231
@@ -0,0 +1,159 @@
1
+ // packages/cdd-engine/src-next/render/issue-body.ts
2
+ // T19 — IssueBodyRenderer (the P7 translation-system render landing): the aggregate
3
+ // issue body's steady renderer, relocated from face/cli.ts (T11's composition root
4
+ // only assembles it — the renderer owns no CLI). The language/label plane is
5
+ // data-driven:
6
+ //
7
+ // · the finding-type vocabulary is the renderer's declared steady set (bug /
8
+ // enhancement / chore — the input contract's type domain);
9
+ // · the language vocabulary is the word table's locale key projection (the langs
10
+ // derivation — localeKeys(), never a hardcoded list);
11
+ // · every label the body emits rides the word table's locale rows through the
12
+ // Translator (the bidirectional layer — localize(canonical, locale) renders the
13
+ // locale-normalized output). The capsule machine face (status · next: ·
14
+ // CDD_BLOCKED:) is deliberately NOT in the locale rows — English-constant, never
15
+ // localized.
16
+ //
17
+ // Module-level exports are types / the class — zero behavior-carrying bare functions.
18
+
19
+ import type { Translator, WordLocaleFace } from "../contract/translate.ts";
20
+
21
+ /** One finding row of the issue-report input. */
22
+ export interface ReportFindingInput {
23
+ type: string;
24
+ lang: string;
25
+ context: string;
26
+ problem: string;
27
+ impact: string;
28
+ suggestedFix: string;
29
+ meta: { skill: string; step: string };
30
+ }
31
+
32
+ /** The issue-report input contract — the stdin findings plane. */
33
+ export interface IssueReportInput {
34
+ harness: string;
35
+ findings: readonly ReportFindingInput[];
36
+ related?: {
37
+ open?: readonly { issue: number; component: string; reason: string }[];
38
+ closed?: readonly { issue: number }[];
39
+ program?: { issue: number };
40
+ };
41
+ }
42
+
43
+ /**
44
+ * The issue-body renderer — the aggregate issue body's steady renderer (the finding
45
+ * type/lang vocabularies and the segment labels live on the declared data — the type
46
+ * set on the renderer, the locale keys + label rows on the word table, never a second
47
+ * source): Session block → per-finding four-segment blocks with attribution → Dedup
48
+ * (open hits) → Related (closed hits + program). Pure deterministic text.
49
+ */
50
+ export class IssueBodyRenderer {
51
+ /** The finding-type vocabulary (the canonical type set). */
52
+ readonly types: readonly string[] = ["bug", "enhancement", "chore"];
53
+ /** The four text-segment keys, in the render order. */
54
+ readonly #segments: readonly string[] = ["context", "problem", "impact", "suggestedFix"];
55
+ /** The word table's locale face — the langs projection + the label rows. */
56
+ readonly #words: WordLocaleFace;
57
+ /** The translation layer — the label rows localize through it (locale-normalized render). */
58
+ readonly #translator: Translator;
59
+
60
+ constructor(words: WordLocaleFace, translator: Translator) {
61
+ this.#words = words;
62
+ this.#translator = translator;
63
+ }
64
+
65
+ /** The rendered language vocabulary — the word table's locale key projection (the
66
+ * langs derivation: a locale-key change in the word table re-projects this face). */
67
+ langs(): readonly string[] {
68
+ return this.#words.localeKeys();
69
+ }
70
+
71
+ /** The canonical `meta` bullet lines of one finding (the two attribution rows). */
72
+ #metaOf(meta: { skill: string; step: string }): string {
73
+ return `- Skill: ${meta.skill}\n- Step: ${meta.step}`;
74
+ }
75
+
76
+ /** One finding's segment label — the word table's label row localized to the
77
+ * finding's lang (localize(canonical, locale); an unknown row — impossible under
78
+ * the completeness pin — falls back to the canonical English face). */
79
+ #labelOf(finding: ReportFindingInput, segment: string): string {
80
+ const row = this.#words.localeRow(`${finding.type}.${segment}`);
81
+ if (row === null) return segment;
82
+ return this.#translator.localize(row.en, finding.lang) ?? row.en;
83
+ }
84
+
85
+ /** One finding's block — the four labeled segments plus the attribution. */
86
+ #findingOf(finding: ReportFindingInput): string {
87
+ const parts = this.#segments.map(
88
+ (segment) =>
89
+ `${this.#labelOf(finding, segment)}\n\n${String(finding[segment as keyof ReportFindingInput])}`,
90
+ );
91
+ return [...parts, this.#metaOf(finding.meta)].join("\n\n");
92
+ }
93
+
94
+ /** Render the aggregate issue body — deterministic: the Session block (harness
95
+ * line), the findings in input order, then the Dedup / Related tails. */
96
+ renderBody(input: IssueReportInput): string {
97
+ const parts: string[] = [`# CDD aggregate issue\n\n- Harness: ${input.harness}`];
98
+ for (const finding of input.findings) parts.push(this.#findingOf(finding));
99
+ const open = input.related?.open ?? [];
100
+ if (open.length > 0) {
101
+ parts.push(
102
+ `## Dedup\n${open.map((hit) => `- Dedup → #${hit.issue} (open):${hit.component} · ${hit.reason}`).join("\n")}`,
103
+ );
104
+ }
105
+ const closed = input.related?.closed ?? [];
106
+ const program = input.related?.program;
107
+ if (closed.length > 0 || program !== undefined) {
108
+ const lines: string[] = [];
109
+ for (const hit of closed) lines.push(`- Regression / follow-up of #${hit.issue} (closed)`);
110
+ if (program !== undefined) lines.push(`- Program: #${program.issue}`);
111
+ parts.push(`## Related\n${lines.join("\n")}`);
112
+ }
113
+ return parts.join("\n\n");
114
+ }
115
+
116
+ /** Input-shape validation — the E-3 early-report contract (field paths, empty =
117
+ * pass). The canonical type set and the word-table locale projection are the single
118
+ * declared vocabularies. */
119
+ validateInput(raw: unknown): string[] {
120
+ const errors: string[] = [];
121
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw))
122
+ return ["input: expected an object with harness / findings / related?"];
123
+ const input = raw as { harness?: unknown; findings?: unknown; related?: unknown };
124
+ if (typeof input.harness !== "string" || input.harness.length === 0)
125
+ errors.push("harness: non-empty string required");
126
+ if (!Array.isArray(input.findings) || input.findings.length === 0) {
127
+ errors.push("findings: non-empty array of findings required");
128
+ } else {
129
+ input.findings.forEach((rawFinding, i) => {
130
+ const finding = rawFinding as Record<string, unknown> | null;
131
+ const base = `findings[${i}]`;
132
+ if (typeof finding !== "object" || finding === null) {
133
+ errors.push(
134
+ `${base}: object with type/lang/context/problem/impact/suggestedFix/meta expected`,
135
+ );
136
+ return;
137
+ }
138
+ if (!this.types.includes(String(finding.type)))
139
+ errors.push(`${base}.type: must be one of ${this.types.join(" | ")}`);
140
+ if (!this.langs().includes(String(finding.lang)))
141
+ errors.push(`${base}.lang: must be one of ${this.langs().join(" | ")}`);
142
+ for (const field of this.#segments) {
143
+ if (typeof finding[field] !== "string" || (finding[field] as string).length === 0)
144
+ errors.push(`${base}.${field}: non-empty string required`);
145
+ }
146
+ const meta = finding.meta as Record<string, unknown> | null | undefined;
147
+ if (typeof meta !== "object" || meta === null || Array.isArray(meta)) {
148
+ errors.push(`${base}.meta: object with skill / step required`);
149
+ } else {
150
+ if (typeof meta.skill !== "string" || meta.skill.length === 0)
151
+ errors.push(`${base}.meta.skill: non-empty string required`);
152
+ if (typeof meta.step !== "string" || meta.step.length === 0)
153
+ errors.push(`${base}.meta.step: non-empty string required`);
154
+ }
155
+ });
156
+ }
157
+ return errors;
158
+ }
159
+ }
@@ -0,0 +1,437 @@
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 per-anchor forms (header lines · link placeholders · generator truths ·
12
+ // table scaffolds) are declared constant data below; the document composition
13
+ // walks them in document order. render() is a pure byte renderer — it never
14
+ // appends a trailing newline (the CLI appends the single `\n`, so a redirected
15
+ // fixture ends with exactly one newline). The composition is the judgment site
16
+ // of the projection: after assembly render() asserts slot consumption — every
17
+ // registered required slot emits a probe and every probe names a registered
18
+ // slot, so a registry/composition drift is a loud throw in the renderer, never a
19
+ // silent byte gap (the doc-contract pin judges the rendered bytes; this asserts
20
+ // the same coverage in-process, before any bytes are produced).
21
+ //
22
+ // Module-level exports are types / the class — zero behavior-carrying bare
23
+ // functions (the plan's zero-bare-function discipline).
24
+
25
+ import type { DocSkeleton, SkeletonSlot } from "../contract/project.ts";
26
+
27
+ /** The per-anchor header line forms — every registered header anchor of the four
28
+ * doc types except the link-typed anchors (their placeholder-link lines assemble
29
+ * from LINK_SLOTS): the title fill, the content marker fills, the generator-truth
30
+ * status line and the scaffold version row. The `{date}` slot carries the
31
+ * injected run date (the version-row date truth). */
32
+ const HEADER_FORMS: Record<string, string> = {
33
+ "# Title": "# :::fill title",
34
+ "**Version**": "- **Version**: v0.1 · {date}",
35
+ "**Author**": "- **Author**: :::fill author",
36
+ "**Constraints**": "- **Constraints**: :::fill constraints",
37
+ "**Depends on**": "- **Depends on**: :::fill depends-on",
38
+ };
39
+
40
+ /** The placeholder-link literals of the link-typed anchor slots (spec §4.1) — the
41
+ * `<…>` label/target pairs of the parent-program / spec links. The `<…>`-shaped
42
+ * target rides the judge's placeholder-exemption chain (file-existence /
43
+ * sibling-scan); the plan's Class-A `**Spec:**` takes label == target so the
44
+ * `label == basename` chain check holds. */
45
+ const LINK_SLOTS: Record<string, { label: string; target: string }> = {
46
+ "**Parent program**": { label: "<parent overall>", target: "<parent path>" },
47
+ "**Spec:**": { label: "<spec path>", target: "<spec path>" },
48
+ };
49
+
50
+ /** The generator truths of the pattern-typed slots (spec §3.2/§4.1) — hand-pinned
51
+ * legal literals consistent with each declared value domain (`**Status**` →
52
+ * Draft, the first legal literal of its enum; the `none` issue-ref default; the
53
+ * `[Pending]` design cell — the only pending form its valuePattern admits, never
54
+ * bare `Pending` — and the bare `Pending` plan cell, a legal alternative of its
55
+ * domain) and the conforming graph rows (the `P1 -> P2` hard edge + the legend
56
+ * line). These are derived true values, guarded by the doc-contract pins that
57
+ * judge the rendered bytes — never fill positions. */
58
+ const TRUTH_LINES: Record<string, string> = {
59
+ "**Status**": "Draft",
60
+ "Issue ref cell": "none",
61
+ "Implementation plan cell": "Pending",
62
+ "Design spec cell": "[Pending]",
63
+ "Hard edge": "P1 -> P2",
64
+ "Graph legend": "- `->` = hard block",
65
+ };
66
+
67
+ /** The change-history table scaffold — the registered `Change history row` /
68
+ * `Version token` / `Change history date` cells composed into the shared
69
+ * header + separator + first-row shape (the version row must equal the header
70
+ * version — v0.1 — and stay version-ascending, spec §3.2). */
71
+ const HISTORY_HEADER = "| Version | date | summary | author |";
72
+
73
+ /**
74
+ * The skeleton assembler — one DocSkeleton (contract/project.ts, the required-only
75
+ * sixth projection) → the markdown skeleton bytes. Constructed on the projection
76
+ * and the run date (the CLI injects the run day; tests inject a fixed date), the
77
+ * instance is stateless after construction, so sharing one instance composes
78
+ * safely. The composition per doc type mirrors the doc's section sequence; every
79
+ * required element of the type lands in its structural position (the doc-contract
80
+ * pin judges the rendered bytes — a missing required anchor is a finding).
81
+ */
82
+ export class SkeletonAssembler {
83
+ /** The doc type of the projected skeleton. */
84
+ readonly #docType: DocSkeleton["docType"];
85
+ /** The injected run date — the version-row date truth (`YYYY-MM-DD`). */
86
+ readonly #date: string;
87
+ /** The projection's slots in shape-group order. */
88
+ readonly #slots: readonly SkeletonSlot[];
89
+
90
+ constructor(projection: DocSkeleton, date: string) {
91
+ this.#docType = projection.docType;
92
+ this.#date = date;
93
+ this.#slots = projection.slots;
94
+ }
95
+
96
+ /** Render the doc skeleton's markdown bytes — no trailing newline (the CLI owns
97
+ * the appended `\n`; the EOF-newline rule lands on the redirected fixture).
98
+ * Every composed anchor registers a probe; the composition completes only when
99
+ * the probes and the projection's required slots coincide (a drift is a loud
100
+ * throw below, never silent bytes). */
101
+ render(): string {
102
+ const probe = new Set<string>();
103
+ const lines: string[] = this.#compose(probe);
104
+ this.#assertConsumed(probe);
105
+ return this.#join(lines);
106
+ }
107
+
108
+ /** Compose the doc-type lines, registering every emitted registered anchor in
109
+ * the probe set (each composition helper probes the anchors it emits). */
110
+ #compose(probe: Set<string>): string[] {
111
+ switch (this.#docType) {
112
+ case "overall-spec":
113
+ return this.#renderOverallSpec(probe);
114
+ case "plan":
115
+ return this.#renderPlan(probe);
116
+ case "phase-spec":
117
+ return this.#renderPhaseSpec(probe);
118
+ case "single-spec":
119
+ return this.#renderSingleSpec(probe);
120
+ }
121
+ }
122
+
123
+ /** The slot-consumption invariant — the composition-side tripwire of the
124
+ * registry-derived structure (the finding hardened in: the projection is the
125
+ * single structure source, the hand-written compositions must not drift from
126
+ * it): every required slot of the projection is emitted by the composition,
127
+ * and no composition probe names an anchor the registry does not require — a
128
+ * registered element with no composition position, or a composed anchor no
129
+ * longer required, is registry drift, loud never silent. */
130
+ #assertConsumed(probe: ReadonlySet<string>): void {
131
+ const registered = new Set(this.#slots.map((slot) => slot.anchor));
132
+ const unemitted = this.#slots
133
+ .filter((slot) => !probe.has(slot.anchor))
134
+ .map((slot) => slot.anchor);
135
+ if (unemitted.length > 0) {
136
+ throw new Error(
137
+ `skeleton composition omits the registered required slot(s): ${unemitted.join(", ")}`,
138
+ );
139
+ }
140
+ for (const anchor of probe) {
141
+ if (!registered.has(anchor)) {
142
+ throw new Error(`skeleton composition emits the unregistered anchor: ${anchor}`);
143
+ }
144
+ }
145
+ }
146
+
147
+ // -------------------------------------------------------------------------
148
+ // the per-doc-type compositions — the doc section sequence + its scaffolds
149
+ // -------------------------------------------------------------------------
150
+
151
+ /** The overall-spec skeleton — the header tuple, the section sequence (the four table
152
+ * sections, the charter facets and the dependency graph) and the change-history
153
+ * table: every required overall-spec element lands in its structural position. */
154
+ #renderOverallSpec(probe: Set<string>): string[] {
155
+ const lines: string[] = [];
156
+ this.#pushHeader(lines, probe);
157
+ lines.push(...this.#section("## Document scope", [":::fill document-scope"], probe));
158
+ lines.push(...this.#section("## File paths", this.#filePathsTable(probe), probe));
159
+ lines.push(...this.#section("## Program charter", this.#programCharter(probe), probe));
160
+ lines.push(...this.#section("## Issue inventory", this.#issueTable(probe), probe));
161
+ lines.push(...this.#section("## Phase inventory", this.#phaseTable(probe), probe));
162
+ lines.push(...this.#section("## Dependency graph", this.#dependencyGraph(probe), probe));
163
+ lines.push(...this.#section("## Boundary rules", ["- :::fill boundary-rule"], probe));
164
+ lines.push(...this.#section("## Maintenance", ["- :::fill maintenance-note"], probe));
165
+ lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
166
+ return lines;
167
+ }
168
+
169
+ /** The plan skeleton — the header tuple, the constraints section, the first task
170
+ * block (`### Task 1:` with the seven required task fields) and the
171
+ * change-history table (§3.2 — one task block, more blocks appended when
172
+ * filling). */
173
+ #renderPlan(probe: Set<string>): string[] {
174
+ const lines: string[] = [];
175
+ this.#pushHeader(lines, probe);
176
+ lines.push(
177
+ ...this.#section(
178
+ "## Constraints",
179
+ ["- :::fill constraint"],
180
+ probe,
181
+ "Constraint delta bullet",
182
+ ),
183
+ );
184
+ lines.push(...this.#taskBlock(probe));
185
+ lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
186
+ return lines;
187
+ }
188
+
189
+ /** The phase-spec skeleton — the header five-tuple, the Design double layer
190
+ * (one `### 1.` group + one `#### 1.1` item + the acceptance surface), the
191
+ * constraints section and the change-history table (§3.2 — more groups/items
192
+ * appended in numeric order when filling). */
193
+ #renderPhaseSpec(probe: Set<string>): string[] {
194
+ const lines: string[] = [];
195
+ this.#pushHeader(lines, probe);
196
+ lines.push(
197
+ ...this.#section(
198
+ "## Design",
199
+ [
200
+ // The design intro is the Design section's one prose position — a rank-3
201
+ // group heading closes the rank-2 section block, so the intro line (not a
202
+ // blank) is what keeps the section non-hollow.
203
+ ":::fill design-intro",
204
+ "",
205
+ "### 1. :::fill group-title",
206
+ "#### 1.1 :::fill item-title",
207
+ "- :::fill item-body",
208
+ "",
209
+ "### Acceptance criteria",
210
+ "",
211
+ "- `:::fill acceptance-entry`",
212
+ ],
213
+ probe,
214
+ "### N. group heading",
215
+ "#### N.M item heading",
216
+ "### Acceptance criteria",
217
+ "Acceptance entry",
218
+ ),
219
+ );
220
+ lines.push(
221
+ ...this.#section(
222
+ "## Constraints",
223
+ ["- :::fill constraint"],
224
+ probe,
225
+ "Constraint delta bullet",
226
+ ),
227
+ );
228
+ lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
229
+ return lines;
230
+ }
231
+
232
+ /** The single-spec skeleton — the header five-tuple, the four prose sections
233
+ * (`:::fill` slots) and the change-history table: the lightweight scaffold of
234
+ * the free-form spec (P6 T2 · spec §2.1). No `### N.` double-layer outline and
235
+ * no `**Parent program**` — the single-spec's deliberate deviations from the
236
+ * phase-spec form. */
237
+ #renderSingleSpec(probe: Set<string>): string[] {
238
+ const lines: string[] = [];
239
+ this.#pushHeader(lines, probe);
240
+ lines.push(
241
+ ...this.#section("## Background & root cause", [":::fill background-root-cause"], probe),
242
+ );
243
+ lines.push(...this.#section("## Design decisions", [":::fill design-ruling"], probe));
244
+ lines.push(...this.#section("## Acceptance", [":::fill acceptance"], probe));
245
+ lines.push(...this.#section("## Constraints", [":::fill constraints"], probe));
246
+ lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
247
+ return lines;
248
+ }
249
+
250
+ // -------------------------------------------------------------------------
251
+ // the shared scaffolds — header, tables, sections, the join
252
+ // -------------------------------------------------------------------------
253
+
254
+ /** The header block — the header-home slots in projection order (the registry
255
+ * order — the title, then the version/status truths, the content markers, the
256
+ * link placeholders), each probed, followed by the blank separator. */
257
+ #pushHeader(lines: string[], probe: Set<string>): void {
258
+ for (const slot of this.#slots) {
259
+ if (slot.home !== "header") continue;
260
+ lines.push(this.#headerLine(slot));
261
+ probe.add(slot.anchor);
262
+ }
263
+ lines.push("");
264
+ }
265
+
266
+ /** One header line — the anchor's declared form with the injected date (the
267
+ * link-typed anchors assemble their placeholder-link line from the LINK_SLOTS
268
+ * label/target pair; the header anchors are a closed set over the four
269
+ * registries — an unknown header anchor is a registry drift, loud never
270
+ * silent). */
271
+ #headerLine(slot: SkeletonSlot): string {
272
+ if (slot.slot === "link") {
273
+ const pair = LINK_SLOTS[slot.anchor];
274
+ if (pair === undefined) {
275
+ throw new Error(`no skeleton link slot for the ${slot.anchor} anchor`);
276
+ }
277
+ const marker = slot.anchor === "**Spec:**" ? "**Spec:**" : `- ${slot.anchor}:`;
278
+ return `${marker} [${pair.label}](${pair.target})`;
279
+ }
280
+ if (slot.anchor === "**Status**") {
281
+ return `- **Status**: ${this.#truth("**Status**")}`;
282
+ }
283
+ const form = HEADER_FORMS[slot.anchor];
284
+ if (form === undefined) {
285
+ throw new Error(`no skeleton header form for the ${slot.anchor} anchor`);
286
+ }
287
+ return form.replace("{date}", this.#date);
288
+ }
289
+
290
+ /** The generator truth of one pattern-typed slot — an unknown anchor is a
291
+ * registry drift, loud never silent. */
292
+ #truth(anchor: string): string {
293
+ const truth = TRUTH_LINES[anchor];
294
+ if (truth === undefined) throw new Error(`no skeleton truth for the ${anchor} anchor`);
295
+ return truth;
296
+ }
297
+
298
+ /** One markdown section — the heading (probed as its registered section-heading
299
+ * anchor), a blank, the body and a trailing blank. The body anchors are the
300
+ * registered anchors the body emits beyond the heading (the table rows/cells,
301
+ * the delta bullets, the design-body headings) — every one must be a required
302
+ * slot of the doc type. */
303
+ #section(
304
+ heading: string,
305
+ body: readonly string[],
306
+ probe: Set<string>,
307
+ ...bodyAnchors: string[]
308
+ ): string[] {
309
+ probe.add(heading);
310
+ for (const anchor of bodyAnchors) probe.add(anchor);
311
+ return [heading, "", ...body, ""];
312
+ }
313
+
314
+ /** The File-paths artifact table — the two-column header + the minimal one-row
315
+ * scaffold (the backticked path cell keeps the `File path row` shape). */
316
+ #filePathsTable(probe: Set<string>): string[] {
317
+ probe.add("File path row");
318
+ return ["| Artifact | Path |", "| --- | --- |", "| overall-spec | `:::fill overall-path` |"];
319
+ }
320
+
321
+ /** The charter facets — the three required `###` facet headings with their
322
+ * content bullets (the optional decision-group / endorsements leaves generate
323
+ * no slot — the optional/conditional zero-gen contract). */
324
+ #programCharter(probe: Set<string>): string[] {
325
+ probe.add("### Goal");
326
+ probe.add("### Non-goals");
327
+ probe.add("### Cross-cutting");
328
+ return [
329
+ "### Goal",
330
+ "",
331
+ "- :::fill goal-description",
332
+ "",
333
+ "### Non-goals",
334
+ "",
335
+ "- :::fill non-goal-description",
336
+ "",
337
+ "### Cross-cutting",
338
+ "",
339
+ "- :::fill cross-cutting-description",
340
+ ];
341
+ }
342
+
343
+ /** The Issue-inventory table — the registered columns + the minimal row (the `P1`
344
+ * phase cell registers the inventory id, the issue-ref cell the enum's first
345
+ * legal literal (`none`), the title cell a content fill). */
346
+ #issueTable(probe: Set<string>): string[] {
347
+ probe.add("Issue inventory columns");
348
+ probe.add("Issue row");
349
+ probe.add("Issue ref cell");
350
+ return [
351
+ "| Phase | Issue (ref) | Title summary |",
352
+ "| --- | --- | --- |",
353
+ `| P1 | ${this.#truth("Issue ref cell")} | :::fill issue-title |`,
354
+ ];
355
+ }
356
+
357
+ /** The Phase-inventory table — the registered columns + two rows (the `P1 -> P2`
358
+ * graph edge cross-links both ids, so both phases register; the cells carry the
359
+ * pending-form truths (`[Pending]` design — the design domain's pending form —
360
+ * and `Pending` plan, each legal in its declared domain), the phase-id cell the
361
+ * structural id). */
362
+ #phaseTable(probe: Set<string>): string[] {
363
+ probe.add("Phase inventory columns");
364
+ probe.add("Phase row");
365
+ probe.add("Phase id token");
366
+ probe.add("Implementation plan cell");
367
+ probe.add("Design spec cell");
368
+ probe.add("Dependency cell");
369
+ const phaseRow = `:::fill phase-name | :::fill scope | ${this.#truth("Design spec cell")} | ${this.#truth("Implementation plan cell")} | :::fill acceptance-criteria | :::fill dependency`;
370
+ return [
371
+ "| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
372
+ "| --- | --- | --- | --- | --- | --- | --- |",
373
+ `| P1 | ${phaseRow} |`,
374
+ `| P2 | ${phaseRow} |`,
375
+ ];
376
+ }
377
+
378
+ /** The Dependency-graph block — the hard-edge truth row + the legend line. */
379
+ #dependencyGraph(probe: Set<string>): string[] {
380
+ probe.add("Hard edge");
381
+ probe.add("Graph legend");
382
+ return [this.#truth("Hard edge"), this.#truth("Graph legend")];
383
+ }
384
+
385
+ /** The Change-history table — the header + separator + the first-row scaffold. */
386
+ #historyTable(probe: Set<string>): string[] {
387
+ probe.add("Change history row");
388
+ probe.add("Version token");
389
+ probe.add("Change history date");
390
+ return [HISTORY_HEADER, "| --- | --- | --- | --- |", this.#historyRow()];
391
+ }
392
+
393
+ /** The change-history first row — the v0.1 version token (the header version),
394
+ * the injected run date and the summary/author content fills. */
395
+ #historyRow(): string {
396
+ return `| v0.1 | ${this.#date} | :::fill summary | :::fill author |`;
397
+ }
398
+
399
+ /** The first task block — the true-numbered `### Task 1:` heading (the title a
400
+ * content fill) plus the seven required task fields: the content markers with
401
+ * their values, the Steps field with the checkable step form (§3.2), and the
402
+ * `none` DependsOn default. */
403
+ #taskBlock(probe: Set<string>): string[] {
404
+ probe.add("### Task N:");
405
+ probe.add("Task id token");
406
+ probe.add("**Objective**");
407
+ probe.add("**Files**");
408
+ probe.add("File path token");
409
+ probe.add("**Consumes**");
410
+ probe.add("**Produces**");
411
+ probe.add("**Steps**");
412
+ probe.add("Step action");
413
+ probe.add("Step checkable");
414
+ probe.add("**Acceptance**");
415
+ probe.add("**DependsOn**");
416
+ return [
417
+ "### Task 1: :::fill task-title",
418
+ "- **Objective**: :::fill objective",
419
+ "- **Files**: :::fill file-paths",
420
+ "- **Consumes**: :::fill consumes",
421
+ "- **Produces**: :::fill produces",
422
+ "- **Steps**:",
423
+ " - :::fill step-action — checkable: :::fill step-checkable",
424
+ "- **Acceptance**: :::fill acceptance",
425
+ "- **DependsOn**: none",
426
+ "",
427
+ ];
428
+ }
429
+
430
+ /** Join the assembled lines — the trailing blank of the last section dropped
431
+ * (render() never ends with a blank line or a newline). */
432
+ #join(lines: readonly string[]): string {
433
+ const out = [...lines];
434
+ while (out.length > 0 && out[out.length - 1] === "") out.pop();
435
+ return out.join("\n");
436
+ }
437
+ }