repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs(the-system): plan document kernel

f088c7a0c2d12f711998d23fcc85ed37c7e7f8dd

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

docs/super/plans/2026-07-11-the-system-phase-2-document-kernel.html

Added
new file mode 100644
1 +<!doctype html>
2 +<html lang="en">
3 +<head>
4 +<meta charset="utf-8">
5 +<meta name="viewport" content="width=device-width, initial-scale=1">
6 +<title>The System Phase 2 project and document kernel implementation plan</title>
7 +<style>
8 +:root { color-scheme:light dark; --fg:#121212; --page:#ededed; --panel:#dbdbdb; --accent:#ae2eae; --ui:#922792; --focus:#184e5b; --error:#bd172e; }
9 +@media(prefers-color-scheme:dark) { :root { --fg:#ededed; --page:#121212; --panel:#242424; --accent:#d151d1; --ui:#d86dd8; --focus:#7ba1aa; --error:#ec6376; } }
10 +* { box-sizing:border-box; }
11 +body { margin:0; padding:1rem; background:var(--page); color:var(--fg); font:14px/1.55 ui-monospace,SFMono-Regular,Consolas,monospace; }
12 +article { width:min(100%,1060px); margin:0 auto 3rem; border:3px solid var(--fg); box-shadow:10px 10px 0 var(--ui); }
13 +header,section { padding:clamp(1rem,3vw,1.5rem); border-bottom:2px solid var(--fg); }
14 +header { background:var(--panel); border-bottom-width:3px; }
15 +h1 { margin:.25rem 0; font:900 clamp(1.8rem,6vw,3.7rem)/.92 system-ui; text-transform:uppercase; }
16 +h2 { margin:0 0 1rem; color:var(--accent); font:900 1rem/1 system-ui; letter-spacing:.12em; text-transform:uppercase; }
17 +h3 { margin:1.4rem 0 .5rem; font-size:.92rem; text-transform:uppercase; }
18 +p,li { max-width:90ch; }
19 +li { margin:.35rem 0; }
20 +a { color:var(--focus); font-weight:900; }
21 +code,pre { background:var(--panel); }
22 +code { padding:.1rem .3rem; }
23 +pre { padding:1rem; overflow:auto; border:2px solid var(--fg); border-left:7px solid var(--ui); font-size:.82rem; line-height:1.45; }
24 +.contract { padding:1rem; border:2px solid var(--fg); border-left:8px solid var(--ui); background:var(--panel); font-weight:800; }
25 +.red { border-left-color:var(--error); }
26 +table { width:100%; border-collapse:collapse; }
27 +th,td { padding:.65rem; border:2px solid var(--fg); text-align:left; vertical-align:top; }
28 +th { background:var(--panel); }
29 +.checks { list-style:none; padding-left:0; }
30 +.checks li::before { content:"☐ "; color:var(--accent); font-weight:900; }
31 +@media(max-width:620px) { body { padding:.5rem; } article { box-shadow:5px 5px 0 var(--ui); } th,td { display:block; width:100%; } }
32 +</style>
33 +</head>
34 +<body>
35 +<article>
36 +<header>
37 +<p><strong>Phase 2 implementation plan · 2026-07-11</strong></p>
38 +<h1>Project + document kernel</h1>
39 +<p><a href="../roadmaps/2026-07-11-the-system-roadmap.html">Roadmap</a> · <a href="../specs/2026-07-11-the-system-design.html">Design spec</a> · <a href="./2026-07-11-the-system-phase-1-hard-rename.html">Phase 1 plan</a></p>
40 +<p><strong>For agentic workers:</strong> REQUIRED SUB-SKILL: use <code>/skill:executing-plans</code> and execute every checkbox in order.</p>
41 +<div class="contract"><strong>Goal:</strong> add a dormant, pure, dependency-free kernel that resolves project roots, confines governed paths, validates config and authored documents, indexes their graph, and ships style version 1.</div>
42 +<p><strong>Architecture:</strong> <code>documents.ts</code> exposes deterministic functions over explicit strings and document arrays; only root discovery reads marker existence through an injectable adapter. Validation returns sorted diagnostics instead of mutating or repairing input. Runtime registration, doctor traversal, initialization, prompts, hooks, and browser behavior remain absent.</p>
43 +<p><strong>Tech stack:</strong> TypeScript, Node <code>fs</code>/<code>path</code>, Vitest, Node assert, plain CSS; no parser, schema, DOM, shell, network, or runtime dependency.</p>
44 +<p><strong>Roadmap:</strong> <code>docs/super/roadmaps/2026-07-11-the-system-roadmap.html</code></p>
45 +<p><strong>Phase:</strong> Phase 2: Project and document kernel.</p>
46 +</header>
47 +<main>
48 +<section>
49 +<h2>Boundary and locked decisions</h2>
50 +<ul>
51 +<li>Work only in <code>extensions/the-system/documents.ts</code>, <code>extensions/the-system/__tests__/documents.test.ts</code>, <code>extensions/the-system/assets/system.css</code>, and <code>tsconfig.json</code>.</li>
52 +<li>Do not import <code>documents.ts</code> from <code>index.ts</code>; Phase 2 must have no runtime behavior.</li>
53 +<li>Do not add doctor, directory walking, writes, prompts, skills, package metadata, hooks, initialization, browser opening, test-reference discovery, or mockup-orphan checks; those belong to later phases.</li>
54 +<li>Use lexical normalization and containment. Do not call <code>realpath</code>: nonexistent write candidates must be checkable in Phase 5.</li>
55 +<li>Treat either a file or directory named <code>.git</code> as a Git marker, so linked worktrees remain rooted at their worktree.</li>
56 +<li>Use metadata key <code>capturedAt</code> for the spec's “ISO capture date”; accept exactly <code>YYYY-MM-DD</code> that round-trips through UTC calendar validation.</li>
57 +<li>A plan's <code>roadmap</code> and <code>phase</code> are an all-or-neither pair. This makes “one phase in that roadmap” representable without ambiguity.</li>
58 +<li>Reject <code>000</code>, noncanonical zero padding, unsupported types, unknown keys, duplicate top-level JSON keys, and foreign prefixes.</li>
59 +<li>Stable diagnostic order is <code>path</code>, then <code>code</code>, then <code>message</code>.</li>
60 +<li>Commit commands below are execution-time checkpoints. Do not commit this planning-only change.</li>
61 +</ul>
62 +</section>
63 +<section>
64 +<h2>File map</h2>
65 +<table>
66 +<tr><th>File</th><th>Action</th><th>Single responsibility</th></tr>
67 +<tr><td><code>extensions/the-system/documents.ts</code></td><td>Create</td><td>Pure root/path, strict JSON schemas, IDs/names, authored-HTML lint, metadata parsing, and graph indexing.</td></tr>
68 +<tr><td><code>extensions/the-system/__tests__/documents.test.ts</code></td><td>Create</td><td>Table-driven behavioral contract for every Phase 2 branch and diagnostic.</td></tr>
69 +<tr><td><code>extensions/the-system/assets/system.css</code></td><td>Create</td><td>Approved Nugu styleVersion 1 tokens, dossier primitives, responsive behavior, and no remote assets.</td></tr>
70 +<tr><td><code>tsconfig.json</code></td><td>Modify</td><td>Typecheck the new kernel while retaining the temporary exclusions for unchanged legacy runtime files.</td></tr>
71 +</table>
72 +<h3>Public kernel surface</h3>
73 +<pre><code>export const SCHEMA_VERSION = 1;
74 +export const STYLE_VERSION = 1;
75 +export type DocumentType = "spec" | "roadmap" | "plan" | "issue" | "research";
76 +export type SystemConfig = Readonly&lt;{ prefix: string; schemaVersion: number; styleVersion: number }&gt;;
77 +export type DocumentSource = Readonly&lt;{ path: string; html: string }&gt;;
78 +export type Diagnostic = Readonly&lt;{ code: string; path: string; message: string }&gt;;
79 +export type DocumentRecord = Readonly&lt;{ path: string; metadata: DocumentMetadata }&gt;;
80 +export type DocumentIndex = Readonly&lt;{ documents: readonly DocumentRecord[]; diagnostics: readonly Diagnostic[] }&gt;;
82 +export class SystemDocumentError extends Error {
83 + readonly code: string;
86 +export function discoverProjectRoot(cwd: string, markerExists?: (path: string) =&gt; boolean): string;
87 +export function resolveGovernedPath(root: string, candidate: string): string;
88 +export function parseSystemConfig(source: string): SystemConfig;
89 +export function parseDocumentId(source: string, expectedPrefix?: string): ParsedDocumentId;
90 +export function validateFilename(path: string, metadata: DocumentMetadata, prefix: string): void;
91 +export function parseDocumentMetadata(html: string, prefix: string): DocumentMetadata;
92 +export function validateAuthoredHtml(path: string, html: string): readonly Diagnostic[];
93 +export function indexDocuments(sources: readonly DocumentSource[], prefix: string): DocumentIndex;</code></pre>
94 +</section>
95 +<section>
96 +<h2>Task 1 · Baseline and Phase 2 guardrails</h2>
97 +<ul class="checks">
98 +<li><strong>Step 1: inspect the worktree without changing it.</strong><br>Run: <code>git status --short</code><br>Expected: existing unrelated entries are recorded and remain untouched throughout execution.</li>
99 +<li><strong>Step 2: prove the renamed package baseline.</strong><br>Run: <code>mise run test -- extensions/the-system/__tests__</code><br>Expected: all current <code>the-system</code> tests pass; no <code>documents.test.ts</code> exists yet.</li>
100 +<li><strong>Step 3: prove repository checks before adding the kernel.</strong><br>Run: <code>mise run check</code><br>Expected: static checks print their existing success output, including <code>OK static-check tests</code>.</li>
101 +<li><strong>Step 4: verify dormant integration.</strong><br>Run: <code>git grep -n "documents\.ts\|from \"\.\/documents" -- extensions/the-system/index.ts extensions/the-system/mockup.ts</code><br>Expected: exit 1 and no output.</li>
102 +</ul>
103 +</section>
104 +<section>
105 +<h2>Task 2 · Root discovery and governed containment</h2>
106 +<p>Start with the filesystem boundary. The tests use real temporary marker trees, including a <code>.git</code> file, while the implementation only observes markers.</p>
107 +<ul class="checks">
108 +<li><strong>Step 1: create the failing root/path tests.</strong> Create <code>extensions/the-system/__tests__/documents.test.ts</code> with:</li>
109 +</ul>
110 +<pre><code>import assert from "node:assert/strict";
111 +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
112 +import { tmpdir } from "node:os";
113 +import path from "node:path";
114 +import { afterEach, describe, it } from "vitest";
115 +import {
116 + discoverProjectRoot,
117 + resolveGovernedPath,
118 + SystemDocumentError,
119 +} from "../documents.ts";
121 +const temporary: string[] = [];
122 +const tree = () =&gt; {
123 + const root = mkdtempSync(path.join(tmpdir(), "the-system-documents-"));
124 + temporary.push(root);
125 + return root;
127 +const dir = (...parts: string[]) =&gt; {
128 + const result = path.join(...parts);
129 + mkdirSync(result, { recursive: true });
130 + return result;
132 +afterEach(() =&gt; {
133 + for (const root of temporary.splice(0)) rmSync(root, { recursive: true, force: true });
134 +});
136 +describe("project root", () =&gt; {
137 + it.each([
138 + ["simple Git", [".git"], "directory"],
139 + ["Git worktree", [".git"], "file"],
140 + ["JJ workspace", [".jj"], "directory"],
141 + ["colocated JJ/Git", [".jj", ".git"], "directory"],
142 + ] as const)("resolves %s", (_name, markers, markerKind) =&gt; {
143 + const root = tree();
144 + const cwd = dir(root, "packages", "app");
145 + for (const marker of markers) {
146 + const target = path.join(root, marker);
147 + if (markerKind === "file" &amp;&amp; marker === ".git") writeFileSync(target, "gitdir: ../shared\n");
148 + else mkdirSync(target);
150 + assert.equal(discoverProjectRoot(cwd), root);
151 + });
153 + it("uses cwd when no VCS marker exists", () =&gt; {
154 + const cwd = dir(tree(), "plain");
155 + assert.equal(discoverProjectRoot(cwd), path.resolve(cwd));
156 + });
158 + it("fails when nearest JJ and Git roots differ", () =&gt; {
159 + const gitRoot = tree();
160 + mkdirSync(path.join(gitRoot, ".git"));
161 + const jjRoot = dir(gitRoot, "nested");
162 + mkdirSync(path.join(jjRoot, ".jj"));
163 + const cwd = dir(jjRoot, "src");
164 + assert.throws(
165 + () =&gt; discoverProjectRoot(cwd),
166 + (error: unknown) =&gt; error instanceof SystemDocumentError &amp;&amp;
167 + error.code === "root.conflict" &amp;&amp;
168 + error.message === `Conflicting project roots: Git ${gitRoot}; JJ ${jjRoot}`,
169 + );
170 + });
171 +});
173 +describe("governed path containment", () =&gt; {
174 + it("normalizes a contained relative path", () =&gt; {
175 + const root = path.resolve("project");
176 + assert.equal(resolveGovernedPath(root, ".system/specs/../plans/a.html"), path.join(root, ".system", "plans", "a.html"));
177 + });
179 + it.each(["../outside", path.resolve("outside")])("rejects %s", (candidate) =&gt; {
180 + assert.throws(
181 + () =&gt; resolveGovernedPath(path.resolve("project"), candidate),
182 + (error: unknown) =&gt; error instanceof SystemDocumentError &amp;&amp; error.code === "path.outside-root",
183 + );
184 + });
186 + it("does not confuse a sibling sharing the root prefix for a child", () =&gt; {
187 + const root = path.resolve("project");
188 + assert.throws(() =&gt; resolveGovernedPath(root, path.resolve("project-other/file")), /outside project root/);
189 + });
190 +});</code></pre>
191 +<ul class="checks">
192 +<li><strong>Step 2: run RED.</strong><br>Run: <code>mise run test -- extensions/the-system/__tests__/documents.test.ts</code><br>Expected: FAIL because <code>../documents.ts</code> cannot be resolved.</li>
193 +<li><strong>Step 3: create the minimal root/path implementation.</strong> Create <code>extensions/the-system/documents.ts</code> with:</li>
194 +</ul>
195 +<pre><code>import { existsSync } from "node:fs";
196 +import path from "node:path";
198 +export const SCHEMA_VERSION = 1;
199 +export const STYLE_VERSION = 1;
201 +export class SystemDocumentError extends Error {
202 + constructor(readonly code: string, message: string) {
203 + super(message);
204 + this.name = "SystemDocumentError";
208 +const nearestMarker = (cwd: string, marker: string, markerExists: (path: string) =&gt; boolean) =&gt; {
209 + let current = path.resolve(cwd);
210 + while (true) {
211 + if (markerExists(path.join(current, marker))) return current;
212 + const parent = path.dirname(current);
213 + if (parent === current) return undefined;
214 + current = parent;
218 +export function discoverProjectRoot(cwd: string, markerExists = existsSync): string {
219 + const resolvedCwd = path.resolve(cwd);
220 + const jj = nearestMarker(resolvedCwd, ".jj", markerExists);
221 + const git = nearestMarker(resolvedCwd, ".git", markerExists);
222 + if (jj &amp;&amp; git &amp;&amp; jj !== git) {
223 + throw new SystemDocumentError("root.conflict", `Conflicting project roots: Git ${git}; JJ ${jj}`);
225 + return jj ?? git ?? resolvedCwd;
228 +export function resolveGovernedPath(root: string, candidate: string): string {
229 + const normalizedRoot = path.resolve(root);
230 + const target = path.resolve(normalizedRoot, candidate);
231 + const relative = path.relative(normalizedRoot, target);
232 + if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
233 + throw new SystemDocumentError("path.outside-root", `Path is outside project root: ${candidate}`);
235 + return target;
236 +}</code></pre>
237 +<ul class="checks">
238 +<li><strong>Step 4: run GREEN.</strong><br>Run: <code>mise run test -- extensions/the-system/__tests__/documents.test.ts</code><br>Expected: PASS with 8 root/path cases.</li>
239 +<li><strong>Step 5: checkpoint.</strong><br>Run: <code>git add extensions/the-system/documents.ts extensions/the-system/__tests__/documents.test.ts &amp;&amp; git commit -m "feat(the-system): resolve governed project roots"</code><br>Expected: one commit containing only those two files.</li>
240 +</ul>
241 +</section>
242 +<section>
243 +<h2>Task 3 · Strict config, IDs, slugs, and filenames</h2>
244 +<ul class="checks">
245 +<li><strong>Step 1: append failing table-driven schema tests.</strong> Add these imports to the existing import list: <code>parseDocumentId</code>, <code>parseSystemConfig</code>, and <code>validateFilename</code>. Append:</li>
246 +</ul>
247 +<pre><code>describe("system config", () =&gt; {
248 + it("accepts only the exact versioned shape", () =&gt; {
249 + assert.deepEqual(parseSystemConfig('{"prefix":"PX","schemaVersion":1,"styleVersion":1}'), {
250 + prefix: "PX", schemaVersion: 1, styleVersion: 1,
251 + });
252 + });
254 + it.each([
255 + ["malformed JSON", "{"],
256 + ["unknown key", '{"prefix":"PX","schemaVersion":1,"styleVersion":1,"extra":true}'],
257 + ["missing key", '{"prefix":"PX","schemaVersion":1}'],
258 + ["short prefix", '{"prefix":"P","schemaVersion":1,"styleVersion":1}'],
259 + ["lowercase prefix", '{"prefix":"px","schemaVersion":1,"styleVersion":1}'],
260 + ["zero schema", '{"prefix":"PX","schemaVersion":0,"styleVersion":1}'],
261 + ["fractional style", '{"prefix":"PX","schemaVersion":1,"styleVersion":1.5}'],
262 + ])("rejects %s", (_name, source) =&gt; assert.throws(() =&gt; parseSystemConfig(source), SystemDocumentError));
263 +});
265 +describe("document IDs and filenames", () =&gt; {
266 + it.each([
267 + ["PX-SPEC-001", "spec", 1],
268 + ["PX-ROADMAP-999", "roadmap", 999],
269 + ["PX-PLAN-1000", "plan", 1000],
270 + ["PX-ISSUE-042", "issue", 42],
271 + ["PX-RESEARCH-007", "research", 7],
272 + ] as const)("parses %s", (id, type, sequence) =&gt; {
273 + assert.deepEqual(parseDocumentId(id, "PX"), { id, prefix: "PX", type, sequence });
274 + });
276 + it.each([
277 + "P-SPEC-001", "px-SPEC-001", "PX-spec-001", "PX-SPEC-01", "PX-SPEC-000",
278 + "PX-SPEC-0001", "PX-TEST-001", "PX-SPEC-001-slug",
279 + ])("rejects invalid ID %s", (id) =&gt; assert.throws(() =&gt; parseDocumentId(id), /Invalid document ID/));
281 + it("rejects a foreign configured prefix", () =&gt; assert.throws(() =&gt; parseDocumentId("AB-SPEC-001", "PX"), /prefix PX/));
283 + it("accepts a matching type directory, ID, and slug", () =&gt; {
284 + assert.doesNotThrow(() =&gt; validateFilename("/project/.system/specs/PX-SPEC-001-login-flow.html", { id: "PX-SPEC-001", type: "spec" }, "PX"));
285 + });
287 + it.each([
288 + "/project/.system/specs/PX-SPEC-002-login-flow.html",
289 + "/project/.system/specs/PX-SPEC-001-Login.html",
290 + "/project/.system/plans/PX-SPEC-001-login-flow.html",
291 + "/project/.system/specs/PX-SPEC-001-login_flow.html",
292 + ])("rejects mismatched filename %s", (filename) =&gt; {
293 + assert.throws(() =&gt; validateFilename(filename, { id: "PX-SPEC-001", type: "spec" }, "PX"), /Filename mismatch/);
294 + });
295 +});</code></pre>
296 +<ul class="checks">
297 +<li><strong>Step 2: run RED.</strong><br>Run: <code>mise run test -- extensions/the-system/__tests__/documents.test.ts</code><br>Expected: FAIL with missing exports <code>parseSystemConfig</code>, <code>parseDocumentId</code>, and <code>validateFilename</code>.</li>
298 +<li><strong>Step 3: append the exact minimal schemas and naming implementation to <code>documents.ts</code>.</strong></li>
299 +</ul>
300 +<pre><code>export const DOCUMENT_TYPES = ["spec", "roadmap", "plan", "issue", "research"] as const;
301 +export type DocumentType = (typeof DOCUMENT_TYPES)[number];
302 +export type SystemConfig = Readonly&lt;{ prefix: string; schemaVersion: number; styleVersion: number }&gt;;
303 +export type ParsedDocumentId = Readonly&lt;{ id: string; prefix: string; type: DocumentType; sequence: number }&gt;;
304 +export type SpecMetadata = Readonly&lt;{ id: string; type: "spec" }&gt;;
305 +export type RoadmapMetadata = Readonly&lt;{ id: string; type: "roadmap"; spec: string }&gt;;
306 +export type PlanMetadata = Readonly&lt;{ id: string; type: "plan"; spec: string; roadmap?: string; phase?: number }&gt;;
307 +export type IssueMetadata = Readonly&lt;{ id: string; type: "issue"; status: "open" | "fixed"; specs: readonly string[] }&gt;;
308 +export type ResearchMetadata = Readonly&lt;{ id: string; type: "research"; capturedAt: string; sources?: readonly string[] }&gt;;
309 +export type DocumentMetadata = SpecMetadata | RoadmapMetadata | PlanMetadata | IssueMetadata | ResearchMetadata;
311 +const PREFIX = /^[A-Z][A-Z0-9]{1,7}$/;
312 +const SLUG = "[a-z0-9]+(?:-[a-z0-9]+)*";
313 +const TYPE_BY_TOKEN = new Map(DOCUMENT_TYPES.map((type) =&gt; [type.toUpperCase(), type]));
314 +const DIRECTORY_BY_TYPE: Readonly&lt;Record&lt;DocumentType, string&gt;&gt; = {
315 + spec: "specs", roadmap: "roadmaps", plan: "plans", issue: "issues", research: "research",
318 +const objectValue = (value: unknown, label: string): Record&lt;string, unknown&gt; =&gt; {
319 + if (typeof value !== "object" || value === null || Array.isArray(value)) {
320 + throw new SystemDocumentError("json.shape", `${label} must be a JSON object`);
322 + return value as Record&lt;string, unknown&gt;;
324 +const exactKeys = (value: Record&lt;string, unknown&gt;, required: readonly string[], optional: readonly string[] = []) =&gt; {
325 + const actual = Object.keys(value).sort();
326 + const allowed = new Set([...required, ...optional]);
327 + if (required.some((key) =&gt; !(key in value)) || actual.some((key) =&gt; !allowed.has(key))) {
328 + throw new SystemDocumentError("json.keys", `Expected keys ${[...required, ...optional].sort().join(", ")}; received ${actual.join(", ")}`);
331 +const positiveInteger = (value: unknown) =&gt; typeof value === "number" &amp;&amp; Number.isInteger(value) &amp;&amp; value &gt; 0;
333 +export function parseSystemConfig(source: string): SystemConfig {
334 + let parsed: unknown;
335 + try { parsed = JSON.parse(source); } catch { throw new SystemDocumentError("config.invalid-json", "Invalid config JSON"); }
336 + const value = objectValue(parsed, "Config");
337 + exactKeys(value, ["prefix", "schemaVersion", "styleVersion"]);
338 + if (typeof value.prefix !== "string" || !PREFIX.test(value.prefix)) throw new SystemDocumentError("config.prefix", "Invalid project prefix");
339 + if (!positiveInteger(value.schemaVersion) || !positiveInteger(value.styleVersion)) throw new SystemDocumentError("config.version", "Schema and style versions must be positive integers");
340 + return { prefix: value.prefix, schemaVersion: value.schemaVersion as number, styleVersion: value.styleVersion as number };
343 +export function parseDocumentId(source: string, expectedPrefix?: string): ParsedDocumentId {
344 + const match = /^([A-Z][A-Z0-9]{1,7})-(SPEC|ROADMAP|PLAN|ISSUE|RESEARCH)-([0-9]{3,})$/.exec(source);
345 + const sequence = match ? Number(match[3]) : 0;
346 + const canonical = sequence &gt; 0 ? String(sequence).padStart(3, "0") : "";
347 + if (!match || match[3] !== canonical) throw new SystemDocumentError("id.invalid", `Invalid document ID: ${source}`);
348 + if (expectedPrefix &amp;&amp; match[1] !== expectedPrefix) throw new SystemDocumentError("id.prefix", `Document ID must use prefix ${expectedPrefix}: ${source}`);
349 + return { id: source, prefix: match[1], type: TYPE_BY_TOKEN.get(match[2]) as DocumentType, sequence };
352 +export function validateFilename(filename: string, metadata: DocumentMetadata, prefix: string): void {
353 + const parsed = parseDocumentId(metadata.id, prefix);
354 + const expectedDirectory = DIRECTORY_BY_TYPE[metadata.type];
355 + const directory = path.basename(path.dirname(filename));
356 + const pattern = new RegExp(`^${metadata.id}-${SLUG}\\.html$`);
357 + if (parsed.type !== metadata.type || directory !== expectedDirectory || !pattern.test(path.basename(filename))) {
358 + throw new SystemDocumentError("document.filename", `Filename mismatch for ${metadata.id}: ${filename}`);
360 +}</code></pre>
361 +<ul class="checks">
362 +<li><strong>Step 4: run GREEN.</strong><br>Run: <code>mise run test -- extensions/the-system/__tests__/documents.test.ts</code><br>Expected: PASS with config, five ID types, growth past 999, slug, directory, and mismatch cases green.</li>
363 +<li><strong>Step 5: checkpoint.</strong><br>Run: <code>git add extensions/the-system/documents.ts extensions/the-system/__tests__/documents.test.ts &amp;&amp; git commit -m "feat(the-system): validate config and document names"</code><br>Expected: one commit containing only the two kernel files.</li>
364 +</ul>
365 +</section>
366 +<section>
367 +<h2>Task 4 · Exact metadata and narrow authored HTML</h2>
368 +<p>The metadata parser recognizes exactly one non-executable <code>script#system-meta[type="application/json"]</code>. The authored-HTML lint is structural lint for trusted source, never a browser sandbox: it performs no DOM execution, fetch, import, or evaluation.</p>
369 +<ul class="checks">
370 +<li><strong>Step 1: append failing metadata tests.</strong> Add <code>parseDocumentMetadata</code> and <code>validateAuthoredHtml</code> to imports, then append:</li>
371 +</ul>
372 +<pre><code>const shell = (metadata: string, body = "&lt;header&gt;&lt;h1&gt;Title&lt;/h1&gt;&lt;/header&gt;&lt;main&gt;&lt;section&gt;&lt;h2&gt;Contract&lt;/h2&gt;&lt;p&gt;Readable.&lt;/p&gt;&lt;/section&gt;&lt;/main&gt;") =&gt; `&lt;!doctype html&gt;
373 +&lt;html lang="en"&gt;&lt;head&gt;&lt;meta charset="utf-8"&gt;
374 +&lt;meta name="viewport" content="width=device-width, initial-scale=1"&gt;
375 +&lt;title&gt;Title&lt;/title&gt;&lt;link rel="stylesheet" href="../system.css"&gt;&lt;/head&gt;
376 +&lt;body&gt;${body}&lt;script type="application/json" id="system-meta"&gt;${metadata}&lt;/script&gt;&lt;/body&gt;&lt;/html&gt;`;
378 +describe("document metadata", () =&gt; {
379 + it.each([
380 + ['{"id":"PX-SPEC-001","type":"spec"}', { id: "PX-SPEC-001", type: "spec" }],
381 + ['{"id":"PX-ROADMAP-001","type":"roadmap","spec":"PX-SPEC-001"}', { id: "PX-ROADMAP-001", type: "roadmap", spec: "PX-SPEC-001" }],
382 + ['{"id":"PX-PLAN-001","type":"plan","spec":"PX-SPEC-001"}', { id: "PX-PLAN-001", type: "plan", spec: "PX-SPEC-001" }],
383 + ['{"id":"PX-PLAN-002","type":"plan","spec":"PX-SPEC-001","roadmap":"PX-ROADMAP-001","phase":2}', { id: "PX-PLAN-002", type: "plan", spec: "PX-SPEC-001", roadmap: "PX-ROADMAP-001", phase: 2 }],
384 + ['{"id":"PX-ISSUE-001","type":"issue","status":"open","specs":[]}', { id: "PX-ISSUE-001", type: "issue", status: "open", specs: [] }],
385 + ['{"id":"PX-RESEARCH-001","type":"research","capturedAt":"2026-07-11","sources":["https://example.com/a"]}', { id: "PX-RESEARCH-001", type: "research", capturedAt: "2026-07-11", sources: ["https://example.com/a"] }],
386 + ] as const)("parses exact metadata %s", (json, expected) =&gt; assert.deepEqual(parseDocumentMetadata(shell(json), "PX"), expected));
388 + it.each([
389 + ["missing block", "&lt;!doctype html&gt;&lt;html lang=\"en\"&gt;&lt;/html&gt;"],
390 + ["duplicate blocks", shell('{"id":"PX-SPEC-001","type":"spec"}') + '&lt;script type="application/json" id="system-meta"&gt;{}&lt;/script&gt;'],
391 + ["duplicate JSON key", shell('{"id":"PX-SPEC-001","id":"PX-SPEC-002","type":"spec"}')],
392 + ["unknown key", shell('{"id":"PX-SPEC-001","type":"spec","status":"open"}')],
393 + ["own ID/type mismatch", shell('{"id":"PX-PLAN-001","type":"spec"}')],
394 + ["one-sided roadmap", shell('{"id":"PX-PLAN-001","type":"plan","spec":"PX-SPEC-001","roadmap":"PX-ROADMAP-001"}')],
395 + ["duplicate issue specs", shell('{"id":"PX-ISSUE-001","type":"issue","status":"fixed","specs":["PX-SPEC-001","PX-SPEC-001"]}')],
396 + ["invalid date", shell('{"id":"PX-RESEARCH-001","type":"research","capturedAt":"2026-02-30"}')],
397 + ["non-HTTPS source", shell('{"id":"PX-RESEARCH-001","type":"research","capturedAt":"2026-07-11","sources":["http://example.com"]}')],
398 + ])("rejects %s", (_name, html) =&gt; assert.throws(() =&gt; parseDocumentMetadata(html, "PX"), SystemDocumentError));
399 +});
401 +describe("authored HTML", () =&gt; {
402 + it("accepts the complete semantic shell and inert progressive enhancement", () =&gt; {
403 + const html = shell('{"id":"PX-SPEC-001","type":"spec"}', "&lt;header&gt;&lt;h1&gt;Title&lt;/h1&gt;&lt;/header&gt;&lt;main&gt;&lt;section&gt;&lt;h2&gt;Contract&lt;/h2&gt;&lt;details&gt;&lt;summary&gt;More&lt;/summary&gt;&lt;p&gt;Text.&lt;/p&gt;&lt;/details&gt;&lt;/section&gt;&lt;/main&gt;&lt;script&gt;document.querySelector('details');&lt;/script&gt;");
404 + assert.deepEqual(validateAuthoredHtml("specs/PX-SPEC-001-title.html", html), []);
405 + });
407 + it.each([
408 + ["document.doctype", shell('{"id":"PX-SPEC-001","type":"spec"}').replace("&lt;!doctype html&gt;", "")],
409 + ["document.language", shell('{"id":"PX-SPEC-001","type":"spec"}').replace('lang="en"', 'lang="fr"')],
410 + ["document.charset", shell('{"id":"PX-SPEC-001","type":"spec"}').replace('&lt;meta charset="utf-8"&gt;', "")],
411 + ["document.viewport", shell('{"id":"PX-SPEC-001","type":"spec"}').replace(/&lt;meta name="viewport"[^&gt;]+&gt;/, "")],
412 + ["document.title", shell('{"id":"PX-SPEC-001","type":"spec"}').replace("&lt;title&gt;Title&lt;/title&gt;", "&lt;title&gt;&lt;/title&gt;")],
413 + ["document.stylesheet", shell('{"id":"PX-SPEC-001","type":"spec"}').replace("../system.css", "./local.css")],
414 + ["document.semantic-shell", shell('{"id":"PX-SPEC-001","type":"spec"}').replace(/&lt;main&gt;|&lt;\/main&gt;/g, "")],
415 + ["document.forbidden-tag", shell('{"id":"PX-SPEC-001","type":"spec"}', "&lt;header&gt;&lt;h1&gt;X&lt;/h1&gt;&lt;/header&gt;&lt;main&gt;&lt;section&gt;&lt;iframe src=\"x\"&gt;&lt;/iframe&gt;&lt;/section&gt;&lt;/main&gt;")],
416 + ["document.event-handler", shell('{"id":"PX-SPEC-001","type":"spec"}', "&lt;header&gt;&lt;h1&gt;X&lt;/h1&gt;&lt;/header&gt;&lt;main&gt;&lt;section onclick=\"x()\"&gt;X&lt;/section&gt;&lt;/main&gt;")],
417 + ["document.executable-url", shell('{"id":"PX-SPEC-001","type":"spec"}', "&lt;header&gt;&lt;h1&gt;X&lt;/h1&gt;&lt;/header&gt;&lt;main&gt;&lt;section&gt;&lt;a href=\"javascript:x()\"&gt;X&lt;/a&gt;&lt;/section&gt;&lt;/main&gt;")],
418 + ["document.external-script", shell('{"id":"PX-SPEC-001","type":"spec"}', "&lt;header&gt;&lt;h1&gt;X&lt;/h1&gt;&lt;/header&gt;&lt;main&gt;&lt;section&gt;X&lt;/section&gt;&lt;/main&gt;&lt;script src=\"https://example.com/x.js\"&gt;&lt;/script&gt;")],
419 + ["document.active-api", shell('{"id":"PX-SPEC-001","type":"spec"}', "&lt;header&gt;&lt;h1&gt;X&lt;/h1&gt;&lt;/header&gt;&lt;main&gt;&lt;section&gt;X&lt;/section&gt;&lt;/main&gt;&lt;script&gt;fetch('https://example.com')&lt;/script&gt;")],
420 + ["document.css-resource", shell('{"id":"PX-SPEC-001","type":"spec"}', "&lt;header&gt;&lt;h1&gt;X&lt;/h1&gt;&lt;/header&gt;&lt;main&gt;&lt;section&gt;X&lt;/section&gt;&lt;/main&gt;&lt;style&gt;@import url('https://example.com/x.css');&lt;/style&gt;")],
421 + ["document.meta-refresh", shell('{"id":"PX-SPEC-001","type":"spec"}').replace("&lt;/head&gt;", '&lt;meta http-equiv="refresh" content="0; url=x"&gt;&lt;/head&gt;')],
422 + ])("reports %s", (code, html) =&gt; assert.ok(validateAuthoredHtml("doc.html", html).some((item) =&gt; item.code === code)));
424 + it("allows remote HTTPS navigation anchors", () =&gt; {
425 + const html = shell('{"id":"PX-SPEC-001","type":"spec"}', "&lt;header&gt;&lt;h1&gt;X&lt;/h1&gt;&lt;/header&gt;&lt;main&gt;&lt;section&gt;&lt;a href=\"https://example.com/reference\"&gt;Reference&lt;/a&gt;&lt;/section&gt;&lt;/main&gt;");
426 + assert.deepEqual(validateAuthoredHtml("doc.html", html), []);
427 + });
428 +});</code></pre>
429 +<ul class="checks">
430 +<li><strong>Step 2: run RED.</strong><br>Run: <code>mise run test -- extensions/the-system/__tests__/documents.test.ts</code><br>Expected: FAIL with missing metadata/HTML exports.</li>
431 +<li><strong>Step 3: implement duplicate-key detection and exact metadata.</strong> Append the following. Each schema branch checks every value instead of coercing it.</li>
432 +</ul>
433 +<pre><code>const duplicateTopLevelKeys = (source: string): string[] =&gt; {
434 + const keys: string[] = [];
435 + const duplicates = new Set&lt;string&gt;();
436 + let depth = 0;
437 + let index = 0;
438 + while (index &lt; source.length) {
439 + const character = source[index];
440 + if (character === "{") { depth += 1; index += 1; continue; }
441 + if (character === "}") { depth -= 1; index += 1; continue; }
442 + if (character !== '"') { index += 1; continue; }
443 + const start = index;
444 + index += 1;
445 + let escaped = false;
446 + while (index &lt; source.length) {
447 + const current = source[index++];
448 + if (!escaped &amp;&amp; current === '"') break;
449 + escaped = !escaped &amp;&amp; current === "\\";
450 + if (current !== "\\") escaped = false;
452 + if (depth !== 1) continue;
453 + let cursor = index;
454 + while (/\s/.test(source[cursor] ?? "")) cursor += 1;
455 + if (source[cursor] !== ":") continue;
456 + const key = JSON.parse(source.slice(start, index)) as string;
457 + if (keys.includes(key)) duplicates.add(key);
458 + keys.push(key);
460 + return [...duplicates].sort();
463 +const stringArray = (value: unknown, label: string): string[] =&gt; {
464 + if (!Array.isArray(value) || value.some((item) =&gt; typeof item !== "string")) throw new SystemDocumentError("metadata.value", `${label} must be a string array`);
465 + if (new Set(value).size !== value.length) throw new SystemDocumentError("metadata.duplicate", `${label} must contain unique values`);
466 + return value;
468 +const validDate = (value: unknown) =&gt; {
469 + if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
470 + const date = new Date(`${value}T00:00:00Z`);
471 + return !Number.isNaN(date.valueOf()) &amp;&amp; date.toISOString().slice(0, 10) === value;
473 +const httpsUrl = (value: string) =&gt; {
474 + try { return new URL(value).protocol === "https:"; } catch { return false; }
476 +const metadataScripts = (html: string) =&gt; [...html.matchAll(/&lt;script\b([^&gt;]*)&gt;([\s\S]*?)&lt;\/script\s*&gt;/gi)]
477 + .filter((match) =&gt; /\bid\s*=\s*(["'])system-meta\1/i.test(match[1]) &amp;&amp; /\btype\s*=\s*(["'])application\/json\1/i.test(match[1]));
479 +export function parseDocumentMetadata(html: string, prefix: string): DocumentMetadata {
480 + const blocks = metadataScripts(html);
481 + if (blocks.length !== 1) throw new SystemDocumentError("metadata.block", `Expected exactly one system-meta block; received ${blocks.length}`);
482 + const json = blocks[0][2].trim();
483 + const duplicates = duplicateTopLevelKeys(json);
484 + if (duplicates.length) throw new SystemDocumentError("metadata.duplicate-key", `Duplicate metadata keys: ${duplicates.join(", ")}`);
485 + let parsed: unknown;
486 + try { parsed = JSON.parse(json); } catch { throw new SystemDocumentError("metadata.invalid-json", "Invalid system metadata JSON"); }
487 + const value = objectValue(parsed, "Metadata");
488 + if (typeof value.id !== "string" || typeof value.type !== "string") throw new SystemDocumentError("metadata.identity", "Metadata requires string id and type");
489 + const ownId = parseDocumentId(value.id, prefix);
490 + if (ownId.type !== value.type) throw new SystemDocumentError("metadata.identity", `Metadata ID/type mismatch: ${value.id} / ${value.type}`);
491 + const reference = (key: string) =&gt; {
492 + if (typeof value[key] !== "string") throw new SystemDocumentError("metadata.value", `${key} must be a document ID`);
493 + parseDocumentId(value[key] as string, prefix);
494 + return value[key] as string;
495 + };
496 + switch (value.type) {
497 + case "spec":
498 + exactKeys(value, ["id", "type"]);
499 + return { id: value.id, type: "spec" };
500 + case "roadmap":
501 + exactKeys(value, ["id", "type", "spec"]);
502 + return { id: value.id, type: "roadmap", spec: reference("spec") };
503 + case "plan": {
504 + exactKeys(value, ["id", "type", "spec"], ["roadmap", "phase"]);
505 + const hasRoadmap = "roadmap" in value;
506 + const hasPhase = "phase" in value;
507 + if (hasRoadmap !== hasPhase || (hasPhase &amp;&amp; !positiveInteger(value.phase))) throw new SystemDocumentError("metadata.plan-phase", "Plan roadmap and positive phase must appear together");
508 + return hasRoadmap ? { id: value.id, type: "plan", spec: reference("spec"), roadmap: reference("roadmap"), phase: value.phase as number } : { id: value.id, type: "plan", spec: reference("spec") };
510 + case "issue": {
511 + exactKeys(value, ["id", "type", "status", "specs"]);
512 + if (value.status !== "open" &amp;&amp; value.status !== "fixed") throw new SystemDocumentError("metadata.status", "Issue status must be open or fixed");
513 + const specs = stringArray(value.specs, "specs");
514 + for (const id of specs) parseDocumentId(id, prefix);
515 + return { id: value.id, type: "issue", status: value.status, specs };
517 + case "research": {
518 + exactKeys(value, ["id", "type", "capturedAt"], ["sources"]);
519 + if (!validDate(value.capturedAt)) throw new SystemDocumentError("metadata.date", "capturedAt must be a valid ISO date");
520 + const sources = "sources" in value ? stringArray(value.sources, "sources") : undefined;
521 + if (sources?.some((source) =&gt; !httpsUrl(source))) throw new SystemDocumentError("metadata.source", "Research sources must use HTTPS");
522 + return sources ? { id: value.id, type: "research", capturedAt: value.capturedAt as string, sources } : { id: value.id, type: "research", capturedAt: value.capturedAt as string };
524 + default:
525 + throw new SystemDocumentError("metadata.type", `Unsupported metadata type: ${value.type}`);
527 +}</code></pre>
528 +<ul class="checks">
529 +<li><strong>Step 4: implement narrow HTML diagnostics.</strong> Append:</li>
530 +</ul>
531 +<pre><code>export type Diagnostic = Readonly&lt;{ code: string; path: string; message: string }&gt;;
532 +const diagnostic = (code: string, path: string, message: string): Diagnostic =&gt; ({ code, path, message });
533 +const count = (source: string, expression: RegExp) =&gt; [...source.matchAll(expression)].length;
535 +export function validateAuthoredHtml(filename: string, html: string): readonly Diagnostic[] {
536 + const findings: Diagnostic[] = [];
537 + const requireOne = (code: string, expression: RegExp, message: string) =&gt; {
538 + if (count(html, expression) !== 1) findings.push(diagnostic(code, filename, message));
539 + };
540 + if (!/^&lt;!doctype html&gt;/i.test(html.trimStart())) findings.push(diagnostic("document.doctype", filename, "Document must begin with HTML doctype"));
541 + requireOne("document.language", /&lt;html\b[^&gt;]*\blang\s*=\s*(["'])en\1[^&gt;]*&gt;/gi, "Document requires one html lang=en root");
542 + requireOne("document.charset", /&lt;meta\b[^&gt;]*\bcharset\s*=\s*(["'])?utf-8\1[^&gt;]*&gt;/gi, "Document requires one UTF-8 charset meta");
543 + requireOne("document.viewport", /&lt;meta\b[^&gt;]*\bname\s*=\s*(["'])viewport\1[^&gt;]*\bcontent\s*=\s*(["'])width=device-width,\s*initial-scale=1\2[^&gt;]*&gt;/gi, "Document requires one viewport meta");
544 + requireOne("document.title", /&lt;title&gt;\s*[^&lt;\s][^&lt;]*&lt;\/title&gt;/gi, "Document requires one nonempty title");
545 + requireOne("document.stylesheet", /&lt;link\b(?=[^&gt;]*\brel\s*=\s*(["'])stylesheet\1)(?=[^&gt;]*\bhref\s*=\s*(["'])\.\.\/system\.css\2)[^&gt;]*&gt;/gi, "Document requires exactly ../system.css");
546 + if (count(html, /&lt;link\b[^&gt;]*\brel\s*=\s*(["'])stylesheet\1[^&gt;]*&gt;/gi) !== 1) findings.push(diagnostic("document.stylesheet", filename, "Additional or missing stylesheets are forbidden"));
547 + for (const tag of ["header", "main", "section"] as const) requireOne("document.semantic-shell", new RegExp(`&lt;${tag}\\b`, "gi"), `Document requires one ${tag} element`);
548 + if (/&lt;\/?(?:iframe|object|embed)\b/i.test(html)) findings.push(diagnostic("document.forbidden-tag", filename, "iframe, object, and embed are forbidden"));
549 + if (/&lt;meta\b[^&gt;]*\bhttp-equiv\s*=\s*(["'])refresh\1/i.test(html)) findings.push(diagnostic("document.meta-refresh", filename, "Meta refresh is forbidden"));
550 + if (/\son[a-z]+\s*=/i.test(html)) findings.push(diagnostic("document.event-handler", filename, "Event-handler attributes are forbidden"));
551 + if (/\b(?:href|src|action|formaction|xlink:href)\s*=\s*(["'])\s*(?:javascript|vbscript|data):/i.test(html)) findings.push(diagnostic("document.executable-url", filename, "Executable URL schemes are forbidden"));
552 + if (/&lt;script\b[^&gt;]*\bsrc\s*=/i.test(html)) findings.push(diagnostic("document.external-script", filename, "External script sources are forbidden"));
553 + if (/&lt;(?:img|audio|video|source|track)\b[^&gt;]*\bsrc\s*=\s*(["'])https?:/i.test(html)) findings.push(diagnostic("document.remote-resource", filename, "Remote media resources are forbidden"));
554 + if (/(?:@import|url\s*\(\s*["']?\s*(?:https?:|data:))/i.test(html)) findings.push(diagnostic("document.css-resource", filename, "CSS imports and remote/data URLs are forbidden"));
555 + const executable = [...html.matchAll(/&lt;script\b([^&gt;]*)&gt;([\s\S]*?)&lt;\/script\s*&gt;/gi)]
556 + .filter((match) =&gt; !/\btype\s*=\s*(["'])application\/json\1/i.test(match[1]))
557 + .map((match) =&gt; match[2]).join("\n");
558 + if (/\b(?:fetch|XMLHttpRequest|WebSocket|EventSource|importScripts|localStorage|sessionStorage|indexedDB)\b/.test(executable) || /\bimport\s*\(/.test(executable)) findings.push(diagnostic("document.active-api", filename, "Network, import, and browser storage APIs are forbidden"));
559 + return findings.sort(compareDiagnostics);
562 +const compareDiagnostics = (left: Diagnostic, right: Diagnostic) =&gt;
563 + left.path.localeCompare(right.path) || left.code.localeCompare(right.code) || left.message.localeCompare(right.message);</code></pre>
564 +<ul class="checks">
565 +<li><strong>Step 5: run GREEN.</strong><br>Run: <code>mise run test -- extensions/the-system/__tests__/documents.test.ts</code><br>Expected: PASS; exact metadata schemas and every active-resource table row are green.</li>
566 +<li><strong>Step 6: checkpoint.</strong><br>Run: <code>git add extensions/the-system/documents.ts extensions/the-system/__tests__/documents.test.ts &amp;&amp; git commit -m "feat(the-system): validate authored document source"</code><br>Expected: one commit containing only metadata and HTML validation changes.</li>
567 +</ul>
568 +</section>
569 +<section>
570 +<h2>Task 5 · Document index and graph diagnostics</h2>
571 +<p>The index accepts already-read sources; later doctor code will own traversal and I/O. Invalid documents produce diagnostics and are excluded from graph edges. Duplicate IDs remain indexed as records but are not valid reference targets.</p>
572 +<ul class="checks">
573 +<li><strong>Step 1: append failing graph tests.</strong> Add <code>indexDocuments</code> to imports, then append:</li>
574 +</ul>
575 +<pre><code>const source = (folder: string, id: string, slug: string, metadata: string) =&gt; ({
576 + path: `/project/.system/${folder}/${id}-${slug}.html`, html: shell(metadata),
577 +});
579 +describe("document index", () =&gt; {
580 + it("indexes a valid complete graph without diagnostics", () =&gt; {
581 + const result = indexDocuments([
582 + source("specs", "PX-SPEC-001", "login", '{"id":"PX-SPEC-001","type":"spec"}'),
583 + source("roadmaps", "PX-ROADMAP-001", "login", '{"id":"PX-ROADMAP-001","type":"roadmap","spec":"PX-SPEC-001"}'),
584 + source("plans", "PX-PLAN-001", "login-phase-2", '{"id":"PX-PLAN-001","type":"plan","spec":"PX-SPEC-001","roadmap":"PX-ROADMAP-001","phase":2}'),
585 + source("issues", "PX-ISSUE-001", "login-error", '{"id":"PX-ISSUE-001","type":"issue","status":"open","specs":["PX-SPEC-001"]}'),
586 + source("research", "PX-RESEARCH-001", "login", '{"id":"PX-RESEARCH-001","type":"research","capturedAt":"2026-07-11"}'),
587 + ], "PX");
588 + assert.equal(result.documents.length, 5);
589 + assert.deepEqual(result.diagnostics, []);
590 + });
592 + it("sorts stable duplicate, filename, dangling, and forbidden-edge diagnostics", () =&gt; {
593 + const result = indexDocuments([
594 + source("specs", "PX-SPEC-001", "one", '{"id":"PX-SPEC-001","type":"spec"}'),
595 + source("specs", "PX-SPEC-002", "two", '{"id":"PX-SPEC-001","type":"spec"}'),
596 + source("roadmaps", "PX-ROADMAP-001", "wrong-target", '{"id":"PX-ROADMAP-001","type":"roadmap","spec":"PX-PLAN-009"}'),
597 + source("plans", "PX-PLAN-001", "dangling", '{"id":"PX-PLAN-001","type":"plan","spec":"PX-SPEC-404"}'),
598 + source("plans", "PX-PLAN-002", "crossed", '{"id":"PX-PLAN-002","type":"plan","spec":"PX-SPEC-001","roadmap":"PX-ROADMAP-002","phase":1}'),
599 + source("roadmaps", "PX-ROADMAP-002", "other", '{"id":"PX-ROADMAP-002","type":"roadmap","spec":"PX-SPEC-003"}'),
600 + source("issues", "PX-ISSUE-001", "unknown", '{"id":"PX-ISSUE-001","type":"issue","status":"open","specs":[]}'),
601 + ], "PX");
602 + assert.deepEqual(result.diagnostics.map(({ code }) =&gt; code), [...result.diagnostics].sort((a, b) =&gt; a.path.localeCompare(b.path) || a.code.localeCompare(b.code) || a.message.localeCompare(b.message)).map(({ code }) =&gt; code));
603 + assert.ok(result.diagnostics.some((item) =&gt; item.code === "graph.duplicate-id" &amp;&amp; item.message.includes("PX-SPEC-001")));
604 + assert.ok(result.diagnostics.some((item) =&gt; item.code === "document.filename"));
605 + assert.ok(result.diagnostics.some((item) =&gt; item.code === "graph.dangling-reference" &amp;&amp; item.message.includes("PX-SPEC-404")));
606 + assert.ok(result.diagnostics.some((item) =&gt; item.code === "graph.forbidden-edge" &amp;&amp; item.message.includes("must reference spec")));
607 + assert.ok(result.diagnostics.some((item) =&gt; item.code === "graph.forbidden-edge" &amp;&amp; item.message.includes("belongs to PX-SPEC-003")));
608 + assert.ok(!result.diagnostics.some((item) =&gt; item.path.includes("PX-ISSUE-001") &amp;&amp; item.code.startsWith("graph.")));
609 + });
610 +});</code></pre>
611 +<ul class="checks">
612 +<li><strong>Step 2: run RED.</strong><br>Run: <code>mise run test -- extensions/the-system/__tests__/documents.test.ts</code><br>Expected: FAIL because <code>indexDocuments</code> is not exported.</li>
613 +<li><strong>Step 3: append the deterministic index implementation.</strong></li>
614 +</ul>
615 +<pre><code>export type DocumentSource = Readonly&lt;{ path: string; html: string }&gt;;
616 +export type DocumentRecord = Readonly&lt;{ path: string; metadata: DocumentMetadata }&gt;;
617 +export type DocumentIndex = Readonly&lt;{ documents: readonly DocumentRecord[]; diagnostics: readonly Diagnostic[] }&gt;;
619 +const references = (metadata: DocumentMetadata): readonly [string, "spec" | "roadmap"][] =&gt; {
620 + switch (metadata.type) {
621 + case "roadmap": return [[metadata.spec, "spec"]];
622 + case "plan": return [[metadata.spec, "spec"], ...(metadata.roadmap ? [[metadata.roadmap, "roadmap"] as const] : [])];
623 + case "issue": return metadata.specs.map((id) =&gt; [id, "spec"] as const);
624 + default: return [];
628 +export function indexDocuments(sources: readonly DocumentSource[], prefix: string): DocumentIndex {
629 + const documents: DocumentRecord[] = [];
630 + const diagnostics: Diagnostic[] = [];
631 + for (const item of [...sources].sort((left, right) =&gt; left.path.localeCompare(right.path))) {
632 + diagnostics.push(...validateAuthoredHtml(item.path, item.html));
633 + try {
634 + const metadata = parseDocumentMetadata(item.html, prefix);
635 + try { validateFilename(item.path, metadata, prefix); }
636 + catch (error) { diagnostics.push(diagnostic("document.filename", item.path, (error as Error).message)); }
637 + documents.push({ path: item.path, metadata });
638 + } catch (error) {
639 + const value = error as SystemDocumentError;
640 + diagnostics.push(diagnostic("document.metadata", item.path, `${value.code}: ${value.message}`));
643 + const groups = new Map&lt;string, DocumentRecord[]&gt;();
644 + for (const document of documents) groups.set(document.metadata.id, [...(groups.get(document.metadata.id) ?? []), document]);
645 + for (const [id, records] of groups) {
646 + if (records.length &gt; 1) {
647 + const paths = records.map((record) =&gt; record.path).sort();
648 + for (const record of records) diagnostics.push(diagnostic("graph.duplicate-id", record.path, `Duplicate ID ${id}: ${paths.join(", ")}`));
651 + const unique = new Map([...groups].filter(([, records]) =&gt; records.length === 1).map(([id, records]) =&gt; [id, records[0]]));
652 + for (const document of documents) {
653 + for (const [targetId, expectedType] of references(document.metadata)) {
654 + const target = unique.get(targetId);
655 + if (!target) {
656 + diagnostics.push(diagnostic("graph.dangling-reference", document.path, `${document.metadata.id} references missing ${targetId}`));
657 + } else if (target.metadata.type !== expectedType) {
658 + diagnostics.push(diagnostic("graph.forbidden-edge", document.path, `${document.metadata.id} must reference ${expectedType}; ${targetId} is ${target.metadata.type}`));
661 + if (document.metadata.type === "plan" &amp;&amp; document.metadata.roadmap) {
662 + const roadmap = unique.get(document.metadata.roadmap);
663 + if (roadmap?.metadata.type === "roadmap" &amp;&amp; roadmap.metadata.spec !== document.metadata.spec) {
664 + diagnostics.push(diagnostic("graph.forbidden-edge", document.path, `${document.metadata.roadmap} belongs to ${roadmap.metadata.spec}, not ${document.metadata.spec}`));
668 + return { documents, diagnostics: diagnostics.sort(compareDiagnostics) };
669 +}</code></pre>
670 +<ul class="checks">
671 +<li><strong>Step 4: run GREEN.</strong><br>Run: <code>mise run test -- extensions/the-system/__tests__/documents.test.ts</code><br>Expected: PASS; valid graph is clean and all four required stable diagnostic classes are present.</li>
672 +<li><strong>Step 5: checkpoint.</strong><br>Run: <code>git add extensions/the-system/documents.ts extensions/the-system/__tests__/documents.test.ts &amp;&amp; git commit -m "feat(the-system): index document relationships"</code><br>Expected: one graph-only commit.</li>
673 +</ul>
674 +</section>
675 +<section>
676 +<h2>Task 6 · Approved Nugu styleVersion 1 asset</h2>
677 +<p>Derive the approved base literally from <code>docs/super/specs/2026-07-11-the-system-design-mockup-nugu-unified-dossier.html</code>, then add only missing shared semantic primitives. This avoids transcription drift in the exact light/dark tokens.</p>
678 +<ul class="checks">
679 +<li><strong>Step 1: append the failing CSS contract test.</strong> Add <code>readFileSync</code> from <code>node:fs</code> and append:</li>
680 +</ul>
681 +<pre><code>describe("bundled system.css", () =&gt; {
682 + it("contains exact Nugu tokens, version, components, and responsive contracts", () =&gt; {
683 + const css = readFileSync(path.resolve(import.meta.dirname, "../assets/system.css"), "utf8");
684 + for (const token of [
685 + "The System styleVersion: 1", "--fg: #121212", "--page: #ededed", "--panel: #dbdbdb",
686 + "--accent: #ae2eae", "--ui-accent: #922792", "--minor: #3b3b3b", "--focus: #184e5b",
687 + "--important: #4f3c69", "--error: #bd172e", "--warning: #6e6c10", "--info: #116477",
688 + "--fg: #ededed", "--page: #121212", "--panel: #242424", "--accent: #d151d1",
689 + "--ui-accent: #d86dd8", "--minor: #8b8b8b", "--focus: #7ba1aa", "--important: #dfd3f3",
690 + "--error: #ec6376", "--warning: #f0ee69", "--info: #3ec5e3",
691 + ".doc", ".mast", ".grid", ".section", ".contract", ".callout", ".flow", ".metadata",
692 + ".status", ".document-nav", "table", "pre", "overflow-wrap: anywhere", "@media (max-width: 560px)",
693 + ]) assert.ok(css.includes(token), `missing CSS contract: ${token}`);
694 + assert.doesNotMatch(css, /@import|url\s*\(|https?:\/\//i);
695 + });
696 +});</code></pre>
697 +<ul class="checks">
698 +<li><strong>Step 2: run RED.</strong><br>Run: <code>mise run test -- extensions/the-system/__tests__/documents.test.ts</code><br>Expected: FAIL with <code>ENOENT</code> for <code>extensions/the-system/assets/system.css</code>.</li>
699 +<li><strong>Step 3: copy the accepted style block exactly and version it.</strong><br>Run:</li>
700 +</ul>
701 +<pre><code>node --input-type=module -e "import{readFileSync,writeFileSync,mkdirSync}from'node:fs';const source=readFileSync('docs/super/specs/2026-07-11-the-system-design-mockup-nugu-unified-dossier.html','utf8');const css=source.match(/&lt;style&gt;([\s\S]*?)&lt;\/style&gt;/)[1].trim();mkdirSync('extensions/the-system/assets',{recursive:true});writeFileSync('extensions/the-system/assets/system.css','/* The System styleVersion: 1 */\n'+css+'\n','utf8');"</code></pre>
702 +<p>Expected: <code>assets/system.css</code> contains the mockup's exact palette and dossier styles, with no HTML.</p>
703 +<ul class="checks">
704 +<li><strong>Step 4: append the missing shared primitives exactly.</strong> Append to <code>extensions/the-system/assets/system.css</code>:</li>
705 +</ul>
706 +<pre><code>
707 +/* Shared authored-document primitives. */
708 +a { color: var(--focus); font-weight: 800; overflow-wrap: anywhere; }
709 +.document-nav { display: flex; flex-wrap: wrap; gap: .5rem; padding: .8rem; border-bottom: 2px solid var(--fg); }
710 +.metadata { display: grid; grid-template-columns: repeat(auto-fit, minmax(9rem, 1fr)); gap: .5rem; margin: 0; padding: .8rem; background: var(--panel); border: 2px solid var(--fg); }
711 +.metadata dt { color: var(--accent); font-size: .7rem; font-weight: 900; letter-spacing: .12em; text-transform: uppercase; }
712 +.metadata dd { margin: .2rem 0 0; overflow-wrap: anywhere; }
713 +.callout { padding: .75rem; border: 2px solid var(--fg); border-left: 7px solid var(--info); background: var(--panel); }
714 +.callout.important { border-left-color: var(--important); }
715 +.callout.warning { border-left-color: var(--warning); }
716 +.callout.error { border-left-color: var(--error); }
717 +.status { display: inline-block; padding: .15rem .45rem; border: 2px solid currentColor; color: var(--info); font-size: .7rem; font-weight: 900; text-transform: uppercase; }
718 +.status.open, .status.error { color: var(--error); }
719 +.status.fixed { color: var(--focus); }
720 +table { width: 100%; border-collapse: collapse; }
721 +th, td { padding: .6rem; border: 2px solid var(--fg); text-align: left; vertical-align: top; overflow-wrap: anywhere; }
722 +th { background: var(--panel); }
723 +pre, code { background: var(--panel); }
724 +code { padding: .1rem .3rem; overflow-wrap: anywhere; }
725 +pre { max-width: 100%; padding: .8rem; overflow: auto; border-left: 7px solid var(--ui-accent); }
726 +pre code { padding: 0; }
727 +figure { max-width: 100%; margin: 1rem 0; overflow: auto; }
728 +details { border: 2px solid var(--fg); padding: .65rem; }
729 +summary { min-height: 2.75rem; cursor: pointer; font-weight: 900; }
730 +@media (max-width: 560px) {
731 + .document-nav a { min-height: 2.75rem; display: inline-flex; align-items: center; }
732 + table, tbody, tr, th, td { display: block; width: 100%; }
733 + th { border-bottom: 0; }
734 + .metadata { grid-template-columns: 1fr; }
735 +}</code></pre>
736 +<ul class="checks">
737 +<li><strong>Step 5: run GREEN.</strong><br>Run: <code>mise run test -- extensions/the-system/__tests__/documents.test.ts</code><br>Expected: PASS; all exact light/dark tokens, primitives, responsiveness, and no-resource assertions pass.</li>
738 +<li><strong>Step 6: checkpoint.</strong><br>Run: <code>git add extensions/the-system/assets/system.css extensions/the-system/__tests__/documents.test.ts &amp;&amp; git commit -m "feat(the-system): add Nugu system stylesheet"</code><br>Expected: one asset/test commit.</li>
739 +</ul>
740 +</section>
741 +<section>
742 +<h2>Task 7 · Typecheck exposure and independent-green release gate</h2>
743 +<ul class="checks">
744 +<li><strong>Step 1: expose only the new module to root typecheck.</strong> In <code>tsconfig.json</code>, replace:</li>
745 +</ul>
746 +<pre><code>"extensions/the-system"</code></pre>
747 +<p>with:</p>
748 +<pre><code>"extensions/the-system/index.ts",
749 +"extensions/the-system/mockup.ts"</code></pre>
750 +<p>This retains the Phase 1 exclusion for unchanged runtime code while allowing the include glob to typecheck <code>documents.ts</code>.</p>
751 +<ul class="checks">
752 +<li><strong>Step 2: run the focused suite.</strong><br>Run: <code>mise run test -- extensions/the-system/__tests__/documents.test.ts</code><br>Expected: PASS with root, containment, schema, IDs, metadata, HTML, graph, and CSS contracts.</li>
753 +<li><strong>Step 3: run all renamed-extension regressions.</strong><br>Run: <code>mise run test -- extensions/the-system/__tests__</code><br>Expected: PASS, including existing task, mockup, harness, and workflow-skill tests.</li>
754 +<li><strong>Step 4: typecheck through the repository script.</strong><br>Run: <code>npm run typecheck</code><br>Expected: exit 0 with no TypeScript diagnostics; <code>documents.ts</code> is included while <code>index.ts</code> and <code>mockup.ts</code> remain excluded.</li>
755 +<li><strong>Step 5: format only through the declared task.</strong><br>Run: <code>mise run fmt</code><br>Expected: Biome and dprint complete successfully; inspect formatting changes and revert any unrelated dirty-file edits before proceeding.</li>
756 +<li><strong>Step 6: rerun focused tests after formatting.</strong><br>Run: <code>mise run test -- extensions/the-system/__tests__/documents.test.ts</code><br>Expected: PASS.</li>
757 +<li><strong>Step 7: run static/package checks.</strong><br>Run: <code>mise run check</code><br>Expected: exit 0, including <code>OK static-check tests</code>; the dormant files require no package resource registration.</li>
758 +<li><strong>Step 8: run the full independent-green gate.</strong><br>Run: <code>mise run ci</code><br>Expected: lint, all tests, skill checks, static checks, and extension checks pass.</li>
759 +<li><strong>Step 9: verify the phase boundary and dirty-work preservation.</strong><br>Run: <code>git status --short &amp;&amp; git diff -- extensions/the-system/index.ts extensions/the-system/mockup.ts extensions/the-system/package.json package.json package-lock.json</code><br>Expected: no diff for runtime entrypoints or manifests; only the four planned paths differ from the Phase 1 baseline, plus unchanged pre-existing dirty work.</li>
760 +<li><strong>Step 10: final checkpoint.</strong><br>Run: <code>git add extensions/the-system/documents.ts extensions/the-system/__tests__/documents.test.ts extensions/the-system/assets/system.css tsconfig.json &amp;&amp; git commit -m "test(the-system): complete document kernel phase"</code><br>Expected: commit succeeds if verification formatting changed tracked Phase 2 files; if nothing remains staged, skip this empty checkpoint rather than changing content.</li>
761 +</ul>
762 +</section>
763 +<section>
764 +<h2>Acceptance matrix</h2>
765 +<table>
766 +<tr><th>Phase 2 contract</th><th>Proof</th></tr>
767 +<tr><td>Simple Git directory, Git worktree file, JJ, colocated markers, conflict, and no VCS.</td><td><code>project root</code> table and conflict test.</td></tr>
768 +<tr><td>Normalized governed containment rejects traversal, absolute escape, and sibling-prefix confusion.</td><td><code>governed path containment</code> tests.</td></tr>
769 +<tr><td>Strict config, prefix, IDs, independent type sequences, growth past 999, slug, filename, and type directory.</td><td><code>system config</code> and <code>document IDs and filenames</code> tables.</td></tr>
770 +<tr><td>Exactly one metadata block; exact keys and values for all five authored types.</td><td><code>document metadata</code> table and rejection cases.</td></tr>
771 +<tr><td>Duplicate IDs, filename mismatch, dangling references, wrong target types, and cross-spec roadmap plans.</td><td><code>document index</code> diagnostics test.</td></tr>
772 +<tr><td>Complete shell, semantic source, exact stylesheet, allowed HTTPS anchors, and obvious active-resource rejection without execution.</td><td><code>authored HTML</code> table; validator uses string inspection only.</td></tr>
773 +<tr><td>Approved versioned Nugu palette and responsive brutal components.</td><td><code>bundled system.css</code> exact-token test.</td></tr>
774 +<tr><td>Dormant, dependency-free, no mutation, no runtime behavior.</td><td>No <code>index.ts</code> import or package change; kernel has only <code>existsSync</code> observation and pure transforms.</td></tr>
775 +<tr><td>Independent green phase.</td><td>Focused tests, renamed regressions, typecheck, static checks, and <code>mise run ci</code>.</td></tr>
776 +</table>
777 +<div class="contract red"><strong>Stop here.</strong> Phase 3 owns doctor filesystem traversal, read-only reporting, skills, prompts, package prompt resources, and runtime reachability. Do not begin any of those changes in this plan.</div>
778 +</section>
779 +<section>
780 +<h2>Plan self-review</h2>
781 +<ul>
782 +<li>Coverage: every Phase 2 roadmap bullet maps to Tasks 2–6; Task 7 proves the phase is independently green.</li>
783 +<li>Scope: runtime hooks and filesystem mutation are absent; later lifecycle work is explicitly excluded.</li>
784 +<li>Consistency: all tests import the public surface listed in the file map; metadata and graph property names are identical across tasks.</li>
785 +<li>Buildability: each code change has an exact path, insertion point, RED command, expected failure, minimal implementation, GREEN command, and checkpoint.</li>
786 +<li>Placeholder scan: no deferred implementation markers or unspecified validation/error-handling steps remain.</li>
787 +<li>Historical path: this plan intentionally remains under approved transitional <code>docs/super/plans/**</code>.</li>
788 +</ul>
789 +<p><strong>Execution handoff:</strong> execute with <code>/skill:executing-plans</code>. This plan intentionally stops at Phase 2: Project and document kernel; every later roadmap phase requires a separate detailed plan.</p>
790 +</section>
791 +</main>
792 +</article>
793 +</body>
794 +</html>