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