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
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:
33 +- `/system-view` and `/system-book`;
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 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**
78 +git diff
-- package-lock.json
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`:
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",
102 +Regenerate the lock through the repository task:
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:
115 +import assert
from "node:assert/strict";
116 +import { describe, it }
from "vitest";
117 +import { MarkdownDocumentError, parseRichMarkdown }
from "../markdown.ts";
122 +title: Rich documents 123 +owners: [human, the-system] 125 + approved: 2026-07-15 126 + flags: [visual, editable] 132 +> Canonical source remains editable. 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()], [
162 + result.frontmatter.
get(
"review"),
164 + [
"approved",
"2026-07-15"],
165 + [
"flags", [
"visual",
"editable"]],
168 + const tree
= JSON.
stringify(result.tree);
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);
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)
=> {
186 + ()
=> parseRichMarkdown(source),
187 + (error
: unknown)
=> 188 + error
instanceof MarkdownDocumentError && error.
code === code,
194 +- [ ] **Step 4: Run the parser tests to verify RED**
199 +mise run test
-- extensions/the-system/__tests__/markdown.test.ts
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:
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";
227 +export type FrontmatterValue = 232 + | readonly FrontmatterValue[]
234 +export type FrontmatterMap = ReadonlyMap<
string,
FrontmatterValue>;
235 +export type RichMarkdownDocument = Readonly<{
237 + frontmatter
: FrontmatterMap;
240 +export class MarkdownDocumentError extends Error {
241 + constructor(
readonly code
: string, message
: string) {
243 + this.
name = "MarkdownDocumentError";
247 +export const createMarkdownParser = ()
=> 250 + .
use(remarkFrontmatter, [
"yaml"])
252 + .
use(remarkDefinitionList)
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",
266 + if (blocks.
length !== 1) {
267 + throw new MarkdownDocumentError(
268 + "frontmatter.multiple",
269 + `Document requires one YAML frontmatter block; received ${blocks.length}`,
272 + const document
= parseDocument(blocks[
0]
!.
value, {
277 + if (
document.errors.
length > 0) {
278 + throw new MarkdownDocumentError(
279 + "frontmatter.invalid",
280 + document.errors.
map((error)
=> error.message).
join(
"; "),
283 + if (
!isMap(
document.contents)) {
284 + throw new MarkdownDocumentError(
285 + "frontmatter.shape",
286 + "Frontmatter must be a YAML map",
289 + return { tree, frontmatter:
convertMap(
document.contents.items) };
293 +Use these converters in the same file:
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;
309 + || typeof value
=== "boolean" 310 + || typeof value
=== "string" 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));
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**
343 +mise run test
-- extensions/the-system/__tests__/markdown.test.ts
347 +Expected: parser tests PASS and typecheck/static checks PASS.
349 +- [ ] **Step 7: Commit the parser slice**
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" 358 +Expected: only those four planned paths are staged.
360 +###
Task 2: Add Bundle Paths, Discovery, And YAML Graph Projection 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:
376 +const markdownSource = (
380 + frontmatter
: string,
382 + path:
`.system/${directory}/${id}-${slug}/index.md`,
383 + markdown:
`---\n${frontmatter}\n---\n\n# ${id}\n`,
390 +const parsed
= parseAuthoredDocument(
395 +roadmap: PX-ROADMAP-001 406 +assert.
deepEqual(parsed.metadata, {
409 + spec:
"PX-SPEC-001",
410 + roadmap:
"PX-ROADMAP-001",
413 +assert.
deepEqual([
...parsed.frontmatter.
keys()], [
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:
448 +assert.
deepEqual(discovery.sources, [{
449 + path:
".system/specs/PX-SPEC-001-contract/index.md",
450 + markdown:
specMarkdown(
"PX-SPEC-001"),
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",
461 +- [ ] **Step 3: Run the document tests to verify RED**
464 +mise run test
-- extensions/the-system/__tests__/documents.test.ts
467 +Expected: FAIL because bundle APIs do not exist.
469 +- [ ] **Step 4: Add the bundle API to `documents.ts`**
471 +Add these contracts:
474 +export type AuthoredDocument = Readonly<{
475 + metadata
: DocumentMetadata;
476 + frontmatter
: FrontmatterMap;
478 +export type BundleDocumentSource = Readonly<{
482 +export type BundleDocumentRecord = Readonly<{
484 + metadata
: DocumentMetadata;
485 + frontmatter
: FrontmatterMap;
487 +export type BundleDocumentIndex = Readonly<{
488 + documents
: readonly BundleDocumentRecord[];
489 + diagnostics
: readonly Diagnostic[];
491 +export type BundleDiscovery = Readonly<{
492 + sources
: readonly BundleDocumentSource[];
493 + diagnostics
: readonly Diagnostic[];
496 +export function parseAuthoredDocument(
499 +)
: AuthoredDocument;
500 +export function validateDocumentPath(
501 + documentPath
: string,
502 + metadata
: DocumentMetadata,
505 +export function discoverDocumentBundles(root
: string)
: BundleDiscovery;
506 +export function indexBundleDocuments(
507 + sources
: readonly BundleDocumentSource[],
509 +)
: BundleDocumentIndex;
510 +export function validateBundleCandidate(
511 + current
: readonly BundleDocumentSource[],
512 + candidate
: BundleDocumentSource,
514 +)
: readonly Diagnostic[];
517 +Project known graph metadata with these helpers:
520 +const requiredStringField = (
521 + fields
: FrontmatterMap,
524 + const value
= fields.
get(key);
525 + if (
typeof value
!== "string") {
526 + throw new SystemDocumentError(
528 + `${key} must be a string`,
534 +const optionalUniqueStrings = (
535 + fields
: FrontmatterMap,
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(
543 + `${key} must be a string array`,
546 + if (
new Set(value).
size !== value.
length) {
547 + throw new SystemDocumentError(
548 + "metadata.duplicate",
549 + `${key} must contain unique values`,
555 +const projectMetadata = (
556 + fields
: FrontmatterMap,
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}`,
568 + const reference = (key
: string)
=> {
569 + const value
= requiredStringField(fields, key);
570 + parseDocumentId(value, prefix);
575 + return { id, type };
577 + return { id, type, spec:
reference(
"spec") };
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",
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",
594 + parseDocumentId(roadmap, prefix);
598 + spec:
reference(
"spec"),
600 + phase: phase
as number,
604 + const status
= requiredStringField(fields,
"status");
605 + if (status
!== "open" && status
!== "fixed") {
606 + throw new SystemDocumentError(
608 + "Issue status must be open or fixed",
611 + const specs
= optionalUniqueStrings(fields,
"specs");
613 + throw new SystemDocumentError(
615 + "specs must be a string array",
618 + for (
const spec
of specs)
parseDocumentId(spec, prefix);
619 + return { id, type, status, specs };
622 + const capturedAt
= requiredStringField(fields,
"capturedAt");
623 + if (
!validDate(capturedAt)) {
624 + throw new SystemDocumentError(
626 + "capturedAt must be a valid ISO date",
629 + const sources
= optionalUniqueStrings(fields,
"sources");
631 + ? { id, type, capturedAt, sources }
632 + : { id, type, capturedAt };
635 + throw new SystemDocumentError(
637 + `Unsupported metadata type: ${type}`,
642 +export function parseAuthoredDocument(
645 +)
: AuthoredDocument {
646 + const parsed
= parseRichMarkdown(source);
648 + metadata:
projectMetadata(parsed.frontmatter, prefix),
649 + frontmatter: parsed.frontmatter,
653 +export function validateDocumentPath(
654 + documentPath
: string,
655 + metadata
: DocumentMetadata,
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(
"/");
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" 670 + throw new SystemDocumentError(
672 + `Bundle path mismatch for ${metadata.id}: ${documentPath}`,
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:
685 +const scanBundleAssets = (
688 + findings
: Diagnostic[],
691 + const entry
of readdirSync(absolute, { withFileTypes:
true }).
sort(
692 + (left, right)
=> left.
name.
localeCompare(right.
name),
695 + if (relative.
split(
"/").
length === 3 && entry.
name === "index.md") {
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",
706 + `Bundle path is a symbolic link: ${childRelative}`,
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,
723 + if (
!directoryStats?.
isDirectory()
|| directoryStats.
isSymbolicLink()) {
727 + const entry
of readdirSync(absoluteDirectory, {
728 + withFileTypes:
true,
729 + }).
sort((left, right)
=> left.
name.
localeCompare(right.
name))
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",
738 + `Bundle path is a symbolic link: ${bundleRelative}`,
742 + if (
!bundleStats?.
isDirectory()) {
743 + diagnostics.
push(
diagnostic(
744 + "bundle.expected-directory",
746 + `Expected a document bundle directory: ${bundleRelative}`,
750 + const indexRelative
= `${bundleRelative}/index.md`;
751 + const indexAbsolute
= path.
join(bundleAbsolute,
"index.md");
752 + const indexStats
= lstatSync(indexAbsolute, { throwIfNoEntry:
false });
754 + diagnostics.
push(
diagnostic(
755 + "bundle.missing-index",
757 + `Bundle is missing index.md: ${bundleRelative}`,
759 + }
else if (indexStats.
isSymbolicLink()) {
760 + diagnostics.
push(
diagnostic(
761 + "bundle.symbolic-link",
763 + `Bundle path is a symbolic link: ${indexRelative}`,
765 + }
else if (
!indexStats.
isFile()) {
766 + diagnostics.
push(
diagnostic(
767 + "bundle.expected-file",
769 + `Expected a regular index.md: ${indexRelative}`,
773 + path: indexRelative,
774 + markdown:
readFileSync(indexAbsolute,
"utf8"),
777 + scanBundleAssets(bundleAbsolute, bundleRelative, diagnostics);
781 + sources: sources.
sort((left, right)
=> left.path.
localeCompare(right.path)),
782 + diagnostics: diagnostics.
sort(compareDiagnostics),
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:
794 +export function indexBundleDocuments(
795 + sources
: readonly BundleDocumentSource[],
797 +)
: BundleDocumentIndex {
798 + const documents
: BundleDocumentRecord[]
= [];
799 + const graphEligible
: BundleDocumentRecord[]
= [];
800 + const diagnostics
: Diagnostic[]
= [];
802 + const item
of [
...sources].
sort((left, right)
=> 803 + left.path.
localeCompare(right.path)
807 + const parsed
= parseAuthoredDocument(item.markdown, prefix);
808 + let pathValid
= true;
810 + validateDocumentPath(item.path, parsed.metadata, prefix);
813 + diagnostics.
push(
diagnostic(
816 + (error
as Error).message,
821 + metadata: parsed.metadata,
822 + frontmatter: parsed.frontmatter,
824 + documents.
push(record);
825 + if (pathValid) graphEligible.
push(record);
827 + const value
= error
as SystemDocumentError | MarkdownDocumentError;
828 + diagnostics.
push(
diagnostic(
829 + "document.metadata",
831 + `${value.code}: ${value.message}`,
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)
?? []),
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",
851 + `Duplicate ID ${id}: ${paths.join(", ")}`,
856 + const unique
= new Map(
858 + .
filter(([, records])
=> records.
length === 1)
859 + .
map(([id, records])
=> [id, records[
0]
!]
as const),
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",
870 + `${document.metadata.id} must reference ${expectedType}; ${targetId} is ${referencedType}`,
872 + }
else if (
!target) {
873 + diagnostics.
push(
diagnostic(
874 + "graph.dangling-reference",
876 + `${document.metadata.id} references missing ${targetId}`,
878 + }
else if (target.metadata.
type !== expectedType) {
879 + diagnostics.
push(
diagnostic(
880 + "graph.forbidden-edge",
882 + `${document.metadata.id} must reference ${expectedType}; ${targetId} is ${target.metadata.type}`,
886 + if (
document.metadata.
type === "plan" && document.metadata.roadmap) {
887 + const roadmap
= unique.
get(
document.metadata.roadmap);
889 + roadmap?.metadata.
type === "roadmap" 890 + && roadmap.metadata.spec
!== document.metadata.spec
892 + diagnostics.
push(
diagnostic(
893 + "graph.forbidden-edge",
895 + `${document.metadata.roadmap} belongs to ${roadmap.metadata.spec}, not ${document.metadata.spec}`,
902 + diagnostics: diagnostics.
sort(compareDiagnostics),
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,
913 +)
: readonly Diagnostic[] {
914 + const baseline
= new Set(
915 + indexBundleDocuments(current, prefix).diagnostics.
map(diagnosticIdentity),
917 + const next
= indexBundleDocuments(
919 + ...current.
filter((source)
=> source.path
!== candidate.path),
924 + return next.diagnostics.
filter(
926 + item.path
=== candidate.path
927 + || (
!baseline.
has(
diagnosticIdentity(item))
928 + && item.
code !== "graph.duplicate-id"),
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**
942 +mise run test
-- extensions/the-system/__tests__/markdown.test.ts \
943 + extensions/the-system/__tests__/documents.test.ts
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**
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" 957 +###
Task 3: Migrate Initialization And Doctor To Schema V2 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:
973 + readFileSync(path.
join(project,
".system/config.json"),
"utf8"),
974 + "{\n\t\"prefix\": \"PX\",\n\t\"schemaVersion\": 2\n}\n",
977 + lstatSync(path.
join(project,
".system/system.css"), {
978 + throwIfNoEntry:
false,
984 +Add a migration fixture containing:
987 +{
"prefix":
"PX",
"schemaVersion":
1,
"styleVersion":
1 }
990 +and `.system/system.css`.
992 +Assert inspection reports exactly:
996 + ".system/config.json schemaVersion 1 -> 2; remove styleVersion",
997 + ".system/system.css remove obsolete machine-owned asset",
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.
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**
1025 +mise run test
-- extensions/the-system/__tests__/init.test.ts \
1026 + extensions/the-system/__tests__/doctor.test.ts
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:
1036 +export type SystemConfig = Readonly<{
1038 + schemaVersion
: number;
1042 +`parseSystemConfig` accepts only `prefix` and `schemaVersion`.
1044 +Remove `STYLE_VERSION`.
1046 +In `documents.ts`, add one shared inspection-only parser:
1049 +export type InspectedSystemConfig = Readonly<{
1050 + config
: SystemConfig;
1051 + legacyStyleVersion
?: number;
1054 +export function inspectSystemConfig(
1056 +)
: InspectedSystemConfig {
1058 + return { config:
parseSystemConfig(source) };
1059 + }
catch (currentError) {
1060 + let parsed
: unknown;
1062 + parsed
= JSON.
parse(source);
1064 + throw currentError;
1066 + const duplicates
= duplicateTopLevelKeys(source);
1067 + if (duplicates.
length > 0)
throw currentError;
1068 + let value
: Record<
string,
unknown>;
1070 + value
= objectValue(parsed,
"Legacy config");
1071 + exactKeys(value, [
"prefix",
"schemaVersion",
"styleVersion"]);
1073 + throw currentError;
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,
1085 + legacyStyleVersion: value.styleVersion
as number,
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:
1100 +export type MachineState = Readonly<{ schemaVersion
: number }>;
1101 +export const DEFAULT_MACHINE_STATE
: MachineState = Object.
freeze({
1102 + schemaVersion: SCHEMA_VERSION,
1106 +Change `InitializationResult` to include:
1109 +removed: readonly string[];
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`:
1119 +for (
const item
of result.changed)
console.
log(
`WROTE ${item}
`);
1120 +for (
const item
of result.removed)
console.
log(
`REMOVED ${item}
`);
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:
1130 +const discovery
= discoverDocumentBundles(
root);
1131 +diagnostics.
push(
...discovery.diagnostics);
1133 + const index
= indexBundleDocuments(discovery.sources, prefix);
1134 + diagnostics.
push(
...index.diagnostics);
1135 + specIds
= new Set(
1137 + .
filter((document)
=> document.metadata.
type === "spec")
1138 + .
map((document)
=> document.metadata.
id),
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**
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
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 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:
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)}` 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";
1198 + id:
"PX-SPEC-001",
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**
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:
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",
1236 + const result
= await preflightFileMutation(
1239 + { path: relative, content:
"replacement" },
1242 + assert.
equal(result?.block,
undefined, relative);
1243 + assert.
equal(approvals,
1, relative);
1248 +- [ ] **Step 3: Run runtime tests to verify RED**
1251 +mise run test
-- extensions/the-system/__tests__/system.test.ts
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:
1263 +type GovernedDocumentPath = Readonly<{
1264 + directory
: "specs" | "roadmaps" | "plans" | "issues" | "research";
1270 +const governedDocumentPath = (
1272 +)
: GovernedDocumentPath | undefined => {
1274 + /^\.system\/(specs|roadmaps|plans|issues|research)\/([^/]+)\/(.+)$/.
exec(
1277 + if (
!match)
return undefined;
1279 + directory: match[
1]
as GovernedDocumentPath[
"directory"],
1280 + bundle: match[
2]
!,
1282 + index: match[
3]
=== "index.md",
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:
1296 +type ResolvedBundleMutation = Readonly<{
1297 + location
: GovernedDocumentPath;
1298 + metadata
?: DocumentMetadata;
1299 + findings
: readonly Diagnostic[];
1302 +const resolveBundleMutation = (
1305 + content
: string | undefined,
1306 +)
: ResolvedBundleMutation => {
1307 + const location
= governedDocumentPath(relative);
1310 + `Authored paths require .system/<type>/<ID>-<slug>/<file>: ${relative}`,
1313 + const prefix
= projectPrefix(
root);
1314 + const discovery
= discoverDocumentBundles(
root);
1315 + const bundlePath
= `.system/${location.directory}/${location.bundle}`;
1316 + const localDiscovery
= discovery.diagnostics.
filter(
1318 + item.path
=== bundlePath
|| item.path.
startsWith(
`${bundlePath}/`),
1322 + && item.path
=== bundlePath
1323 + && item.
code === "bundle.missing-index"),
1325 + if (localDiscovery.
length > 0) {
1328 + findings: localDiscovery,
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 },
1341 + const parsed
= parseAuthoredDocument(content, prefix);
1344 + metadata: parsed.metadata,
1349 + const indexPath
= `${bundlePath}/index.md`;
1350 + const owner
= discovery.sources.
find((source)
=> source.path
=== indexPath);
1353 + `Bundle requires a valid index.md before assets: ${bundlePath}`,
1356 + const indexed
= indexBundleDocuments(discovery.sources, prefix);
1357 + const findings
= indexed.diagnostics.
filter(
1358 + (item)
=> item.path
=== indexPath,
1360 + const document
= indexed.documents.
find(
1361 + (item)
=> item.path
=== indexPath,
1364 + throw new Error(
`Bundle index is invalid: ${indexPath}`);
1368 + metadata:
document.metadata,
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:
1381 +const typedDirectory
= 1382 + /^\.system\/(specs|roadmaps|plans|issues|research)(?:\/|$)/.
test(relative);
1383 +if (
!typedDirectory)
return undefined;
1385 +const location
= governedDocumentPath(relative);
1388 + `The System requires document bundles at .system/<type>/<ID>-<slug>/<file>: ${relative}.`,
1392 +let content
: string | undefined;
1393 +if (location.
index) {
1395 + content
= candidateContent(target, kind, input);
1398 + `The System candidate validation failed: ${ 1399 + error instanceof Error ? error.message : String(error) 1405 +let resolved
: ResolvedBundleMutation;
1407 + resolved
= resolveBundleMutation(
root, relative, content);
1410 + `The System candidate validation failed: ${ 1411 + error instanceof Error ? error.message : String(error) 1415 +if (resolved.findings.
length > 0) {
1416 + return blocked(
diagnosticsReason(resolved.findings));
1418 +if (
!resolved.metadata) {
1420 + `The System could not determine bundle ownership: ${relative}.`,
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;
1432 + `The System blocked existing human-owned ${relative}: interactive UI is unavailable.`,
1435 +const approve
= `Approve once: ${kind} ${relative}`;
1436 +const deny
= `Deny: keep ${relative} unchanged`;
1437 +const decision
= await ui.
select(
"The System ownership approval", [
1441 +if (decision
=== approve)
return undefined;
1444 + ? `The System ownership approval was denied for ${relative}.` 1445 + : `The System ownership approval was cancelled for ${relative}.`,
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:
1469 +.system/specs/<bundle>/<any-path>
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;
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**
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
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:
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" 1521 +The committed tree must have doctor, initialization, and runtime on the same bundle model.
1523 +###
Task 5: Update The Document And Initialization Authorities 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:
1539 + const contract
of [
1540 + "<ID>-<slug>/index.md",
1541 + "leading YAML frontmatter",
1546 + "definition lists",
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(
1557 + /system-meta|\.\.\/system\.css|authored HTML shell|forbid remote/i,
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**
1574 +mise run test
-- extensions/the-system/__tests__/workflow-skills.test.ts
1577 +Expected: FAIL on old HTML and CSS instructions.
1579 +- [ ] **Step 3: Rewrite `system-documents`**
1581 +Keep it the single authority.
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:
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.
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:
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**
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
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**
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" 1664 +###
Task 6: Verify The Phase Boundary 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**
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' 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**
1692 +mise run test
-- extensions/the-system/__tests__
1695 +Expected: all The System suites PASS.
1697 +- [ ] **Step 3: Run retained browser regression tests**
1700 +mise //extensions/the-system:e2e
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**
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
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**
1744 +git diff --stat HEAD~4..HEAD
-- \
1745 + extensions/the-system package-lock.json
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.
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.
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.