repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs(the-system): plan rich markdown bundle kernel

61e5f887221d4c989d2ee41e19e53d960ef21a34

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

docs/super/plans/2026-07-15-the-system-phase-6-rich-markdown-bundle-kernel.md

Added
new file mode 100644
1 +# The System Phase 6 Rich Markdown Bundle Kernel Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Replace authored-HTML document assumptions with validated rich Markdown bundles across the kernel, doctor, initialization, and runtime governance.
7 +**Architecture:** Add one shared rich-Markdown parser in `markdown.ts`, then make `documents.ts` project known graph metadata from source-ordered YAML frontmatter and discover `<ID>-<slug>/index.md` bundles. Migrate doctor, initialization, and runtime governance to those shared routes before deleting the HTML validator and project stylesheet. Phase 7 will reuse the parser for rendering; this phase does not render or open documents.
9 +**Tech Stack:** Node.js filesystem/path APIs, TypeScript, unified 11, remark parser extensions, YAML 2, Vitest, Pi extension lifecycle hooks, mise.
11 +**Roadmap:** [`docs/super/roadmaps/2026-07-11-the-system-roadmap.html`](../roadmaps/2026-07-11-the-system-roadmap.html)
13 +**Design Spec:** [`docs/super/specs/2026-07-15-the-system-rich-markdown-design.md`](../specs/2026-07-15-the-system-rich-markdown-design.md)
15 +**Phase:** Phase 6: Rich Markdown bundle kernel migration
17 +---
19 +## Preconditions And Boundaries
21 +The working tree contains unrelated concurrent work.
23 +Before every edit and commit, run `git status --short` and preserve every unrelated path.
25 +`package-lock.json` is a planned file, but it is currently dirty from unrelated work.
27 +If that unrelated lockfile diff still exists when execution starts, stop and ask the human to land or isolate it before Task 1; never stage the complete mixed lockfile.
29 +Phase 6 intentionally excludes:
31 +- HTML rendering;
32 +- Nugu renderer CSS;
33 +- `/system-view` and `/system-book`;
34 +- full-text search;
35 +- browser opening;
36 +- brainstorming/spec workflow migration;
37 +- roadmap, plan, implementation, and issue workflow migration.
39 +The final Phase 6 tree must contain no authored-HTML validator, no project stylesheet asset, and no compatibility alias for flat HTML documents.
41 +## Planned File Structure
43 +- Create `extensions/the-system/markdown.ts`: one reusable rich-Markdown parser and source-ordered YAML frontmatter converter.
44 +- Create `extensions/the-system/__tests__/markdown.test.ts`: parser profile and frontmatter-model tests.
45 +- Modify `extensions/the-system/documents.ts`: schema v2 config, bundle paths, shared bundle discovery, metadata projection, graph indexing, and candidate validation.
46 +- Modify `extensions/the-system/__tests__/documents.test.ts`: replace HTML/path/CSS tests with bundle, discovery, metadata, graph, and candidate tests.
47 +- Modify `extensions/the-system/doctor.ts`: use shared bundle discovery and remove stylesheet/mockup filename logic.
48 +- Modify `extensions/the-system/__tests__/doctor.test.ts`: bundle fixtures, obsolete CSS diagnostics, and no-mutation proof.
49 +- Modify `extensions/the-system/init.ts`: config-only machine state, narrow v1 upgrade reader, and approved obsolete-CSS removal.
50 +- Modify `extensions/the-system/scripts/init.mjs`: distinguish written and removed paths.
51 +- Modify `extensions/the-system/__tests__/init.test.ts`: schema v2 creation, idempotence, pending migration, approved removal, and unsafe paths.
52 +- Modify `extensions/the-system/system.ts`: bundle-aware candidate validation, spec-file ownership, and shell advisory matching.
53 +- Modify `extensions/the-system/__tests__/system.test.ts`: bundle index/assets, ownership, invalid locations, symlinks, and every document type.
54 +- Modify `extensions/the-system/skills/system-documents/SKILL.md`: replace HTML authority with the rich Markdown bundle contract.
55 +- Modify `extensions/the-system/skills/the-system-init/SKILL.md`: config-only machine ownership and bundle topology.
56 +- Modify `extensions/the-system/__tests__/workflow-skills.test.ts`: exact new skill contracts.
57 +- Modify `extensions/the-system/package.json`: runtime parser dependencies.
58 +- Modify `package-lock.json`: generated workspace dependency graph, only after the lockfile precondition is clean.
59 +- Delete `extensions/the-system/assets/system.css`: obsolete project-local stylesheet template.
60 +- Modify `extensions/the-system/README.md`: current bundle structure, doctor, initialization, and governance behavior only.
61 +- Modify `extensions/the-system/CHANGELOG.md`: Phase 6 migration entry.
63 +### Task 1: Add The Shared Rich Markdown Parser
65 +**Files:**
67 +- Create: `extensions/the-system/markdown.ts`
68 +- Create: `extensions/the-system/__tests__/markdown.test.ts`
69 +- Modify: `extensions/the-system/package.json`
70 +- Modify: `package-lock.json`
72 +- [ ] **Step 1: Verify the lockfile precondition**
74 +Run:
76 +```bash
77 +git status --short
78 +git diff -- package-lock.json
79 +```
81 +Expected: `package-lock.json` has no unrelated diff.
83 +If it does, stop and report the lockfile blocker.
85 +- [ ] **Step 2: Declare the parser dependencies**
87 +Add this runtime dependency block to `extensions/the-system/package.json` before `peerDependencies`, and add `"@types/mdast": "^4.0.4"` to `devDependencies`:
89 +```json
90 +"dependencies": {
91 + "remark-definition-list": "^2.0.0",
92 + "remark-frontmatter": "^5.0.0",
93 + "remark-gfm": "^4.0.1",
94 + "remark-github-blockquote-alert": "^2.1.0",
95 + "remark-math": "^6.0.0",
96 + "remark-parse": "^11.0.0",
97 + "unified": "^11.0.5",
98 + "yaml": "^2.9.0"
99 +},
100 +```
102 +Regenerate the lock through the repository task:
104 +```bash
105 +mise run lock
106 +```
108 +Expected: the lock records these dependencies under `extensions/the-system` and changes no unrelated package definitions.
110 +- [ ] **Step 3: Write failing parser-profile tests**
112 +Create `extensions/the-system/__tests__/markdown.test.ts` with this starting content:
114 +```typescript
115 +import assert from "node:assert/strict";
116 +import { describe, it } from "vitest";
117 +import { MarkdownDocumentError, parseRichMarkdown } from "../markdown.ts";
119 +const rich = `---
120 +id: PX-SPEC-001
121 +type: spec
122 +title: Rich documents
123 +owners: [human, the-system]
124 +review:
125 + approved: 2026-07-15
126 + flags: [visual, editable]
127 +---
129 +# Rich documents
131 +> [!IMPORTANT]
132 +> Canonical source remains editable.
134 +Term
135 +: Definition
137 +| A | B |
138 +| - | - |
139 +| 1 | 2 |
141 +Inline $E = mc^2$.
143 +\`\`\`mermaid
144 +graph LR
145 + A --> B
146 +\`\`\`
148 +<span data-example="raw">raw HTML</span>
151 +describe("rich Markdown parsing", () => {
152 + it("parses the complete profile and preserves frontmatter order", () => {
153 + const result = parseRichMarkdown(rich);
154 + assert.deepEqual([...result.frontmatter.keys()], [
155 + "id",
156 + "type",
157 + "title",
158 + "owners",
159 + "review",
160 + ]);
161 + assert.deepEqual(
162 + result.frontmatter.get("review"),
163 + new Map([
164 + ["approved", "2026-07-15"],
165 + ["flags", ["visual", "editable"]],
166 + ]),
167 + );
168 + const tree = JSON.stringify(result.tree);
169 + for (
170 + const nodeType of [
171 + "\"type\":\"table\"",
172 + "\"type\":\"definitionList\"",
173 + "\"type\":\"math\"",
174 + "\"lang\":\"mermaid\"",
175 + "\"type\":\"html\"",
177 + ) assert.ok(tree.includes(nodeType), nodeType);
178 + });
180 + it.each([
181 + ["missing", "# No frontmatter", "frontmatter.missing"],
182 + ["duplicate", "---\nid: A\nid: B\n---\n", "frontmatter.invalid"],
183 + ["alias", "---\na: &a [1]\nb: *a\n---\n", "frontmatter.unsupported"],
184 + ])("rejects %s frontmatter", (_name, source, code) => {
185 + assert.throws(
186 + () => parseRichMarkdown(source),
187 + (error: unknown) =>
188 + error instanceof MarkdownDocumentError && error.code === code,
189 + );
190 + });
191 +});
192 +```
194 +- [ ] **Step 4: Run the parser tests to verify RED**
196 +Run:
198 +```bash
199 +mise run test -- extensions/the-system/__tests__/markdown.test.ts
200 +```
202 +Expected: FAIL because `markdown.ts` does not exist.
204 +- [ ] **Step 5: Implement the shared parser**
206 +Create `extensions/the-system/markdown.ts` around this public contract:
208 +```typescript
209 +import type { Root } from "mdast";
210 +import { remarkDefinitionList } from "remark-definition-list";
211 +import remarkFrontmatter from "remark-frontmatter";
212 +import remarkGfm from "remark-gfm";
213 +import remarkGithubAlert from "remark-github-blockquote-alert";
214 +import remarkMath from "remark-math";
215 +import remarkParse from "remark-parse";
216 +import { unified } from "unified";
217 +import {
218 + Alias,
219 + isMap,
220 + isScalar,
221 + isSeq,
222 + type Node,
223 + type Pair,
224 + parseDocument,
225 +} from "yaml";
227 +export type FrontmatterValue =
228 + | null
229 + | boolean
230 + | number
231 + | string
232 + | readonly FrontmatterValue[]
233 + | FrontmatterMap;
234 +export type FrontmatterMap = ReadonlyMap<string, FrontmatterValue>;
235 +export type RichMarkdownDocument = Readonly<{
236 + tree: Root;
237 + frontmatter: FrontmatterMap;
238 +}>;
240 +export class MarkdownDocumentError extends Error {
241 + constructor(readonly code: string, message: string) {
242 + super(message);
243 + this.name = "MarkdownDocumentError";
247 +export const createMarkdownParser = () =>
248 + unified()
249 + .use(remarkParse)
250 + .use(remarkFrontmatter, ["yaml"])
251 + .use(remarkGfm)
252 + .use(remarkDefinitionList)
253 + .use(remarkMath)
254 + .use(remarkGithubAlert);
256 +export function parseRichMarkdown(source: string): RichMarkdownDocument {
257 + const parser = createMarkdownParser();
258 + const tree = parser.runSync(parser.parse(source)) as Root;
259 + const blocks = tree.children.filter((node) => node.type === "yaml");
260 + if (blocks.length === 0) {
261 + throw new MarkdownDocumentError(
262 + "frontmatter.missing",
263 + "Document requires one leading YAML frontmatter block",
264 + );
266 + if (blocks.length !== 1) {
267 + throw new MarkdownDocumentError(
268 + "frontmatter.multiple",
269 + `Document requires one YAML frontmatter block; received ${blocks.length}`,
270 + );
272 + const document = parseDocument(blocks[0]!.value, {
273 + schema: "core",
274 + strict: true,
275 + uniqueKeys: true,
276 + });
277 + if (document.errors.length > 0) {
278 + throw new MarkdownDocumentError(
279 + "frontmatter.invalid",
280 + document.errors.map((error) => error.message).join("; "),
281 + );
283 + if (!isMap(document.contents)) {
284 + throw new MarkdownDocumentError(
285 + "frontmatter.shape",
286 + "Frontmatter must be a YAML map",
287 + );
289 + return { tree, frontmatter: convertMap(document.contents.items) };
291 +```
293 +Use these converters in the same file:
295 +```typescript
296 +const unsupported = (message: string): never => {
297 + throw new MarkdownDocumentError("frontmatter.unsupported", message);
300 +const convertNode = (node: Node | null): FrontmatterValue => {
301 + if (node === null) return null;
302 + if (node instanceof Alias) {
303 + return unsupported("YAML aliases are not frontmatter values");
305 + if (isScalar(node)) {
306 + const value = node.value;
307 + if (
308 + value === null
309 + || typeof value === "boolean"
310 + || typeof value === "string"
311 + ) return value;
312 + if (typeof value === "number" && Number.isFinite(value)) return value;
313 + return unsupported(`Unsupported YAML scalar: ${String(value)}`);
315 + if (isSeq(node)) return node.items.map((item) => convertNode(item));
316 + if (isMap(node)) return convertMap(node.items);
317 + return unsupported(`Unsupported YAML node: ${node.constructor.name}`);
320 +const convertMap = (
321 + items: readonly Pair[],
322 +): FrontmatterMap => {
323 + const result = new Map<string, FrontmatterValue>();
324 + for (const pair of items) {
325 + if (!isScalar(pair.key) || typeof pair.key.value !== "string") {
326 + unsupported("Frontmatter map keys must be strings");
328 + result.set(pair.key.value, convertNode(pair.value as Node | null));
330 + return result;
332 +```
334 +The core YAML schema leaves dates as strings.
336 +Do not render, sanitize, or rewrite links in this file.
338 +- [ ] **Step 6: Run focused and type checks**
340 +Run:
342 +```bash
343 +mise run test -- extensions/the-system/__tests__/markdown.test.ts
344 +mise run check
345 +```
347 +Expected: parser tests PASS and typecheck/static checks PASS.
349 +- [ ] **Step 7: Commit the parser slice**
351 +```bash
352 +git add extensions/the-system/markdown.ts \
353 + extensions/the-system/__tests__/markdown.test.ts \
354 + extensions/the-system/package.json package-lock.json
355 +git commit -m "feat(the-system): add rich markdown parser"
356 +```
358 +Expected: only those four planned paths are staged.
360 +### Task 2: Add Bundle Paths, Discovery, And YAML Graph Projection
362 +**Files:**
364 +- Modify: `extensions/the-system/documents.ts`
365 +- Modify: `extensions/the-system/__tests__/documents.test.ts`
367 +This task adds the bundle route while the old HTML exports remain only until Task 4 migrates their final runtime caller.
369 +Do not add an alias from HTML paths to bundle paths.
371 +- [ ] **Step 1: Add failing bundle and metadata tests**
373 +Add fixtures shaped like:
375 +```typescript
376 +const markdownSource = (
377 + directory: string,
378 + id: string,
379 + slug: string,
380 + frontmatter: string,
381 +) => ({
382 + path: `.system/${directory}/${id}-${slug}/index.md`,
383 + markdown: `---\n${frontmatter}\n---\n\n# ${id}\n`,
384 +});
385 +```
387 +Add tests proving:
389 +```typescript
390 +const parsed = parseAuthoredDocument(
391 + `---
392 +id: PX-PLAN-001
393 +type: plan
394 +spec: PX-SPEC-001
395 +roadmap: PX-ROADMAP-001
396 +phase: 2
397 +title: Delivery
398 +review:
399 + owner: human
400 +---
402 +# Delivery
404 + "PX",
406 +assert.deepEqual(parsed.metadata, {
407 + id: "PX-PLAN-001",
408 + type: "plan",
409 + spec: "PX-SPEC-001",
410 + roadmap: "PX-ROADMAP-001",
411 + phase: 2,
412 +});
413 +assert.deepEqual([...parsed.frontmatter.keys()], [
414 + "id",
415 + "type",
416 + "spec",
417 + "roadmap",
418 + "phase",
419 + "title",
420 + "review",
421 +]);
422 +```
424 +Also prove:
426 +- unknown frontmatter keys survive but do not create graph edges;
427 +- known `id`, `type`, references, issue status/specs, research date/sources, and plan phase contracts retain current semantics;
428 +- research `sources` accepts arbitrary strings instead of HTTPS-only values;
429 +- `validateDocumentPath` accepts only `.system/<matching-type>/<ID>-<slug>/index.md`;
430 +- flat HTML, wrong type directories, uppercase/bad slugs, nested `other/index.md`, and mismatched IDs fail;
431 +- graph indexing and candidate replacement retain stable duplicate, dangling, forbidden-edge, and crossed-roadmap diagnostics using `markdown` sources.
433 +- [ ] **Step 2: Add failing filesystem discovery tests**
435 +Use the existing temp-tree helpers to prove `discoverDocumentBundles(root)`:
437 +- reads direct bundle `index.md` files in stable path order;
438 +- permits arbitrary regular assets and nested regular asset directories;
439 +- reports a direct file under a typed directory as `bundle.expected-directory`;
440 +- reports a bundle without `index.md` as `bundle.missing-index`;
441 +- reports symlinked bundles, indexes, nested directories, and assets as `bundle.symbolic-link`;
442 +- never follows a symlink;
443 +- returns authored sources separately from structural diagnostics.
445 +Representative assertion:
447 +```typescript
448 +assert.deepEqual(discovery.sources, [{
449 + path: ".system/specs/PX-SPEC-001-contract/index.md",
450 + markdown: specMarkdown("PX-SPEC-001"),
451 +}]);
452 +assert.deepEqual(
453 + discovery.diagnostics.map(({ code, path }) => `${path} ${code}`),
455 + ".system/plans/loose.md bundle.expected-directory",
456 + ".system/specs/PX-SPEC-002-empty bundle.missing-index",
457 + ],
459 +```
461 +- [ ] **Step 3: Run the document tests to verify RED**
463 +```bash
464 +mise run test -- extensions/the-system/__tests__/documents.test.ts
465 +```
467 +Expected: FAIL because bundle APIs do not exist.
469 +- [ ] **Step 4: Add the bundle API to `documents.ts`**
471 +Add these contracts:
473 +```typescript
474 +export type AuthoredDocument = Readonly<{
475 + metadata: DocumentMetadata;
476 + frontmatter: FrontmatterMap;
477 +}>;
478 +export type BundleDocumentSource = Readonly<{
479 + path: string;
480 + markdown: string;
481 +}>;
482 +export type BundleDocumentRecord = Readonly<{
483 + path: string;
484 + metadata: DocumentMetadata;
485 + frontmatter: FrontmatterMap;
486 +}>;
487 +export type BundleDocumentIndex = Readonly<{
488 + documents: readonly BundleDocumentRecord[];
489 + diagnostics: readonly Diagnostic[];
490 +}>;
491 +export type BundleDiscovery = Readonly<{
492 + sources: readonly BundleDocumentSource[];
493 + diagnostics: readonly Diagnostic[];
494 +}>;
496 +export function parseAuthoredDocument(
497 + source: string,
498 + prefix: string,
499 +): AuthoredDocument;
500 +export function validateDocumentPath(
501 + documentPath: string,
502 + metadata: DocumentMetadata,
503 + prefix: string,
504 +): void;
505 +export function discoverDocumentBundles(root: string): BundleDiscovery;
506 +export function indexBundleDocuments(
507 + sources: readonly BundleDocumentSource[],
508 + prefix: string,
509 +): BundleDocumentIndex;
510 +export function validateBundleCandidate(
511 + current: readonly BundleDocumentSource[],
512 + candidate: BundleDocumentSource,
513 + prefix: string,
514 +): readonly Diagnostic[];
515 +```
517 +Project known graph metadata with these helpers:
519 +```typescript
520 +const requiredStringField = (
521 + fields: FrontmatterMap,
522 + key: string,
523 +): string => {
524 + const value = fields.get(key);
525 + if (typeof value !== "string") {
526 + throw new SystemDocumentError(
527 + "metadata.value",
528 + `${key} must be a string`,
529 + );
531 + return value;
534 +const optionalUniqueStrings = (
535 + fields: FrontmatterMap,
536 + key: string,
537 +): readonly string[] | undefined => {
538 + const value = fields.get(key);
539 + if (value === undefined) return undefined;
540 + if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
541 + throw new SystemDocumentError(
542 + "metadata.value",
543 + `${key} must be a string array`,
544 + );
546 + if (new Set(value).size !== value.length) {
547 + throw new SystemDocumentError(
548 + "metadata.duplicate",
549 + `${key} must contain unique values`,
550 + );
552 + return value;
555 +const projectMetadata = (
556 + fields: FrontmatterMap,
557 + prefix: string,
558 +): DocumentMetadata => {
559 + const id = requiredStringField(fields, "id");
560 + const type = requiredStringField(fields, "type");
561 + const own = parseDocumentId(id, prefix);
562 + if (own.type !== type) {
563 + throw new SystemDocumentError(
564 + "metadata.identity",
565 + `Metadata ID/type mismatch: ${id} / ${type}`,
566 + );
568 + const reference = (key: string) => {
569 + const value = requiredStringField(fields, key);
570 + parseDocumentId(value, prefix);
571 + return value;
572 + };
573 + switch (type) {
574 + case "spec":
575 + return { id, type };
576 + case "roadmap":
577 + return { id, type, spec: reference("spec") };
578 + case "plan": {
579 + const roadmap = fields.get("roadmap");
580 + const phase = fields.get("phase");
581 + if ((roadmap === undefined) !== (phase === undefined)) {
582 + throw new SystemDocumentError(
583 + "metadata.plan-phase",
584 + "Plan roadmap and positive phase must appear together",
585 + );
587 + if (roadmap === undefined) return { id, type, spec: reference("spec") };
588 + if (typeof roadmap !== "string" || !positiveInteger(phase)) {
589 + throw new SystemDocumentError(
590 + "metadata.plan-phase",
591 + "Plan roadmap and positive phase must appear together",
592 + );
594 + parseDocumentId(roadmap, prefix);
595 + return {
596 + id,
597 + type,
598 + spec: reference("spec"),
599 + roadmap,
600 + phase: phase as number,
601 + };
603 + case "issue": {
604 + const status = requiredStringField(fields, "status");
605 + if (status !== "open" && status !== "fixed") {
606 + throw new SystemDocumentError(
607 + "metadata.status",
608 + "Issue status must be open or fixed",
609 + );
611 + const specs = optionalUniqueStrings(fields, "specs");
612 + if (!specs) {
613 + throw new SystemDocumentError(
614 + "metadata.value",
615 + "specs must be a string array",
616 + );
618 + for (const spec of specs) parseDocumentId(spec, prefix);
619 + return { id, type, status, specs };
621 + case "research": {
622 + const capturedAt = requiredStringField(fields, "capturedAt");
623 + if (!validDate(capturedAt)) {
624 + throw new SystemDocumentError(
625 + "metadata.date",
626 + "capturedAt must be a valid ISO date",
627 + );
629 + const sources = optionalUniqueStrings(fields, "sources");
630 + return sources
631 + ? { id, type, capturedAt, sources }
632 + : { id, type, capturedAt };
634 + default:
635 + throw new SystemDocumentError(
636 + "metadata.type",
637 + `Unsupported metadata type: ${type}`,
638 + );
642 +export function parseAuthoredDocument(
643 + source: string,
644 + prefix: string,
645 +): AuthoredDocument {
646 + const parsed = parseRichMarkdown(source);
647 + return {
648 + metadata: projectMetadata(parsed.frontmatter, prefix),
649 + frontmatter: parsed.frontmatter,
650 + };
653 +export function validateDocumentPath(
654 + documentPath: string,
655 + metadata: DocumentMetadata,
656 + prefix: string,
657 +): void {
658 + const parsed = parseDocumentId(metadata.id, prefix);
659 + const expectedDirectory = DIRECTORY_BY_TYPE[metadata.type];
660 + const pattern = new RegExp(`^${metadata.id}-${SLUG}$`);
661 + const parts = documentPath.split("/");
662 + if (
663 + parsed.type !== metadata.type
664 + || parts.length !== 4
665 + || parts[0] !== ".system"
666 + || parts[1] !== expectedDirectory
667 + || !pattern.test(parts[2] ?? "")
668 + || parts[3] !== "index.md"
669 + ) {
670 + throw new SystemDocumentError(
671 + "document.path",
672 + `Bundle path mismatch for ${metadata.id}: ${documentPath}`,
673 + );
676 +```
678 +Unknown frontmatter fields remain in `frontmatter` and never create graph edges.
680 +Research sources are arbitrary unique strings; do not retain the HTTPS-only policy.
682 +Use this complete discovery shape:
684 +```typescript
685 +const scanBundleAssets = (
686 + absolute: string,
687 + relative: string,
688 + findings: Diagnostic[],
689 +): void => {
690 + for (
691 + const entry of readdirSync(absolute, { withFileTypes: true }).sort(
692 + (left, right) => left.name.localeCompare(right.name),
694 + ) {
695 + if (relative.split("/").length === 3 && entry.name === "index.md") {
696 + continue;
698 + const childAbsolute = path.join(absolute, entry.name);
699 + const childRelative = `${relative}/${entry.name}`;
700 + const stats = lstatSync(childAbsolute, { throwIfNoEntry: false });
701 + if (!stats) continue;
702 + if (stats.isSymbolicLink()) {
703 + findings.push(diagnostic(
704 + "bundle.symbolic-link",
705 + childRelative,
706 + `Bundle path is a symbolic link: ${childRelative}`,
707 + ));
708 + } else if (stats.isDirectory()) {
709 + scanBundleAssets(childAbsolute, childRelative, findings);
714 +export function discoverDocumentBundles(root: string): BundleDiscovery {
715 + const sources: BundleDocumentSource[] = [];
716 + const diagnostics: Diagnostic[] = [];
717 + for (const directory of Object.values(DIRECTORY_BY_TYPE)) {
718 + const relativeDirectory = `.system/${directory}`;
719 + const absoluteDirectory = path.join(root, relativeDirectory);
720 + const directoryStats = lstatSync(absoluteDirectory, {
721 + throwIfNoEntry: false,
722 + });
723 + if (!directoryStats?.isDirectory() || directoryStats.isSymbolicLink()) {
724 + continue;
726 + for (
727 + const entry of readdirSync(absoluteDirectory, {
728 + withFileTypes: true,
729 + }).sort((left, right) => left.name.localeCompare(right.name))
730 + ) {
731 + const bundleRelative = `${relativeDirectory}/${entry.name}`;
732 + const bundleAbsolute = path.join(absoluteDirectory, entry.name);
733 + const bundleStats = lstatSync(bundleAbsolute, { throwIfNoEntry: false });
734 + if (bundleStats?.isSymbolicLink()) {
735 + diagnostics.push(diagnostic(
736 + "bundle.symbolic-link",
737 + bundleRelative,
738 + `Bundle path is a symbolic link: ${bundleRelative}`,
739 + ));
740 + continue;
742 + if (!bundleStats?.isDirectory()) {
743 + diagnostics.push(diagnostic(
744 + "bundle.expected-directory",
745 + bundleRelative,
746 + `Expected a document bundle directory: ${bundleRelative}`,
747 + ));
748 + continue;
750 + const indexRelative = `${bundleRelative}/index.md`;
751 + const indexAbsolute = path.join(bundleAbsolute, "index.md");
752 + const indexStats = lstatSync(indexAbsolute, { throwIfNoEntry: false });
753 + if (!indexStats) {
754 + diagnostics.push(diagnostic(
755 + "bundle.missing-index",
756 + bundleRelative,
757 + `Bundle is missing index.md: ${bundleRelative}`,
758 + ));
759 + } else if (indexStats.isSymbolicLink()) {
760 + diagnostics.push(diagnostic(
761 + "bundle.symbolic-link",
762 + indexRelative,
763 + `Bundle path is a symbolic link: ${indexRelative}`,
764 + ));
765 + } else if (!indexStats.isFile()) {
766 + diagnostics.push(diagnostic(
767 + "bundle.expected-file",
768 + indexRelative,
769 + `Expected a regular index.md: ${indexRelative}`,
770 + ));
771 + } else {
772 + sources.push({
773 + path: indexRelative,
774 + markdown: readFileSync(indexAbsolute, "utf8"),
775 + });
777 + scanBundleAssets(bundleAbsolute, bundleRelative, diagnostics);
780 + return {
781 + sources: sources.sort((left, right) => left.path.localeCompare(right.path)),
782 + diagnostics: diagnostics.sort(compareDiagnostics),
783 + };
785 +```
787 +Do not follow symlinks.
789 +- [ ] **Step 5: Route indexing and candidates through bundle sources**
791 +Implement the bundle graph route as follows while the old HTML functions remain only for the not-yet-migrated runtime caller:
793 +```typescript
794 +export function indexBundleDocuments(
795 + sources: readonly BundleDocumentSource[],
796 + prefix: string,
797 +): BundleDocumentIndex {
798 + const documents: BundleDocumentRecord[] = [];
799 + const graphEligible: BundleDocumentRecord[] = [];
800 + const diagnostics: Diagnostic[] = [];
801 + for (
802 + const item of [...sources].sort((left, right) =>
803 + left.path.localeCompare(right.path)
805 + ) {
806 + try {
807 + const parsed = parseAuthoredDocument(item.markdown, prefix);
808 + let pathValid = true;
809 + try {
810 + validateDocumentPath(item.path, parsed.metadata, prefix);
811 + } catch (error) {
812 + pathValid = false;
813 + diagnostics.push(diagnostic(
814 + "document.path",
815 + item.path,
816 + (error as Error).message,
817 + ));
819 + const record = {
820 + path: item.path,
821 + metadata: parsed.metadata,
822 + frontmatter: parsed.frontmatter,
823 + };
824 + documents.push(record);
825 + if (pathValid) graphEligible.push(record);
826 + } catch (error) {
827 + const value = error as SystemDocumentError | MarkdownDocumentError;
828 + diagnostics.push(diagnostic(
829 + "document.metadata",
830 + item.path,
831 + `${value.code}: ${value.message}`,
832 + ));
836 + const groups = new Map<string, BundleDocumentRecord[]>();
837 + for (const document of graphEligible) {
838 + groups.set(document.metadata.id, [
839 + ...(groups.get(document.metadata.id) ?? []),
840 + document,
841 + ]);
844 + for (const [id, records] of groups) {
845 + if (records.length < 2) continue;
846 + const paths = records.map((record) => record.path).sort();
847 + for (const record of records) {
848 + diagnostics.push(diagnostic(
849 + "graph.duplicate-id",
850 + record.path,
851 + `Duplicate ID ${id}: ${paths.join(", ")}`,
852 + ));
856 + const unique = new Map(
857 + [...groups]
858 + .filter(([, records]) => records.length === 1)
859 + .map(([id, records]) => [id, records[0]!] as const),
860 + );
862 + for (const document of graphEligible) {
863 + for (const [targetId, expectedType] of references(document.metadata)) {
864 + const referencedType = parseDocumentId(targetId, prefix).type;
865 + const target = unique.get(targetId);
866 + if (referencedType !== expectedType) {
867 + diagnostics.push(diagnostic(
868 + "graph.forbidden-edge",
869 + document.path,
870 + `${document.metadata.id} must reference ${expectedType}; ${targetId} is ${referencedType}`,
871 + ));
872 + } else if (!target) {
873 + diagnostics.push(diagnostic(
874 + "graph.dangling-reference",
875 + document.path,
876 + `${document.metadata.id} references missing ${targetId}`,
877 + ));
878 + } else if (target.metadata.type !== expectedType) {
879 + diagnostics.push(diagnostic(
880 + "graph.forbidden-edge",
881 + document.path,
882 + `${document.metadata.id} must reference ${expectedType}; ${targetId} is ${target.metadata.type}`,
883 + ));
886 + if (document.metadata.type === "plan" && document.metadata.roadmap) {
887 + const roadmap = unique.get(document.metadata.roadmap);
888 + if (
889 + roadmap?.metadata.type === "roadmap"
890 + && roadmap.metadata.spec !== document.metadata.spec
891 + ) {
892 + diagnostics.push(diagnostic(
893 + "graph.forbidden-edge",
894 + document.path,
895 + `${document.metadata.roadmap} belongs to ${roadmap.metadata.spec}, not ${document.metadata.spec}`,
896 + ));
900 + return {
901 + documents,
902 + diagnostics: diagnostics.sort(compareDiagnostics),
903 + };
906 +const diagnosticIdentity = (item: Diagnostic) =>
907 + JSON.stringify([item.path, item.code, item.message]);
909 +export function validateBundleCandidate(
910 + current: readonly BundleDocumentSource[],
911 + candidate: BundleDocumentSource,
912 + prefix: string,
913 +): readonly Diagnostic[] {
914 + const baseline = new Set(
915 + indexBundleDocuments(current, prefix).diagnostics.map(diagnosticIdentity),
916 + );
917 + const next = indexBundleDocuments(
919 + ...current.filter((source) => source.path !== candidate.path),
920 + candidate,
921 + ],
922 + prefix,
923 + );
924 + return next.diagnostics.filter(
925 + (item) =>
926 + item.path === candidate.path
927 + || (!baseline.has(diagnosticIdentity(item))
928 + && item.code !== "graph.duplicate-id"),
929 + );
931 +```
933 +Reuse the existing `references` graph projection unchanged.
935 +Do not make either new function accept HTML sources.
937 +Preserve the existing baseline-diagnostic suppression behavior in candidate validation.
939 +- [ ] **Step 6: Run kernel checks**
941 +```bash
942 +mise run test -- extensions/the-system/__tests__/markdown.test.ts \
943 + extensions/the-system/__tests__/documents.test.ts
944 +mise run check
945 +```
947 +Expected: new parser/bundle tests PASS; old runtime/doctor callers still compile because their HTML exports have not yet been removed.
949 +- [ ] **Step 7: Commit the bundle kernel**
951 +```bash
952 +git add extensions/the-system/documents.ts \
953 + extensions/the-system/__tests__/documents.test.ts
954 +git commit -m "feat(the-system): add markdown bundle kernel"
955 +```
957 +### Task 3: Migrate Initialization And Doctor To Schema V2
959 +**Files:**
961 +- Modify: `extensions/the-system/init.ts`
962 +- Modify: `extensions/the-system/scripts/init.mjs`
963 +- Modify: `extensions/the-system/doctor.ts`
964 +- Modify: `extensions/the-system/__tests__/init.test.ts`
965 +- Modify: `extensions/the-system/__tests__/doctor.test.ts`
967 +- [ ] **Step 1: Write failing schema-v2 initialization tests**
969 +Replace machine-asset expectations with:
971 +```typescript
972 +assert.equal(
973 + readFileSync(path.join(project, ".system/config.json"), "utf8"),
974 + "{\n\t\"prefix\": \"PX\",\n\t\"schemaVersion\": 2\n}\n",
976 +assert.equal(
977 + lstatSync(path.join(project, ".system/system.css"), {
978 + throwIfNoEntry: false,
979 + }),
980 + undefined,
982 +```
984 +Add a migration fixture containing:
986 +```json
987 +{ "prefix": "PX", "schemaVersion": 1, "styleVersion": 1 }
988 +```
990 +and `.system/system.css`.
992 +Assert inspection reports exactly:
994 +```typescript
996 + ".system/config.json schemaVersion 1 -> 2; remove styleVersion",
997 + ".system/system.css remove obsolete machine-owned asset",
999 +```
1001 +Assert `apply` leaves both untouched and returns them as pending.
1003 +Assert approved `upgrade` rewrites config, removes CSS, preserves all core bytes/mtimes, and reports `.system/system.css` in `removed` rather than `changed`.
1005 +Assert a symlink at `.system/system.css` fails with `init.unsafe-path` instead of being removed.
1007 +- [ ] **Step 2: Write failing doctor bundle tests**
1009 +Rewrite doctor fixtures around bundle `index.md` files and schema-v2 config.
1011 +Assert:
1013 +- `system.css` is no longer required;
1014 +- an existing regular `.system/system.css` reports `filesystem.obsolete`;
1015 +- bundle structural diagnostics come from `discoverDocumentBundles`;
1016 +- graph and `SYSTEM-SPEC` diagnostics still combine and sort stably;
1017 +- mockup HTML inside a valid spec bundle needs no filename-owner heuristic;
1018 +- doctor never follows bundle symlinks;
1019 +- a complete bundle system is green;
1020 +- CLI output and no-mutation snapshots remain stable.
1022 +- [ ] **Step 3: Run initialization and doctor tests to verify RED**
1024 +```bash
1025 +mise run test -- extensions/the-system/__tests__/init.test.ts \
1026 + extensions/the-system/__tests__/doctor.test.ts
1027 +```
1029 +Expected: FAIL on style/config and flat-HTML assumptions.
1031 +- [ ] **Step 4: Make config schema v2 exact**
1033 +In `documents.ts`, set `SCHEMA_VERSION` to `2` and make current config exactly:
1035 +```typescript
1036 +export type SystemConfig = Readonly<{
1037 + prefix: string;
1038 + schemaVersion: number;
1039 +}>;
1040 +```
1042 +`parseSystemConfig` accepts only `prefix` and `schemaVersion`.
1044 +Remove `STYLE_VERSION`.
1046 +In `documents.ts`, add one shared inspection-only parser:
1048 +```typescript
1049 +export type InspectedSystemConfig = Readonly<{
1050 + config: SystemConfig;
1051 + legacyStyleVersion?: number;
1052 +}>;
1054 +export function inspectSystemConfig(
1055 + source: string,
1056 +): InspectedSystemConfig {
1057 + try {
1058 + return { config: parseSystemConfig(source) };
1059 + } catch (currentError) {
1060 + let parsed: unknown;
1061 + try {
1062 + parsed = JSON.parse(source);
1063 + } catch {
1064 + throw currentError;
1066 + const duplicates = duplicateTopLevelKeys(source);
1067 + if (duplicates.length > 0) throw currentError;
1068 + let value: Record<string, unknown>;
1069 + try {
1070 + value = objectValue(parsed, "Legacy config");
1071 + exactKeys(value, ["prefix", "schemaVersion", "styleVersion"]);
1072 + } catch {
1073 + throw currentError;
1075 + if (
1076 + value.schemaVersion !== 1
1077 + || !positiveInteger(value.styleVersion)
1078 + ) throw currentError;
1079 + const config = parseSystemConfig(JSON.stringify({
1080 + prefix: value.prefix,
1081 + schemaVersion: value.schemaVersion,
1082 + }));
1083 + return {
1084 + config,
1085 + legacyStyleVersion: value.styleVersion as number,
1086 + };
1089 +```
1091 +`init.ts` and `doctor.ts` both use this inspection route so v1 reports an upgrade instead of invalid JSON shape.
1093 +Runtime and normal document operations continue using strict `parseSystemConfig` and therefore never accept `styleVersion` as current config.
1095 +- [ ] **Step 5: Make initialization config-only**
1097 +Replace `MachineAssets` with:
1099 +```typescript
1100 +export type MachineState = Readonly<{ schemaVersion: number }>;
1101 +export const DEFAULT_MACHINE_STATE: MachineState = Object.freeze({
1102 + schemaVersion: SCHEMA_VERSION,
1103 +});
1104 +```
1106 +Change `InitializationResult` to include:
1108 +```typescript
1109 +removed: readonly string[];
1110 +```
1112 +Remove CSS creation and writing.
1114 +When approved upgrade sees a regular obsolete CSS file, remove it with `unlinkSync`, append the path to `removed`, and never follow a symlink.
1116 +Update `scripts/init.mjs`:
1118 +```javascript
1119 +for (const item of result.changed) console.log(`WROTE ${item}`);
1120 +for (const item of result.removed) console.log(`REMOVED ${item}`);
1121 +```
1123 +- [ ] **Step 6: Route doctor through shared bundle discovery**
1125 +Delete doctor-local HTML collection, mockup-owner matching, style-version checks, and CSS-required state.
1127 +Use `inspectSystemConfig` for config diagnostics, then use:
1129 +```typescript
1130 +const discovery = discoverDocumentBundles(root);
1131 +diagnostics.push(...discovery.diagnostics);
1132 +if (prefix) {
1133 + const index = indexBundleDocuments(discovery.sources, prefix);
1134 + diagnostics.push(...index.diagnostics);
1135 + specIds = new Set(
1136 + index.documents
1137 + .filter((document) => document.metadata.type === "spec")
1138 + .map((document) => document.metadata.id),
1139 + );
1141 +```
1143 +Report a regular legacy CSS file as obsolete.
1145 +A non-regular CSS path remains an unsafe filesystem diagnostic.
1147 +- [ ] **Step 7: Run focused and regression tests**
1149 +```bash
1150 +mise run test -- extensions/the-system/__tests__/init.test.ts \
1151 + extensions/the-system/__tests__/doctor.test.ts \
1152 + extensions/the-system/__tests__/documents.test.ts \
1153 + extensions/the-system/__tests__/system.test.ts
1154 +mise run check
1155 +```
1157 +Expected: all listed suites PASS; runtime remains on the temporary HTML route but uses current initialization/config successfully.
1159 +- [ ] **Step 8: Hold the migration for the runtime cutover**
1161 +Do not commit Task 3 separately.
1163 +At this point doctor and initialization describe only bundles while runtime still accepts flat HTML, so a commit would violate the phase-boundary rule.
1165 +Keep these planned changes unstaged or staged only in a temporary local index until Task 4 completes the runtime cutover.
1167 +Run `git diff --check` and continue directly to Task 4.
1169 +### Task 4: Migrate Runtime Governance And Delete HTML Legacy
1171 +**Files:**
1173 +- Modify: `extensions/the-system/system.ts`
1174 +- Modify: `extensions/the-system/__tests__/system.test.ts`
1175 +- Modify: `extensions/the-system/documents.ts`
1176 +- Modify: `extensions/the-system/__tests__/documents.test.ts`
1177 +- Delete: `extensions/the-system/assets/system.css`
1179 +- [ ] **Step 1: Rewrite runtime fixtures as bundles**
1181 +Replace the flat-HTML fixture helpers with:
1183 +```typescript
1184 +const frontmatter = (value: Record<string, unknown>) =>
1185 + Object.entries(value)
1186 + .map(([key, item]) =>
1187 + `${key}: ${Array.isArray(item) ? JSON.stringify(item) : String(item)}`
1189 + .join("\n");
1190 +const documentSource = (metadata: Record<string, unknown>) =>
1191 + `---\n${frontmatter(metadata)}\n---\n\n# Contract\n\nApproved.\n`;
1192 +const writeSpec = (root: string) => {
1193 + const relative = ".system/specs/PX-SPEC-001-contract/index.md";
1194 + write(
1195 + root,
1196 + relative,
1197 + documentSource({
1198 + id: "PX-SPEC-001",
1199 + type: "spec",
1200 + }),
1201 + );
1202 + return relative;
1204 +```
1206 +Use a YAML serializer helper or literal fixture strings for nested values; do not rely on JSON array syntax if the YAML parser configuration rejects it.
1208 +- [ ] **Step 2: Write failing bundle-governance tests**
1210 +Prove:
1212 +- a valid new spec `index.md` passes without UI;
1213 +- invalid frontmatter/path/graph candidates block before approval;
1214 +- flat `.html`, direct typed-directory files, and nested authored `other/index.md` locations block;
1215 +- a new asset under an existing valid spec bundle passes without UI;
1216 +- an asset under a missing or invalid spec bundle blocks;
1217 +- editing/replacing an existing spec `index.md`, mockup, image, dataset, or nested regular asset requests one approval;
1218 +- existing spec files fail closed without UI;
1219 +- existing roadmap/plan/issue/research indexes validate but do not request ownership approval;
1220 +- symlinked bundles/indexes/assets/ancestors block;
1221 +- computed `edit` candidates validate before approval;
1222 +- shell guard recognizes core paths and every path below `.system/specs/<bundle>/`;
1223 +- shell reads and unrelated writes pass.
1225 +Representative asset matrix:
1227 +```typescript
1228 +for (
1229 + const relative of [
1230 + ".system/specs/PX-SPEC-001-contract/index.md",
1231 + ".system/specs/PX-SPEC-001-contract/mockup-mobile.html",
1232 + ".system/specs/PX-SPEC-001-contract/diagram.svg",
1233 + ".system/specs/PX-SPEC-001-contract/evidence/data.csv",
1235 +) {
1236 + const result = await preflightFileMutation(
1237 + root,
1238 + "write",
1239 + { path: relative, content: "replacement" },
1240 + approvingUi,
1241 + );
1242 + assert.equal(result?.block, undefined, relative);
1243 + assert.equal(approvals, 1, relative);
1244 + approvals = 0;
1246 +```
1248 +- [ ] **Step 3: Run runtime tests to verify RED**
1250 +```bash
1251 +mise run test -- extensions/the-system/__tests__/system.test.ts
1252 +```
1254 +Expected: FAIL on every flat-HTML assumption.
1256 +- [ ] **Step 4: Replace runtime path classification**
1258 +Delete `MOCKUP_NAME`, direct/nested HTML classifiers, mockup HTML validation, and runtime-local source collection.
1260 +Add one parser for governed authored paths:
1262 +```typescript
1263 +type GovernedDocumentPath = Readonly<{
1264 + directory: "specs" | "roadmaps" | "plans" | "issues" | "research";
1265 + bundle: string;
1266 + asset: string;
1267 + index: boolean;
1268 +}>;
1270 +const governedDocumentPath = (
1271 + relative: string,
1272 +): GovernedDocumentPath | undefined => {
1273 + const match =
1274 + /^\.system\/(specs|roadmaps|plans|issues|research)\/([^/]+)\/(.+)$/.exec(
1275 + relative,
1276 + );
1277 + if (!match) return undefined;
1278 + return {
1279 + directory: match[1] as GovernedDocumentPath["directory"],
1280 + bundle: match[2]!,
1281 + asset: match[3]!,
1282 + index: match[3] === "index.md",
1283 + };
1285 +```
1287 +Any path below a typed directory that does not match this shape must block with the required bundle layout.
1289 +Keep the existing root containment and symlink-ancestor checks.
1291 +- [ ] **Step 5: Route validation and ownership through one bundle resolver**
1293 +Add this resolver beside the existing candidate-edit helpers:
1295 +```typescript
1296 +type ResolvedBundleMutation = Readonly<{
1297 + location: GovernedDocumentPath;
1298 + metadata?: DocumentMetadata;
1299 + findings: readonly Diagnostic[];
1300 +}>;
1302 +const resolveBundleMutation = (
1303 + root: string,
1304 + relative: string,
1305 + content: string | undefined,
1306 +): ResolvedBundleMutation => {
1307 + const location = governedDocumentPath(relative);
1308 + if (!location) {
1309 + throw new Error(
1310 + `Authored paths require .system/<type>/<ID>-<slug>/<file>: ${relative}`,
1311 + );
1313 + const prefix = projectPrefix(root);
1314 + const discovery = discoverDocumentBundles(root);
1315 + const bundlePath = `.system/${location.directory}/${location.bundle}`;
1316 + const localDiscovery = discovery.diagnostics.filter(
1317 + (item) =>
1318 + item.path === bundlePath || item.path.startsWith(`${bundlePath}/`),
1319 + ).filter(
1320 + (item) =>
1321 + !(location.index
1322 + && item.path === bundlePath
1323 + && item.code === "bundle.missing-index"),
1324 + );
1325 + if (localDiscovery.length > 0) {
1326 + return {
1327 + location,
1328 + findings: localDiscovery,
1329 + };
1332 + if (location.index) {
1333 + if (content === undefined) {
1334 + throw new Error("Missing index candidate content");
1336 + const findings = validateBundleCandidate(
1337 + discovery.sources,
1338 + { path: relative, markdown: content },
1339 + prefix,
1340 + );
1341 + const parsed = parseAuthoredDocument(content, prefix);
1342 + return {
1343 + location,
1344 + metadata: parsed.metadata,
1345 + findings,
1346 + };
1349 + const indexPath = `${bundlePath}/index.md`;
1350 + const owner = discovery.sources.find((source) => source.path === indexPath);
1351 + if (!owner) {
1352 + throw new Error(
1353 + `Bundle requires a valid index.md before assets: ${bundlePath}`,
1354 + );
1356 + const indexed = indexBundleDocuments(discovery.sources, prefix);
1357 + const findings = indexed.diagnostics.filter(
1358 + (item) => item.path === indexPath,
1359 + );
1360 + const document = indexed.documents.find(
1361 + (item) => item.path === indexPath,
1362 + );
1363 + if (!document) {
1364 + throw new Error(`Bundle index is invalid: ${indexPath}`);
1366 + return {
1367 + location,
1368 + metadata: document.metadata,
1369 + findings,
1370 + };
1372 +```
1374 +- [ ] **Step 6: Replace the governed-document branch in `preflightFileMutation`**
1376 +Keep the existing root discovery, root containment, core handling, symlink-ancestor rejection, `candidateContent`, diagnostic formatting, and approval text.
1378 +Replace the HTML-specific branch after core handling with:
1380 +```typescript
1381 +const typedDirectory =
1382 + /^\.system\/(specs|roadmaps|plans|issues|research)(?:\/|$)/.test(relative);
1383 +if (!typedDirectory) return undefined;
1385 +const location = governedDocumentPath(relative);
1386 +if (!location) {
1387 + return blocked(
1388 + `The System requires document bundles at .system/<type>/<ID>-<slug>/<file>: ${relative}.`,
1389 + );
1392 +let content: string | undefined;
1393 +if (location.index) {
1394 + try {
1395 + content = candidateContent(target, kind, input);
1396 + } catch (error) {
1397 + return blocked(
1398 + `The System candidate validation failed: ${
1399 + error instanceof Error ? error.message : String(error)
1400 + }`,
1401 + );
1405 +let resolved: ResolvedBundleMutation;
1406 +try {
1407 + resolved = resolveBundleMutation(root, relative, content);
1408 +} catch (error) {
1409 + return blocked(
1410 + `The System candidate validation failed: ${
1411 + error instanceof Error ? error.message : String(error)
1412 + }`,
1413 + );
1415 +if (resolved.findings.length > 0) {
1416 + return blocked(diagnosticsReason(resolved.findings));
1418 +if (!resolved.metadata) {
1419 + return blocked(
1420 + `The System could not determine bundle ownership: ${relative}.`,
1421 + );
1424 +const targetStats = lstatSync(target, { throwIfNoEntry: false });
1425 +if (!targetStats) return undefined;
1426 +if (!targetStats.isFile()) {
1427 + return blocked(`The System expected a regular owned file at ${relative}.`);
1429 +if (resolved.metadata.type !== "spec") return undefined;
1430 +if (!ui.hasUI) {
1431 + return blocked(
1432 + `The System blocked existing human-owned ${relative}: interactive UI is unavailable.`,
1433 + );
1435 +const approve = `Approve once: ${kind} ${relative}`;
1436 +const deny = `Deny: keep ${relative} unchanged`;
1437 +const decision = await ui.select("The System ownership approval", [
1438 + approve,
1439 + deny,
1440 +]);
1441 +if (decision === approve) return undefined;
1442 +return blocked(
1443 + decision === deny
1444 + ? `The System ownership approval was denied for ${relative}.`
1445 + : `The System ownership approval was cancelled for ${relative}.`,
1447 +```
1449 +The behavior is now complete:
1451 +- existing core blocks;
1452 +- missing approved core writes pass;
1453 +- missing valid indexes pass after candidate validation;
1454 +- missing assets pass only under a valid owning index;
1455 +- every existing regular spec-bundle file requires UI approval;
1456 +- existing non-spec files pass after bundle validation;
1457 +- non-regular and symlink paths block.
1459 +Asset bytes are never parsed or sanitized.
1461 +- [ ] **Step 7: Expand shell recognition minimally**
1463 +Replace the old `.html` matcher with a matcher that recognizes:
1465 +```text
1466 +.system/SYSTEM.md
1467 +.system/MISSION.md
1468 +.system/RULES.md
1469 +.system/specs/<bundle>/<any-path>
1470 +```
1472 +Keep the explicit advisory message and do not claim shell sandboxing.
1474 +- [ ] **Step 8: Delete the HTML kernel and stylesheet**
1476 +After every caller uses bundle APIs, delete from `documents.ts`:
1478 +- HTML tag/attribute scanners;
1479 +- `parseDocumentMetadata`;
1480 +- `validateAuthoredHtml`;
1481 +- `validateFilename`;
1482 +- executable/remote-resource HTML policy;
1483 +- `STYLE_VERSION`;
1484 +- the old HTML `DocumentSource`, `DocumentRecord`, `indexDocuments`, and `validateDocumentCandidate` route.
1486 +Delete `extensions/the-system/assets/system.css`.
1488 +Remove every old HTML/CSS test rather than preserving compatibility assertions.
1490 +- [ ] **Step 9: Run all Phase 6 code tests**
1492 +```bash
1493 +mise run test -- extensions/the-system/__tests__/markdown.test.ts \
1494 + extensions/the-system/__tests__/documents.test.ts \
1495 + extensions/the-system/__tests__/doctor.test.ts \
1496 + extensions/the-system/__tests__/init.test.ts \
1497 + extensions/the-system/__tests__/system.test.ts
1498 +mise run check
1499 +```
1501 +Expected: all PASS and no live code imports removed HTML/CSS symbols.
1503 +- [ ] **Step 10: Commit the atomic governance cutover**
1505 +Stage Task 3 and Task 4 together:
1507 +```bash
1508 +git add extensions/the-system/system.ts \
1509 + extensions/the-system/__tests__/system.test.ts \
1510 + extensions/the-system/documents.ts \
1511 + extensions/the-system/__tests__/documents.test.ts \
1512 + extensions/the-system/init.ts \
1513 + extensions/the-system/scripts/init.mjs \
1514 + extensions/the-system/doctor.ts \
1515 + extensions/the-system/__tests__/init.test.ts \
1516 + extensions/the-system/__tests__/doctor.test.ts
1517 +git add -u -- extensions/the-system/assets/system.css
1518 +git commit -m "feat(the-system): cut governance over to markdown bundles"
1519 +```
1521 +The committed tree must have doctor, initialization, and runtime on the same bundle model.
1523 +### Task 5: Update The Document And Initialization Authorities
1525 +**Files:**
1527 +- Modify: `extensions/the-system/skills/system-documents/SKILL.md`
1528 +- Modify: `extensions/the-system/skills/the-system-init/SKILL.md`
1529 +- Modify: `extensions/the-system/__tests__/workflow-skills.test.ts`
1530 +- Modify: `extensions/the-system/README.md`
1531 +- Modify: `extensions/the-system/CHANGELOG.md`
1533 +- [ ] **Step 1: Write failing skill-contract tests**
1535 +Replace HTML assertions with exact required phrases covering:
1537 +```typescript
1538 +for (
1539 + const contract of [
1540 + "<ID>-<slug>/index.md",
1541 + "leading YAML frontmatter",
1542 + "source order",
1543 + "GFM",
1544 + "Mermaid",
1545 + "TeX",
1546 + "definition lists",
1547 + "GitHub alerts",
1548 + "raw HTML",
1549 + "existing file inside a spec bundle",
1550 + "relative bundle assets",
1551 + "scripts/doctor.mjs",
1553 +) assert.ok(documents.includes(contract), contract);
1555 +assert.doesNotMatch(
1556 + documents,
1557 + /system-meta|\.\.\/system\.css|authored HTML shell|forbid remote/i,
1559 +```
1561 +Update initialization assertions to require:
1563 +- config is the only machine-owned file;
1564 +- document bundles contain `index.md` and assets;
1565 +- specs and all existing spec-bundle files are human-owned;
1566 +- approved upgrade removes obsolete `system.css`;
1567 +- no new initialization creates or copies CSS.
1569 +Keep brainstorming persistence assertions unchanged because Phase 8 owns that migration.
1571 +- [ ] **Step 2: Run workflow tests to verify RED**
1573 +```bash
1574 +mise run test -- extensions/the-system/__tests__/workflow-skills.test.ts
1575 +```
1577 +Expected: FAIL on old HTML and CSS instructions.
1579 +- [ ] **Step 3: Rewrite `system-documents`**
1581 +Keep it the single authority.
1583 +Define:
1585 +- exact bundle paths;
1586 +- YAML frontmatter as graph authority;
1587 +- current known graph fields plus arbitrary extra fields;
1588 +- complete rich Markdown profile;
1589 +- trusted raw HTML, remote references, and cross-bundle links;
1590 +- spec file-level ownership;
1591 +- bundle-relative assets and accepted `mockup-*.html` ownership;
1592 +- doctor validation after writes;
1593 +- no browser review instructions yet because Phase 7 owns viewing.
1595 +Remove HTML shell, `system-meta`, shared CSS, and active-resource prohibition sections completely.
1597 +- [ ] **Step 4: Rewrite the initialization topology draft**
1599 +In `the-system-init`, make the proposed `SYSTEM.md` draft state:
1601 +```text
1602 +Authored documents live at .system/<type>/<ID>-<slug>/index.md.
1603 +Every other file in that directory belongs to the document.
1604 +Humans own core laws and every existing file in a spec bundle.
1605 +Agents author roadmaps/plans for review and maintain issues/research.
1606 +config.json is machine-owned.
1607 +```
1609 +Make upgrade output explain removal of obsolete machine-owned `system.css` before asking approval.
1611 +- [ ] **Step 5: Update current README and changelog**
1613 +Document only Phase 6 surfaces:
1615 +- bundle topology;
1616 +- doctor;
1617 +- initialization/config upgrade;
1618 +- runtime ownership.
1620 +Explicitly state that renderer/view commands and lifecycle authoring migration arrive in later roadmap phases.
1622 +Do not document unavailable `/system-view`, `/system-book`, or `/system-spec` commands.
1624 +- [ ] **Step 6: Format only planned files, then run skill and package checks**
1626 +```bash
1627 +mise x -- biome check --write \
1628 + extensions/the-system/markdown.ts \
1629 + extensions/the-system/documents.ts \
1630 + extensions/the-system/doctor.ts \
1631 + extensions/the-system/init.ts \
1632 + extensions/the-system/system.ts \
1633 + extensions/the-system/scripts/init.mjs \
1634 + extensions/the-system/package.json \
1635 + extensions/the-system/__tests__/markdown.test.ts \
1636 + extensions/the-system/__tests__/documents.test.ts \
1637 + extensions/the-system/__tests__/doctor.test.ts \
1638 + extensions/the-system/__tests__/init.test.ts \
1639 + extensions/the-system/__tests__/system.test.ts \
1640 + extensions/the-system/__tests__/workflow-skills.test.ts
1641 +mise x -- dprint fmt \
1642 + extensions/the-system/skills/system-documents/SKILL.md \
1643 + extensions/the-system/skills/the-system-init/SKILL.md \
1644 + extensions/the-system/README.md \
1645 + extensions/the-system/CHANGELOG.md
1646 +mise run test -- extensions/the-system/__tests__/workflow-skills.test.ts
1647 +mise run check
1648 +mise run lint
1649 +```
1651 +Expected: all PASS unless unrelated concurrent work blocks repository-wide lint; report such a blocker with its exact path and do not alter it.
1653 +- [ ] **Step 7: Commit authority and documentation updates**
1655 +```bash
1656 +git add extensions/the-system/skills/system-documents/SKILL.md \
1657 + extensions/the-system/skills/the-system-init/SKILL.md \
1658 + extensions/the-system/__tests__/workflow-skills.test.ts \
1659 + extensions/the-system/README.md \
1660 + extensions/the-system/CHANGELOG.md
1661 +git commit -m "docs(the-system): define markdown bundle authority"
1662 +```
1664 +### Task 6: Verify The Phase Boundary
1666 +**Files:**
1668 +- No planned source changes.
1669 +- Modify only a Phase 6 file if verification exposes a defect in that file.
1671 +- [ ] **Step 1: Verify no authored-HTML legacy remains**
1673 +Run:
1675 +```bash
1676 +rg -n "validateAuthoredHtml|parseDocumentMetadata|system-meta|assets/system.css|\.system/(specs|roadmaps|plans|issues|research)/[^/]+\.html" \
1677 + extensions/the-system \
1678 + --glob '!CHANGELOG.md'
1679 +rg -n "styleVersion|\.system/system\.css" extensions/the-system \
1680 + --glob '!CHANGELOG.md'
1681 +```
1683 +Expected: the first scan has no matches.
1685 +The second scan matches only the narrow v1 migration/removal path in `init.ts`, its tests, and explicit obsolete-file documentation; it never appears in current config output or authored-document rules.
1687 +Historical `docs/super/**` is intentionally outside this scan.
1689 +- [ ] **Step 2: Run every The System unit/integration test**
1691 +```bash
1692 +mise run test -- extensions/the-system/__tests__
1693 +```
1695 +Expected: all The System suites PASS.
1697 +- [ ] **Step 3: Run retained browser regression tests**
1699 +```bash
1700 +mise //extensions/the-system:e2e
1701 +```
1703 +Expected: existing generic mockup E2E passes in Chromium and Firefox.
1705 +Phase 6 adds no renderer browser surface.
1707 +- [ ] **Step 4: Verify scoped formatting, then run repository gates**
1709 +```bash
1710 +mise x -- biome ci \
1711 + extensions/the-system/markdown.ts \
1712 + extensions/the-system/documents.ts \
1713 + extensions/the-system/doctor.ts \
1714 + extensions/the-system/init.ts \
1715 + extensions/the-system/system.ts \
1716 + extensions/the-system/scripts/init.mjs \
1717 + extensions/the-system/package.json \
1718 + extensions/the-system/__tests__/markdown.test.ts \
1719 + extensions/the-system/__tests__/documents.test.ts \
1720 + extensions/the-system/__tests__/doctor.test.ts \
1721 + extensions/the-system/__tests__/init.test.ts \
1722 + extensions/the-system/__tests__/system.test.ts \
1723 + extensions/the-system/__tests__/workflow-skills.test.ts
1724 +mise x -- dprint check \
1725 + extensions/the-system/skills/system-documents/SKILL.md \
1726 + extensions/the-system/skills/the-system-init/SKILL.md \
1727 + extensions/the-system/README.md \
1728 + extensions/the-system/CHANGELOG.md
1729 +mise run check
1730 +mise run lint
1731 +mise run test
1732 +mise run ci
1733 +```
1735 +Expected: all PASS.
1737 +If unrelated concurrent work blocks a repository-wide gate, preserve it, report the exact path/error, and retain the successful focused evidence.
1739 +- [ ] **Step 5: Audit source and staged scope**
1741 +```bash
1742 +git status --short
1743 +git diff --check
1744 +git diff --stat HEAD~4..HEAD -- \
1745 + extensions/the-system package-lock.json
1746 +```
1748 +Expected: only planned Phase 6 files appear in the four implementation commits; unrelated dirty work remains unstaged.
1750 +- [ ] **Step 6: Record completion evidence**
1752 +Do not create an empty verification commit.
1754 +Report:
1756 +- focused and complete The System test counts;
1757 +- E2E browser results;
1758 +- repository gate results;
1759 +- any unrelated blocker;
1760 +- the four Phase 6 commit IDs;
1761 +- confirmation that Phase 7 rendering and Phase 8 authoring remain unimplemented.
1763 +## Phase Boundary
1765 +After this plan executes:
1767 +- `.system` has one canonical rich Markdown bundle model;
1768 +- current config is schema v2 and contains no style version;
1769 +- initialization creates no stylesheet and approved upgrade removes the obsolete machine-owned CSS;
1770 +- doctor, graph indexing, candidate validation, runtime approval, and shell advisory guards share bundle semantics;
1771 +- every existing spec-bundle file is human-owned;
1772 +- arbitrary trusted assets remain useful;
1773 +- core injection, task branching, push-task, and generic mockup behavior remain working;
1774 +- no browser renderer or authoring workflow claims to exist early;
1775 +- the repository is ready for a separate Phase 7 renderer plan.