@oscaner-skills/cdd-engine 1.0.0 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +11 -10
- package/README.zh-CN.md +11 -10
- package/package.json +16 -22
- package/src-next/__tests__/bin.test.ts +128 -0
- package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
- package/src-next/__tests__/floor.guard.test.ts +69 -0
- package/src-next/__tests__/issue-body.guard.test.ts +66 -0
- package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
- package/src-next/__tests__/smoke.integration.test.ts +185 -0
- package/src-next/__tests__/support/strip-comments.ts +99 -0
- package/src-next/__tests__/zero-dep.test.ts +94 -0
- package/src-next/bin.ts +61 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +256 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +165 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +190 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +106 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +240 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +165 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +190 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +100 -0
- package/src-next/contract/__tests__/declare.test.ts +481 -0
- package/src-next/contract/__tests__/doc.test.ts +527 -0
- package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
- package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
- package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
- package/src-next/contract/__tests__/judge.test.ts +1111 -0
- package/src-next/contract/__tests__/lint.test.ts +324 -0
- package/src-next/contract/__tests__/project.test.ts +460 -0
- package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
- package/src-next/contract/__tests__/translate.test.ts +96 -0
- package/src-next/contract/declare.ts +1071 -0
- package/src-next/contract/doc.ts +816 -0
- package/src-next/contract/frontmatter.ts +233 -0
- package/src-next/contract/home-extractors.ts +397 -0
- package/src-next/contract/invariants.ts +1413 -0
- package/src-next/contract/judge.ts +151 -0
- package/src-next/contract/lint.ts +239 -0
- package/src-next/contract/project.ts +656 -0
- package/src-next/contract/skill-anatomy.ts +301 -0
- package/src-next/contract/translate.ts +113 -0
- package/src-next/face/__tests__/board-view.test.ts +1151 -0
- package/src-next/face/__tests__/capsule.test.ts +300 -0
- package/src-next/face/__tests__/channel-closure.guard.test.ts +129 -0
- package/src-next/face/__tests__/cli.test.ts +4897 -0
- package/src-next/face/__tests__/face.test.ts +289 -0
- package/src-next/face/__tests__/graph-view.test.ts +61 -0
- package/src-next/face/__tests__/host.test.ts +24 -0
- package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
- package/src-next/face/__tests__/negation.ts +6 -0
- package/src-next/face/__tests__/preview.test.ts +374 -0
- package/src-next/face/__tests__/projection.test.ts +303 -0
- package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
- package/src-next/face/__tests__/termination.test.ts +650 -0
- package/src-next/face/__tests__/words.guard.test.ts +93 -0
- package/src-next/face/artifacts.ts +248 -0
- package/src-next/face/board-view.ts +652 -0
- package/src-next/face/capsule.ts +163 -0
- package/src-next/face/cli.ts +1028 -0
- package/src-next/face/declare.ts +323 -0
- package/src-next/face/gate.ts +171 -0
- package/src-next/face/graph-view.ts +74 -0
- package/src-next/face/host.ts +302 -0
- package/src-next/face/lifecycle.ts +725 -0
- package/src-next/face/preview.ts +151 -0
- package/src-next/face/projection.ts +285 -0
- package/src-next/face/route-render.ts +185 -0
- package/src-next/face/termination.ts +573 -0
- package/src-next/face/words.ts +314 -0
- package/src-next/infra/__tests__/infra.test.ts +333 -0
- package/src-next/infra/__tests__/root.test.ts +56 -0
- package/src-next/infra/config.ts +42 -0
- package/src-next/infra/doc-roots.ts +29 -0
- package/src-next/infra/git.ts +39 -0
- package/src-next/infra/process.ts +34 -0
- package/src-next/infra/root.ts +73 -0
- package/src-next/infra/runtime.ts +132 -0
- package/src-next/infra/workspace.ts +322 -0
- package/src-next/render/__tests__/render.test.ts +550 -0
- package/src-next/render/__tests__/skeleton.test.ts +684 -0
- package/src-next/render/brief.ts +121 -0
- package/src-next/render/issue-body.ts +162 -0
- package/src-next/render/skeleton.ts +502 -0
- package/src-next/render/templates.ts +645 -0
- package/src-next/session/__tests__/graph.test.ts +277 -0
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
- package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
- package/src-next/session/__tests__/ledger.test.ts +745 -0
- package/src-next/session/__tests__/next.test.ts +460 -0
- package/src-next/session/__tests__/preflight.test.ts +545 -0
- package/src-next/session/__tests__/round-naming.test.ts +142 -0
- package/src-next/session/__tests__/run.test.ts +1026 -0
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
- package/src-next/session/__tests__/wave.test.ts +476 -0
- package/src-next/session/faces.ts +110 -0
- package/src-next/session/graph.ts +411 -0
- package/src-next/session/handoff-schema.ts +373 -0
- package/src-next/session/ledger.ts +1076 -0
- package/src-next/session/next.ts +293 -0
- package/src-next/session/preflight.ts +271 -0
- package/src-next/session/round-naming.ts +84 -0
- package/src-next/session/run.ts +610 -0
- package/src-next/session/state.ts +30 -0
- package/src-next/session/wave.ts +139 -0
- package/templates/report/issue-body.json +17 -65
- package/dist/chunks/branch.mjs +0 -480
- package/dist/chunks/docs.mjs +0 -253
- package/dist/chunks/task.mjs +0 -913
- package/dist/cli.mjs +0 -5457
- package/dist/documents/schema/add-phase-protocol.json +0 -126
- package/dist/documents/schema/overall.json +0 -361
- package/dist/documents/schema/phase-spec.json +0 -145
- package/dist/documents/schema/plan.json +0 -191
- package/dist/documents/schema/skill-anatomy.json +0 -233
- package/dist/resources/harness-registry.json +0 -49
- package/dist/shared/cdd-engine.liioziig.mjs +0 -184
- package/templates/engine-config.json +0 -302
- package/templates/schema/cache-profile-schema.json +0 -23
- package/templates/schema/docs-handoff-schema.json +0 -129
- package/templates/schema/task-handoff-schema.json +0 -332
- package/templates/template-contract.json +0 -231
|
@@ -0,0 +1,684 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/render/__tests__/skeleton.test.ts
|
|
2
|
+
// The SkeletonAssembler suite (P2 — the `cdd schema get <type> --output skeleton`
|
|
3
|
+
// render face, spec §3/§4.1/§4.2):
|
|
4
|
+
// · the four doc skeletons render the complete structural scaffolds — byte-
|
|
5
|
+
// pinned from the P2 first version (the assembler's date is the injectable
|
|
6
|
+
// run-day truth, fixed here — never a live clock);
|
|
7
|
+
// · the front-matter head (spec §2.2/§4.2) — a `---`-fenced YAML record whose
|
|
8
|
+
// key set is the projection's front-matter emission list (the head's required
|
|
9
|
+
// keys plus the type's optional head keys); the placeholder three-way split
|
|
10
|
+
// (link keys a `<…>` scalar · content keys `:::fill <key>` · truth keys their
|
|
11
|
+
// true values; `parent-version` never emitted);
|
|
12
|
+
// · the placeholder-anchoring probes (spec §4.1): pure content slots take
|
|
13
|
+
// `:::fill <slot>`, the link-shaped anchors the placeholder links, the
|
|
14
|
+
// pattern-typed rows the generator truths, and `:::fill` never lands on a
|
|
15
|
+
// structure/truth/link/table-header position;
|
|
16
|
+
// · the doc-contract pin — every rendered skeleton passes its own
|
|
17
|
+
// Contract.validate with zero findings (the skeleton is green by
|
|
18
|
+
// construction);
|
|
19
|
+
// · the EOF rule — render() never ends with a newline or a blank line; the
|
|
20
|
+
// CLI's single appended `\n` leaves a redirected fixture with exactly one
|
|
21
|
+
// final newline.
|
|
22
|
+
|
|
23
|
+
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
24
|
+
import { tmpdir } from "node:os";
|
|
25
|
+
import path from "node:path";
|
|
26
|
+
import { describe, expect, it } from "vitest";
|
|
27
|
+
import { parse } from "yaml";
|
|
28
|
+
import { declaredRegistries } from "../../contract/declare.ts";
|
|
29
|
+
import { Contract } from "../../contract/judge.ts";
|
|
30
|
+
import type { DocKey, DocSkeleton, SkeletonSlot } from "../../contract/project.ts";
|
|
31
|
+
import { Projector } from "../../contract/project.ts";
|
|
32
|
+
import { BoardView } from "../../face/board-view.ts";
|
|
33
|
+
import { type RepoPath, RepoRoot } from "../../infra/root.ts";
|
|
34
|
+
import { SkeletonAssembler } from "../skeleton.ts";
|
|
35
|
+
|
|
36
|
+
/** The fixed run date — the injectable run-day truth (no live clock in the pins). */
|
|
37
|
+
const DATE = "2026-10-11";
|
|
38
|
+
const PROJECTOR = new Projector(declaredRegistries);
|
|
39
|
+
const SKELETONS = PROJECTOR.skeleton();
|
|
40
|
+
const KEYS = ["overall-spec", "plan", "phase-spec", "single-spec"] as const;
|
|
41
|
+
|
|
42
|
+
/** The fixed-date rendered skeleton bytes of one doc type. */
|
|
43
|
+
const renderOf = (key: DocKey): string => new SkeletonAssembler(SKELETONS[key], DATE).render();
|
|
44
|
+
|
|
45
|
+
/** The front-matter block of a rendered skeleton — the lines between the two `---`
|
|
46
|
+
* fences (the §2.2 YAML record; the markdown body starts after the second fence). */
|
|
47
|
+
const frontmatterBlockOf = (key: DocKey): string => {
|
|
48
|
+
const lines = renderOf(key).split("\n");
|
|
49
|
+
const first = lines.indexOf("---");
|
|
50
|
+
return lines.slice(first + 1, lines.indexOf("---", first + 1)).join("\n");
|
|
51
|
+
};
|
|
52
|
+
|
|
53
|
+
/** The registered required anchors of one doc type (the live registry). */
|
|
54
|
+
const requiredAnchorsOf = (key: DocKey): readonly string[] =>
|
|
55
|
+
declaredRegistries[key].elements
|
|
56
|
+
.filter((element) => element.presence === "required")
|
|
57
|
+
.map((element) => element.anchor);
|
|
58
|
+
|
|
59
|
+
/** The live front-matter emission list of one doc type (the head key set the
|
|
60
|
+
* renderer emits — the projection's independent list: required head keys plus
|
|
61
|
+
* the type's optional head keys, `parent-version` excluded). */
|
|
62
|
+
const frontmatterSlotsOf = (key: DocKey): readonly SkeletonSlot[] => SKELETONS[key].frontmatter;
|
|
63
|
+
|
|
64
|
+
/** The per-anchor skeleton probe of the semantic anchors — the anchors whose
|
|
65
|
+
* skeleton form is NOT their literal token (the numeric headings, the table row /
|
|
66
|
+
* cell values, the graph rows and the parse-face names). The literal-marker
|
|
67
|
+
* anchors (`### Goal`, `- **Objective**:` …) fall back to their generic forms. */
|
|
68
|
+
const SEMANTIC_PROBES: Record<string, string> = {
|
|
69
|
+
"### N. group heading": "### 1. :::fill group-title",
|
|
70
|
+
"#### N.M item heading": "#### 1.1 :::fill item-title",
|
|
71
|
+
"### Task N:": "### Task 1: :::fill task-title",
|
|
72
|
+
"Task id token": "### Task 1:",
|
|
73
|
+
"File path token": "- **Files**: :::fill file-paths",
|
|
74
|
+
"Step action": ":::fill step-action",
|
|
75
|
+
"Step checkable": "— checkable: :::fill step-checkable",
|
|
76
|
+
"Acceptance entry": "- `:::fill acceptance-entry`",
|
|
77
|
+
"Constraint delta bullet": "- :::fill constraint",
|
|
78
|
+
"Issue inventory columns": "| Phase | Issue (ref) | Title summary |",
|
|
79
|
+
"Issue row": "| P1 | none | :::fill issue-title |",
|
|
80
|
+
"Issue ref cell": "| P1 | none |",
|
|
81
|
+
"Phase inventory columns":
|
|
82
|
+
"| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
|
|
83
|
+
"Phase row": "| P1 | :::fill phase-name |",
|
|
84
|
+
"Phase id token": "| P1 |",
|
|
85
|
+
"Implementation plan cell": "| Pending |",
|
|
86
|
+
"Design spec cell": "| [Pending] |",
|
|
87
|
+
"Dependency cell": ":::fill dependency",
|
|
88
|
+
"File path row": "| overall-spec | `:::fill overall-path` |",
|
|
89
|
+
"Change history row": "| v0.1 |",
|
|
90
|
+
"Version token": "| v0.1 |",
|
|
91
|
+
"Change history date": DATE,
|
|
92
|
+
"Hard edge": "P1 -> P2",
|
|
93
|
+
"Graph legend": "- `->` = hard block",
|
|
94
|
+
};
|
|
95
|
+
|
|
96
|
+
/** The skeleton-probe token of one registered anchor — the semantic map first,
|
|
97
|
+
* the literal-marker anchors by their generic skeleton forms (the heading
|
|
98
|
+
* literal, the `- **Key**:` field markers), and the front-matter key anchors
|
|
99
|
+
* (the remaining plain tokens — the head's key set) by their `key: ` declaration
|
|
100
|
+
* line. */
|
|
101
|
+
const probeOf = (anchor: string): string => {
|
|
102
|
+
const semantic = SEMANTIC_PROBES[anchor];
|
|
103
|
+
if (semantic !== undefined) return semantic;
|
|
104
|
+
if (anchor.startsWith("# ")) return "# :::fill title";
|
|
105
|
+
if (anchor.startsWith("#")) return anchor;
|
|
106
|
+
if (anchor.startsWith("**")) return `- ${anchor}:`;
|
|
107
|
+
return `${anchor}: `;
|
|
108
|
+
};
|
|
109
|
+
|
|
110
|
+
describe("SkeletonAssembler — the four doc skeletons (byte pins)", () => {
|
|
111
|
+
it("renders the phase-spec skeleton — the front-matter head + the Design double layer + the lineage", () => {
|
|
112
|
+
expect(renderOf("phase-spec")).toBe(
|
|
113
|
+
[
|
|
114
|
+
"---",
|
|
115
|
+
"title: ':::fill title'",
|
|
116
|
+
"doc-type: phase-spec",
|
|
117
|
+
"version: v0.1",
|
|
118
|
+
"date: 2026-10-11",
|
|
119
|
+
"status: Draft",
|
|
120
|
+
"author: ':::fill author'",
|
|
121
|
+
"parent-program: <docs/kairos/specs/…-overall.md>",
|
|
122
|
+
"depends-on: ':::fill depends-on'",
|
|
123
|
+
"---",
|
|
124
|
+
"",
|
|
125
|
+
"## Design",
|
|
126
|
+
"",
|
|
127
|
+
":::fill design-intro",
|
|
128
|
+
"",
|
|
129
|
+
"### 1. :::fill group-title",
|
|
130
|
+
"#### 1.1 :::fill item-title",
|
|
131
|
+
"- :::fill item-body",
|
|
132
|
+
"",
|
|
133
|
+
"### Acceptance criteria",
|
|
134
|
+
"",
|
|
135
|
+
"- `:::fill acceptance-entry`",
|
|
136
|
+
"",
|
|
137
|
+
"## Constraints",
|
|
138
|
+
"",
|
|
139
|
+
"- :::fill constraint",
|
|
140
|
+
"",
|
|
141
|
+
"## Change history",
|
|
142
|
+
"",
|
|
143
|
+
"| Version | date | summary | author |",
|
|
144
|
+
"| --- | --- | --- | --- |",
|
|
145
|
+
"| v0.1 | 2026-10-11 | :::fill summary | :::fill author |",
|
|
146
|
+
].join("\n"),
|
|
147
|
+
);
|
|
148
|
+
});
|
|
149
|
+
|
|
150
|
+
it("renders the plan skeleton — the Class-A/B front-matter head + the first task block + the lineage", () => {
|
|
151
|
+
expect(renderOf("plan")).toBe(
|
|
152
|
+
[
|
|
153
|
+
"---",
|
|
154
|
+
"title: ':::fill title'",
|
|
155
|
+
"doc-type: plan",
|
|
156
|
+
"version: v0.1",
|
|
157
|
+
"date: 2026-10-11",
|
|
158
|
+
"spec: <docs/kairos/specs/…-design.md>",
|
|
159
|
+
"parent-program: <docs/kairos/specs/…-overall.md>",
|
|
160
|
+
"depends-on: ':::fill depends-on'",
|
|
161
|
+
"base: ':::fill base'",
|
|
162
|
+
"---",
|
|
163
|
+
"",
|
|
164
|
+
"## Constraints",
|
|
165
|
+
"",
|
|
166
|
+
"- :::fill constraint",
|
|
167
|
+
"",
|
|
168
|
+
"### Task 1: :::fill task-title",
|
|
169
|
+
"- **Objective**: :::fill objective",
|
|
170
|
+
"- **Files**: :::fill file-paths",
|
|
171
|
+
"- **Consumes**: :::fill consumes",
|
|
172
|
+
"- **Produces**: :::fill produces",
|
|
173
|
+
"- **Steps**:",
|
|
174
|
+
" - :::fill step-action — checkable: :::fill step-checkable",
|
|
175
|
+
"- **Acceptance**: :::fill acceptance",
|
|
176
|
+
"- **DependsOn**: none",
|
|
177
|
+
"",
|
|
178
|
+
"## Change history",
|
|
179
|
+
"",
|
|
180
|
+
"| Version | date | summary | author |",
|
|
181
|
+
"| --- | --- | --- | --- |",
|
|
182
|
+
"| v0.1 | 2026-10-11 | :::fill summary | :::fill author |",
|
|
183
|
+
].join("\n"),
|
|
184
|
+
);
|
|
185
|
+
});
|
|
186
|
+
|
|
187
|
+
it("renders the overall skeleton — the front-matter head + the table sections + the dependency graph", () => {
|
|
188
|
+
expect(renderOf("overall-spec")).toBe(
|
|
189
|
+
[
|
|
190
|
+
"---",
|
|
191
|
+
"title: ':::fill title'",
|
|
192
|
+
"doc-type: overall-spec",
|
|
193
|
+
"version: v0.1",
|
|
194
|
+
"date: 2026-10-11",
|
|
195
|
+
"status: Draft",
|
|
196
|
+
"author: ':::fill author'",
|
|
197
|
+
"---",
|
|
198
|
+
"",
|
|
199
|
+
"## Document scope",
|
|
200
|
+
"",
|
|
201
|
+
":::fill document-scope",
|
|
202
|
+
"",
|
|
203
|
+
"## File paths",
|
|
204
|
+
"",
|
|
205
|
+
"| Artifact | Path |",
|
|
206
|
+
"| --- | --- |",
|
|
207
|
+
"| overall-spec | `:::fill overall-path` |",
|
|
208
|
+
"",
|
|
209
|
+
"## Program charter",
|
|
210
|
+
"",
|
|
211
|
+
"### Goal",
|
|
212
|
+
"",
|
|
213
|
+
"- :::fill goal-description",
|
|
214
|
+
"",
|
|
215
|
+
"### Non-goals",
|
|
216
|
+
"",
|
|
217
|
+
"- :::fill non-goal-description",
|
|
218
|
+
"",
|
|
219
|
+
"### Cross-cutting",
|
|
220
|
+
"",
|
|
221
|
+
"- :::fill cross-cutting-description",
|
|
222
|
+
"",
|
|
223
|
+
"## Issue inventory",
|
|
224
|
+
"",
|
|
225
|
+
"| Phase | Issue (ref) | Title summary |",
|
|
226
|
+
"| --- | --- | --- |",
|
|
227
|
+
"| P1 | none | :::fill issue-title |",
|
|
228
|
+
"",
|
|
229
|
+
"## Phase inventory",
|
|
230
|
+
"",
|
|
231
|
+
"| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
|
|
232
|
+
"| --- | --- | --- | --- | --- | --- | --- |",
|
|
233
|
+
"| P1 | :::fill phase-name | :::fill scope | [Pending] | Pending | :::fill acceptance-criteria | :::fill dependency |",
|
|
234
|
+
"| P2 | :::fill phase-name | :::fill scope | [Pending] | Pending | :::fill acceptance-criteria | :::fill dependency |",
|
|
235
|
+
"",
|
|
236
|
+
"## Dependency graph",
|
|
237
|
+
"",
|
|
238
|
+
"P1 -> P2",
|
|
239
|
+
"- `->` = hard block",
|
|
240
|
+
"",
|
|
241
|
+
"## Boundary rules",
|
|
242
|
+
"",
|
|
243
|
+
"- :::fill boundary-rule",
|
|
244
|
+
"",
|
|
245
|
+
"## Constraints",
|
|
246
|
+
"",
|
|
247
|
+
"- :::fill constraint",
|
|
248
|
+
"",
|
|
249
|
+
"## Maintenance",
|
|
250
|
+
"",
|
|
251
|
+
"- :::fill maintenance-note",
|
|
252
|
+
"",
|
|
253
|
+
"## Change history",
|
|
254
|
+
"",
|
|
255
|
+
"| Version | date | summary | author |",
|
|
256
|
+
"| --- | --- | --- | --- |",
|
|
257
|
+
"| v0.1 | 2026-10-11 | :::fill summary | :::fill author |",
|
|
258
|
+
].join("\n"),
|
|
259
|
+
);
|
|
260
|
+
});
|
|
261
|
+
|
|
262
|
+
it("renders the single-spec skeleton — the front-matter head + the prose sections + the lineage", () => {
|
|
263
|
+
expect(renderOf("single-spec")).toBe(
|
|
264
|
+
[
|
|
265
|
+
"---",
|
|
266
|
+
"title: ':::fill title'",
|
|
267
|
+
"doc-type: single-spec",
|
|
268
|
+
"version: v0.1",
|
|
269
|
+
"date: 2026-10-11",
|
|
270
|
+
"status: Draft",
|
|
271
|
+
"author: ':::fill author'",
|
|
272
|
+
"depends-on: ':::fill depends-on'",
|
|
273
|
+
"issues: ':::fill issues'",
|
|
274
|
+
"---",
|
|
275
|
+
"",
|
|
276
|
+
"## Background & root cause",
|
|
277
|
+
"",
|
|
278
|
+
":::fill background-root-cause",
|
|
279
|
+
"",
|
|
280
|
+
"## Design decisions",
|
|
281
|
+
"",
|
|
282
|
+
":::fill design-ruling",
|
|
283
|
+
"",
|
|
284
|
+
"## Acceptance",
|
|
285
|
+
"",
|
|
286
|
+
":::fill acceptance",
|
|
287
|
+
"",
|
|
288
|
+
"## Constraints",
|
|
289
|
+
"",
|
|
290
|
+
":::fill constraints",
|
|
291
|
+
"",
|
|
292
|
+
"## Change history",
|
|
293
|
+
"",
|
|
294
|
+
"| Version | date | summary | author |",
|
|
295
|
+
"| --- | --- | --- | --- |",
|
|
296
|
+
"| v0.1 | 2026-10-11 | :::fill summary | :::fill author |",
|
|
297
|
+
].join("\n"),
|
|
298
|
+
);
|
|
299
|
+
});
|
|
300
|
+
});
|
|
301
|
+
|
|
302
|
+
describe("SkeletonAssembler — the required-anchor coverage probes (§3.2)", () => {
|
|
303
|
+
it("carries every required anchor of the four doc types (the live registry set)", () => {
|
|
304
|
+
for (const key of KEYS) {
|
|
305
|
+
const rendered = renderOf(key);
|
|
306
|
+
for (const anchor of requiredAnchorsOf(key)) {
|
|
307
|
+
// The grep probe per anchor — the skeleton line form of the anchor lands
|
|
308
|
+
// in the rendered bytes (headings and markers by their literal, the
|
|
309
|
+
// semantic anchors by their rendered value forms, the front-matter keys
|
|
310
|
+
// by their `key: ` declaration line).
|
|
311
|
+
expect(rendered, `${key}: ${anchor}`).toContain(probeOf(anchor));
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
});
|
|
315
|
+
|
|
316
|
+
it("renders the numeric headings as true numbers — zero literal `N`", () => {
|
|
317
|
+
const spec = renderOf("phase-spec");
|
|
318
|
+
expect(spec).toContain("### 1. :::fill group-title");
|
|
319
|
+
expect(spec).toContain("#### 1.1 :::fill item-title");
|
|
320
|
+
const plan = renderOf("plan");
|
|
321
|
+
expect(plan).toContain("### Task 1: :::fill task-title");
|
|
322
|
+
// the declared digit-headed anchors never render a literal `N` placeholder
|
|
323
|
+
expect(rendersNoLiteralN("phase-spec")).toBe(true);
|
|
324
|
+
expect(rendersNoLiteralN("plan")).toBe(true);
|
|
325
|
+
});
|
|
326
|
+
|
|
327
|
+
it("renders the version and date keys and the change-history first row with the injected date truth", () => {
|
|
328
|
+
for (const key of KEYS) {
|
|
329
|
+
const rendered = renderOf(key);
|
|
330
|
+
// the front-matter `version:` / `date:` truth keys — v0.1 · the injected
|
|
331
|
+
// run date (real shape hit, never a `<date>` notation marker)
|
|
332
|
+
expect(rendered).toContain("version: v0.1");
|
|
333
|
+
expect(rendered).toContain(`date: ${DATE}`);
|
|
334
|
+
// the change-history first row — the header version (v0.1) + the date cell
|
|
335
|
+
// + the summary/author content fills
|
|
336
|
+
expect(rendered).toContain(`| v0.1 | ${DATE} | :::fill summary | :::fill author |`);
|
|
337
|
+
// the header version equals the change-history row version (self-consistent
|
|
338
|
+
// lineage, ascending oldest-first with a single row)
|
|
339
|
+
const headerVersion = rendered.match(/^version: (v\d+\.\d+)$/m)?.[1];
|
|
340
|
+
expect(rendered).toContain(`| ${headerVersion} |`);
|
|
341
|
+
}
|
|
342
|
+
});
|
|
343
|
+
|
|
344
|
+
it("renders the generator truths — the enum status key and the graph rows", () => {
|
|
345
|
+
for (const key of ["overall-spec", "phase-spec", "single-spec"] as const) {
|
|
346
|
+
expect(renderOf(key)).toContain("status: Draft");
|
|
347
|
+
}
|
|
348
|
+
// the plan head carries no status key (its registry omits it)
|
|
349
|
+
expect(renderOf("plan")).not.toContain("status: ");
|
|
350
|
+
expect(renderOf("overall-spec")).toContain("P1 -> P2");
|
|
351
|
+
expect(renderOf("overall-spec")).toContain("- `->` = hard block");
|
|
352
|
+
});
|
|
353
|
+
|
|
354
|
+
it("renders every content position as a `:::fill <slot>` slot — the body and the front-matter content keys", () => {
|
|
355
|
+
for (const key of KEYS) {
|
|
356
|
+
const rendered = renderOf(key);
|
|
357
|
+
expect(rendered).toMatch(/:::fill \S+/g);
|
|
358
|
+
// the fill values are the declared slot names — never a residual `<…>`
|
|
359
|
+
// notation or a bare empty value
|
|
360
|
+
expect(rendered).not.toContain(":::fill <");
|
|
361
|
+
const block = frontmatterBlockOf(key);
|
|
362
|
+
for (const slot of frontmatterSlotsOf(key)) {
|
|
363
|
+
if (slot.slot === "content") {
|
|
364
|
+
expect(block, `${key}: ${slot.anchor} content fill`).toContain(
|
|
365
|
+
`${slot.anchor}: ':::fill ${slot.anchor}'`,
|
|
366
|
+
);
|
|
367
|
+
}
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
});
|
|
371
|
+
|
|
372
|
+
it("renders the link-typed anchors as placeholder scalars (the `<…>` exemption shape)", () => {
|
|
373
|
+
const spec = renderOf("phase-spec");
|
|
374
|
+
expect(spec).toContain("parent-program: <docs/kairos/specs/…-overall.md>");
|
|
375
|
+
const plan = renderOf("plan");
|
|
376
|
+
expect(plan).toContain("spec: <docs/kairos/specs/…-design.md>");
|
|
377
|
+
expect(plan).toContain("parent-program: <docs/kairos/specs/…-overall.md>");
|
|
378
|
+
});
|
|
379
|
+
});
|
|
380
|
+
|
|
381
|
+
describe("SkeletonAssembler — the front-matter head (spec §2.2/§4.2)", () => {
|
|
382
|
+
it("emits the projection's front-matter key set — the head parses back key-identical, zero extras", () => {
|
|
383
|
+
for (const key of KEYS) {
|
|
384
|
+
const block = frontmatterBlockOf(key);
|
|
385
|
+
const parsed = parse(block) as Record<string, unknown>;
|
|
386
|
+
const keys = frontmatterSlotsOf(key).map((slot) => slot.anchor);
|
|
387
|
+
expect(Object.keys(parsed).sort(), `${key}: yaml-key set = registry head set`).toEqual(
|
|
388
|
+
[...keys].sort(),
|
|
389
|
+
);
|
|
390
|
+
}
|
|
391
|
+
});
|
|
392
|
+
|
|
393
|
+
it("splits the §4.2 placeholder classes — truth keys never carry a fill, content keys always do, link keys the `<…>` shape", () => {
|
|
394
|
+
for (const key of KEYS) {
|
|
395
|
+
const lines = frontmatterBlockOf(key).split("\n");
|
|
396
|
+
for (const slot of frontmatterSlotsOf(key)) {
|
|
397
|
+
const line = lines.find((candidate) => candidate.startsWith(`${slot.anchor}: `));
|
|
398
|
+
expect(line, `${key}: ${slot.anchor} emitted`).toBeDefined();
|
|
399
|
+
if (slot.slot === "content") {
|
|
400
|
+
expect(line, `${key}: ${slot.anchor} content`).toBe(
|
|
401
|
+
`${slot.anchor}: ':::fill ${slot.anchor}'`,
|
|
402
|
+
);
|
|
403
|
+
} else if (slot.slot === "link") {
|
|
404
|
+
expect(line, `${key}: ${slot.anchor} link`).toMatch(
|
|
405
|
+
new RegExp(`^${slot.anchor}: <[^>]+>$`),
|
|
406
|
+
);
|
|
407
|
+
} else {
|
|
408
|
+
expect(line, `${key}: ${slot.anchor} truth`).not.toContain(":::fill");
|
|
409
|
+
}
|
|
410
|
+
}
|
|
411
|
+
}
|
|
412
|
+
});
|
|
413
|
+
|
|
414
|
+
it("emits the truth keys' true values — doc-type · v0.1 · the injected date · Draft", () => {
|
|
415
|
+
for (const key of KEYS) {
|
|
416
|
+
const block = frontmatterBlockOf(key);
|
|
417
|
+
expect(block).toContain(`doc-type: ${key}`);
|
|
418
|
+
expect(block).toContain("version: v0.1");
|
|
419
|
+
expect(block).toContain(`date: ${DATE}`);
|
|
420
|
+
if (key !== "plan") expect(block).toContain("status: Draft");
|
|
421
|
+
}
|
|
422
|
+
});
|
|
423
|
+
|
|
424
|
+
it("never emits the optional `parent-version` key — its `v<n>.<m>` domain admits no placeholder form", () => {
|
|
425
|
+
for (const key of ["plan", "phase-spec"] as const) {
|
|
426
|
+
expect(renderOf(key)).not.toContain("parent-version");
|
|
427
|
+
}
|
|
428
|
+
});
|
|
429
|
+
|
|
430
|
+
it("emits the type's optional front-matter keys — `base` / `depends-on` on the plan head, `issues` on the single-spec head", () => {
|
|
431
|
+
// §4.2's independent emission list = the head's required keys PLUS the
|
|
432
|
+
// type's optional head keys — the optional keys never ride the slot channel
|
|
433
|
+
// (they are not required), so the head would silently drop them without the
|
|
434
|
+
// dedicated list.
|
|
435
|
+
for (const key of KEYS) {
|
|
436
|
+
const block = frontmatterBlockOf(key);
|
|
437
|
+
const optionalAnchors = declaredRegistries[key].elements
|
|
438
|
+
.filter((element) => element.home === "frontmatter" && element.presence === "optional")
|
|
439
|
+
.map((element) => element.anchor)
|
|
440
|
+
.filter((anchor) => anchor !== "parent-version");
|
|
441
|
+
for (const anchor of optionalAnchors) {
|
|
442
|
+
expect(block, `${key}: optional head key ${anchor} emitted`).toContain(
|
|
443
|
+
`${anchor}: ':::fill ${anchor}'`,
|
|
444
|
+
);
|
|
445
|
+
}
|
|
446
|
+
}
|
|
447
|
+
expect(frontmatterBlockOf("plan")).toContain("base: ':::fill base'");
|
|
448
|
+
expect(frontmatterBlockOf("plan")).toContain("depends-on: ':::fill depends-on'");
|
|
449
|
+
expect(frontmatterBlockOf("single-spec")).toContain("issues: ':::fill issues'");
|
|
450
|
+
});
|
|
451
|
+
});
|
|
452
|
+
|
|
453
|
+
describe("SkeletonAssembler — the placeholder-anchoring probes (§4.1)", () => {
|
|
454
|
+
/** The structure/truth/header rows that must never carry a `:::fill` — the
|
|
455
|
+
* front-matter truth/link keys, the doc-type declaration, the fixed heading
|
|
456
|
+
* lines, the version row, the Status truth, the link anchors, the graph rows
|
|
457
|
+
* and the table headers/separators. */
|
|
458
|
+
const STRUCTURE_LINES: Record<string, readonly string[]> = {
|
|
459
|
+
"overall-spec": [
|
|
460
|
+
"doc-type: overall-spec",
|
|
461
|
+
"version: v0.1",
|
|
462
|
+
"date: 2026-10-11",
|
|
463
|
+
"status: Draft",
|
|
464
|
+
"## Document scope",
|
|
465
|
+
"## File paths",
|
|
466
|
+
"| Artifact | Path |",
|
|
467
|
+
"| --- | --- |",
|
|
468
|
+
"## Program charter",
|
|
469
|
+
"### Goal",
|
|
470
|
+
"### Non-goals",
|
|
471
|
+
"### Cross-cutting",
|
|
472
|
+
"## Issue inventory",
|
|
473
|
+
"| Phase | Issue (ref) | Title summary |",
|
|
474
|
+
"| --- | --- | --- |",
|
|
475
|
+
"## Phase inventory",
|
|
476
|
+
"| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
|
|
477
|
+
"| --- | --- | --- | --- | --- | --- | --- |",
|
|
478
|
+
"## Dependency graph",
|
|
479
|
+
"P1 -> P2",
|
|
480
|
+
"- `->` = hard block",
|
|
481
|
+
"## Boundary rules",
|
|
482
|
+
"## Constraints",
|
|
483
|
+
"## Maintenance",
|
|
484
|
+
"## Change history",
|
|
485
|
+
"| Version | date | summary | author |",
|
|
486
|
+
"| --- | --- | --- | --- |",
|
|
487
|
+
],
|
|
488
|
+
plan: [
|
|
489
|
+
"doc-type: plan",
|
|
490
|
+
"version: v0.1",
|
|
491
|
+
"date: 2026-10-11",
|
|
492
|
+
"spec: <docs/kairos/specs/…-design.md>",
|
|
493
|
+
"parent-program: <docs/kairos/specs/…-overall.md>",
|
|
494
|
+
"## Constraints",
|
|
495
|
+
"## Change history",
|
|
496
|
+
"| Version | date | summary | author |",
|
|
497
|
+
"| --- | --- | --- | --- |",
|
|
498
|
+
],
|
|
499
|
+
"phase-spec": [
|
|
500
|
+
"doc-type: phase-spec",
|
|
501
|
+
"version: v0.1",
|
|
502
|
+
"date: 2026-10-11",
|
|
503
|
+
"status: Draft",
|
|
504
|
+
"parent-program: <docs/kairos/specs/…-overall.md>",
|
|
505
|
+
"## Design",
|
|
506
|
+
"### Acceptance criteria",
|
|
507
|
+
"## Constraints",
|
|
508
|
+
"## Change history",
|
|
509
|
+
"| Version | date | summary | author |",
|
|
510
|
+
"| --- | --- | --- | --- |",
|
|
511
|
+
],
|
|
512
|
+
"single-spec": [
|
|
513
|
+
"doc-type: single-spec",
|
|
514
|
+
"version: v0.1",
|
|
515
|
+
"date: 2026-10-11",
|
|
516
|
+
"status: Draft",
|
|
517
|
+
"## Background & root cause",
|
|
518
|
+
"## Design decisions",
|
|
519
|
+
"## Acceptance",
|
|
520
|
+
"## Constraints",
|
|
521
|
+
"## Change history",
|
|
522
|
+
"| Version | date | summary | author |",
|
|
523
|
+
"| --- | --- | --- | --- |",
|
|
524
|
+
],
|
|
525
|
+
};
|
|
526
|
+
|
|
527
|
+
it("lands every `:::fill` on a content position — zero on the structure/truth/link/header rows", () => {
|
|
528
|
+
for (const key of KEYS) {
|
|
529
|
+
const lines = renderOf(key).split("\n");
|
|
530
|
+
for (const line of lines) {
|
|
531
|
+
if (!line.includes(":::fill")) continue;
|
|
532
|
+
expect(STRUCTURE_LINES[key], `${key}: ${line}`).not.toContain(line);
|
|
533
|
+
}
|
|
534
|
+
expect(renderOf(key)).not.toMatch(/\| --- \|.*:::fill/);
|
|
535
|
+
// the front-matter truth keys carry no fill inside the head block
|
|
536
|
+
for (const line of frontmatterBlockOf(key).split("\n")) {
|
|
537
|
+
if (line.includes(":::fill")) {
|
|
538
|
+
expect(line, `${key} head fill`).toMatch(/':::fill [a-z-]+'$/);
|
|
539
|
+
}
|
|
540
|
+
}
|
|
541
|
+
}
|
|
542
|
+
});
|
|
543
|
+
|
|
544
|
+
it("keeps structure true — the fixed headings and table headers carry no fill", () => {
|
|
545
|
+
for (const key of KEYS) {
|
|
546
|
+
const rendered = renderOf(key);
|
|
547
|
+
for (const line of STRUCTURE_LINES[key]) {
|
|
548
|
+
expect(rendered, `${key}: ${line}`).toContain(line);
|
|
549
|
+
if (!line.includes(":::")) expect(line).not.toContain(":::fill");
|
|
550
|
+
}
|
|
551
|
+
}
|
|
552
|
+
});
|
|
553
|
+
});
|
|
554
|
+
|
|
555
|
+
describe("SkeletonAssembler — the slot-consumption invariant (composition vs registry)", () => {
|
|
556
|
+
it("consumes every required slot of the four live projections — render() never trips the assertion", () => {
|
|
557
|
+
// The four not-to-throw pins also tripwire the overall Constraints
|
|
558
|
+
// triple-same-order composition: the declared `## Constraints` section anchor,
|
|
559
|
+
// the composed heading and the composed `Constraint delta bullet` must land in
|
|
560
|
+
// the same step — a heading without its bullet (or a bullet no longer
|
|
561
|
+
// required) omits a registered required slot and throws below.
|
|
562
|
+
for (const key of KEYS) {
|
|
563
|
+
expect(() => renderOf(key)).not.toThrow();
|
|
564
|
+
}
|
|
565
|
+
});
|
|
566
|
+
|
|
567
|
+
it("loud-throws on an unemitted required slot — a registered anchor the composition does not place", () => {
|
|
568
|
+
const plan = SKELETONS.plan;
|
|
569
|
+
const tampered: DocSkeleton = {
|
|
570
|
+
docType: plan.docType,
|
|
571
|
+
frontmatter: plan.frontmatter,
|
|
572
|
+
slots: [
|
|
573
|
+
...plan.slots,
|
|
574
|
+
{
|
|
575
|
+
anchor: "**Guest anchor**",
|
|
576
|
+
presence: "required",
|
|
577
|
+
home: "section",
|
|
578
|
+
slot: "content",
|
|
579
|
+
refKind: "none",
|
|
580
|
+
},
|
|
581
|
+
],
|
|
582
|
+
};
|
|
583
|
+
expect(() => new SkeletonAssembler(tampered, DATE).render()).toThrow(
|
|
584
|
+
/omits the registered required slot\(s\): \*\*Guest anchor\*\*/,
|
|
585
|
+
);
|
|
586
|
+
});
|
|
587
|
+
|
|
588
|
+
it("loud-throws on an emitted anchor the registry no longer requires — a composed anchor with no registered slot", () => {
|
|
589
|
+
const plan = SKELETONS.plan;
|
|
590
|
+
const tampered: DocSkeleton = {
|
|
591
|
+
docType: plan.docType,
|
|
592
|
+
frontmatter: plan.frontmatter,
|
|
593
|
+
slots: plan.slots.filter((slot) => slot.anchor !== "## Constraints"),
|
|
594
|
+
};
|
|
595
|
+
expect(() => new SkeletonAssembler(tampered, DATE).render()).toThrow(
|
|
596
|
+
/emits the unregistered anchor: ## Constraints/,
|
|
597
|
+
);
|
|
598
|
+
});
|
|
599
|
+
});
|
|
600
|
+
|
|
601
|
+
describe("SkeletonAssembler — the Doc type declaration (spec §3.1 ⑩ / D34)", () => {
|
|
602
|
+
it("declares the doc type in the front-matter head — `doc-type:` precedes `version:` (the registry key order)", () => {
|
|
603
|
+
for (const key of KEYS) {
|
|
604
|
+
const lines = frontmatterBlockOf(key).split("\n");
|
|
605
|
+
const docTypeIndex = lines.indexOf(`doc-type: ${key}`);
|
|
606
|
+
expect(docTypeIndex, `${key}: doc-type key present`).toBeGreaterThan(-1);
|
|
607
|
+
const versionIndex = lines.indexOf("version: v0.1");
|
|
608
|
+
expect(versionIndex, `${key}: version key present`).toBeGreaterThan(-1);
|
|
609
|
+
// the front-matter key order follows the registry's frontmatter-home slot
|
|
610
|
+
// order — doc-type (the doc-identity key) comes before the version row
|
|
611
|
+
expect(docTypeIndex, `${key}: doc-type before version`).toBeLessThan(versionIndex);
|
|
612
|
+
}
|
|
613
|
+
});
|
|
614
|
+
|
|
615
|
+
it("the engine-produced skeleton passes its OWN doc-type reader — BoardView.readDocType (self-preflight regression)", () => {
|
|
616
|
+
// The ⑩ defect: the engine's skeleton omitted the Doc type declaration, so a
|
|
617
|
+
// skeleton it produced failed its own preflight (BoardView.readDocType → null
|
|
618
|
+
// → BLOCK). After the front-matter flip the head's `doc-type:` key IS the
|
|
619
|
+
// canonical machine read — the board face reads the head record (§3.1 ⑩
|
|
620
|
+
// regression). This pin writes each skeleton to disk and asserts the doc-type
|
|
621
|
+
// reader returns the matching key — the writer/reader pair now agrees.
|
|
622
|
+
const dir = mkdtempSync(path.join(tmpdir(), "skeleton-doctype-"));
|
|
623
|
+
try {
|
|
624
|
+
for (const key of KEYS) {
|
|
625
|
+
const file = path.join(dir, `${key}.md`);
|
|
626
|
+
writeFileSync(file, `${renderOf(key)}\n`, "utf8");
|
|
627
|
+
expect(
|
|
628
|
+
BoardView.readDocType(new RepoRoot(dir), path.relative(dir, file) as RepoPath),
|
|
629
|
+
`${key}: skeleton fails its own doc-type read`,
|
|
630
|
+
).toBe(key);
|
|
631
|
+
}
|
|
632
|
+
} finally {
|
|
633
|
+
rmSync(dir, { recursive: true, force: true });
|
|
634
|
+
}
|
|
635
|
+
});
|
|
636
|
+
});
|
|
637
|
+
|
|
638
|
+
describe("SkeletonAssembler — the doc-contract pin (the skeleton green by construction)", () => {
|
|
639
|
+
it("every rendered skeleton passes its own Contract.validate — zero findings on all four types", () => {
|
|
640
|
+
const contract = new Contract();
|
|
641
|
+
const dir = mkdtempSync(path.join(tmpdir(), "skeleton-contract-"));
|
|
642
|
+
try {
|
|
643
|
+
for (const key of KEYS) {
|
|
644
|
+
const file = path.join(dir, `${key}.md`);
|
|
645
|
+
writeFileSync(file, `${renderOf(key)}\n`, "utf8");
|
|
646
|
+
const findings = contract.validate({
|
|
647
|
+
docKey: key,
|
|
648
|
+
path: file,
|
|
649
|
+
content: readFileSync(file, "utf8"),
|
|
650
|
+
root: dir,
|
|
651
|
+
});
|
|
652
|
+
expect(findings, `${key}: skeleton fails its own contract judgment`).toEqual([]);
|
|
653
|
+
}
|
|
654
|
+
} finally {
|
|
655
|
+
rmSync(dir, { recursive: true, force: true });
|
|
656
|
+
}
|
|
657
|
+
});
|
|
658
|
+
});
|
|
659
|
+
|
|
660
|
+
describe("SkeletonAssembler — the EOF rule", () => {
|
|
661
|
+
it("render() never ends with a newline or a blank line — the redirected fixture ends with exactly one `\\n`", () => {
|
|
662
|
+
for (const key of KEYS) {
|
|
663
|
+
const rendered = renderOf(key);
|
|
664
|
+
expect(rendered.endsWith("\n"), `${key}: no trailing newline from render`).toBe(false);
|
|
665
|
+
expect(rendered.endsWith("\n\n") || rendered.endsWith(" \n"), `${key}: no blank tail`).toBe(
|
|
666
|
+
false,
|
|
667
|
+
);
|
|
668
|
+
const withCliNewline = `${rendered}\n`;
|
|
669
|
+
expect(withCliNewline.endsWith("\n")).toBe(true);
|
|
670
|
+
expect(withCliNewline.endsWith("\n\n"), `${key}: exactly one final newline`).toBe(false);
|
|
671
|
+
// the last line of the rendered bytes is real content, never a blank
|
|
672
|
+
const lastLine = rendered.split("\n").at(-1);
|
|
673
|
+
expect(lastLine?.trim().length, `${key}: last line non-blank`).toBeGreaterThan(0);
|
|
674
|
+
}
|
|
675
|
+
});
|
|
676
|
+
});
|
|
677
|
+
|
|
678
|
+
/** Whether any rendered skeleton line carries a literal `N` heading placeholder —
|
|
679
|
+
* the declared digit headings (`### N.` / `#### N.M` / `### Task N:`) always
|
|
680
|
+
* render true numbers, never the letter. */
|
|
681
|
+
const rendersNoLiteralN = (key: DocKey): boolean => {
|
|
682
|
+
const rendered = renderOf(key);
|
|
683
|
+
return !/(?:^|\n)#{2,4} (?:Task )?N[.:]/m.test(rendered) && !rendered.includes("Task N:");
|
|
684
|
+
};
|