repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs(the-system): define markdown bundle authority

b5c6654accdc7dd66b35be98c7cd40037f2fef22

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (5)

extensions/the-system/CHANGELOG.md

Modified
1 1 # Changelog
3 +## Unreleased
5 +- Migrate The System documents to rich Markdown bundles with YAML graph metadata,
6 + config-only machine state, doctor validation, and file-level spec ownership.
3 8 ## 0.0.3
5 10 - Resolve pi-ext conflict stack; retire superpowers.

extensions/the-system/README.md

Modified
60 60 It rejects full HTML documents in `options[].html` with an agent-facing fix message.
61 61 It returns `action`, `selected`, `notes`, and `annotations`.
62 62 It also ships skills from `extensions/the-system/skills` through Pi package resources.
64 +## Project documents (Phase 6)
66 +The System stores each authored document as a bundle:
68 +```text
69 +.system/<type>/<ID>-<slug>/index.md
70 +```
72 +The matching typed directory is `specs`, `roadmaps`, `plans`, `issues`, or
73 +`research`. `index.md` starts with YAML frontmatter, which is the graph
74 +authority; every other regular file below that bundle is a document-owned asset.
75 +The shared rich Markdown profile supports GFM, Mermaid, TeX, definition lists,
76 +GitHub alerts, and trusted raw HTML. Remote references and cross-bundle links
77 +are allowed.
79 +Run `/system-doctor` to report configuration, bundle structure, frontmatter and
80 +graph findings without mutation. Run `/system-init` only to explicitly initialize
81 +or upgrade a project. `config.json` is the only machine-owned file. An approved
82 +upgrade removes obsolete `.system/system.css`; new initialization never creates
83 +or copies CSS.
85 +`SYSTEM.md`, `MISSION.md`, and `RULES.md` remain human-owned core law. Humans
86 +also own every existing file in a spec bundle, so runtime governance requires one
87 +explicit approval before mutating one. Agents may author roadmaps and plans for
88 +review and maintain issues and research, subject to bundle and graph validation.
90 +Renderer/view commands and lifecycle authoring migration arrive in later roadmap
91 +phases; this phase exposes only the bundle kernel, initialization, doctor, and
92 +runtime ownership rules.

extensions/the-system/__tests__/workflow-skills.test.ts

Modified
109 109 "Approve writing .system/RULES.md?",
110 110 "Approve writing .system/SYSTEM.md?",
111 111 "scripts/doctor.mjs",
112 + "config.json is the only machine-owned file",
113 + "index.md and assets",
114 + "Humans own core laws and every existing file in a spec bundle.",
115 + "removal of obsolete machine-owned `system.css`",
116 + "No new initialization creates or copies CSS.",
113 118 assert.ok(init.includes(contract), `missing init contract: ${contract}`);
114 119 for (const file of ["MISSION.md", "RULES.md", "SYSTEM.md"])
142 147 for (const contract of [
143 148 "single document-authoring authority",
144 - "../system.css",
145 - "system-meta",
146 - "SPEC|ROADMAP|PLAN|ISSUE|RESEARCH",
147 - "Metadata is the reference authority",
148 - "spec-owned mockup",
149 - "Never open a browser or editor automatically",
149 + "<ID>-<slug>/index.md",
150 + "leading YAML frontmatter",
151 + "source order",
152 + "GFM",
153 + "Mermaid",
154 + "TeX",
155 + "definition lists",
156 + "GitHub alerts",
157 + "raw HTML",
158 + "existing file inside a spec bundle",
159 + "relative bundle assets",
150 160 "scripts/doctor.mjs",
152 - assert.ok(
153 - documents.includes(contract),
154 - `missing document contract: ${contract}`,
155 - );
156 - assert.doesNotMatch(
157 - documents,
158 - /initialize|SYSTEM\.md|MISSION\.md|RULES\.md/i,
159 - );
162 + assert.ok(documents.includes(contract), contract);
163 + assert.doesNotMatch(documents, /authored HTML shell|forbid remote/i);
162 166 it("discovers phase resources from both package manifests", async () => {

extensions/the-system/skills/system-documents/SKILL.md

Modified
2 2 name: system-documents
3 -description: Apply The System HTML, metadata, ID, reference, mockup, validation, and browser-review contracts
3 +description: Apply The System Markdown-bundle, graph, asset, ownership, and validation contracts
6 6 # System Documents
11 11 ## Preconditions
13 13 - Discover the project root from the nearest `.jj` and `.git` markers; stop when they disagree.
14 -- Read `.system/config.json`; require its approved prefix and current schema/style versions.
14 +- Read `.system/config.json`; require its approved prefix and current schema version.
15 15 - Resolve every target below the project root and reject traversal.
16 -- Inspect existing filenames and metadata before allocating an ID.
16 +- Inspect existing bundle paths and frontmatter before allocating an ID.
18 -## IDs and paths
18 +## IDs and bundle paths
20 20 Use `<PREFIX>-(SPEC|ROADMAP|PLAN|ISSUE|RESEARCH)-<SEQUENCE>`.
21 21 Start sequence text at three digits, permit growth past 999, and use the next unused value for that type.
22 22 Use lowercase ASCII slugs matching `[a-z0-9]+(?:-[a-z0-9]+)*`.
23 -Write `<ID>-<slug>.html` only in its matching `.system/specs|roadmaps|plans|issues|research` directory.
25 -## HTML source
24 +An authored document lives only at:
27 -Every authored document is complete, formatted, directly editable HTML with:
26 +```text
27 +.system/<type>/<ID>-<slug>/index.md
28 +```
29 -- `<!doctype html>`, `<html lang="en">`, UTF-8 charset, viewport, and a nonempty title;
30 -- exactly one `<link rel="stylesheet" href="../system.css">`;
31 -- header followed by main containing one section;
32 -- semantic headings, paragraphs, lists, tables, asides, figures, and details where appropriate;
33 -- one readable `<script type="application/json" id="system-meta">` block.
30 +`<type>` must match the ID and frontmatter type: `specs`, `roadmaps`, `plans`,
31 +`issues`, or `research`. A bundle contains its `index.md` plus relative bundle
32 +assets in that same directory or its nested directories. Do not author flat
33 +files in a typed directory or a second authored `index.md` below a bundle.
35 -Inline CSS may express document-specific layout but may not redefine shared Nugu colors, typography, breakpoints, or components.
36 -Inline JavaScript must be optional, dependency-free progressive disclosure, filtering, or a tiny explanation.
37 -Forbid network APIs, browser storage, dynamic import, external scripts, event-handler attributes, executable URL schemes, iframes, objects, embeds, meta refresh, remote runtime assets, generated SVG sludge, and diagram libraries.
38 -HTTPS anchors remain allowed navigation.
35 +## Markdown and frontmatter
40 -## Metadata and graph
42 -Metadata is the reference authority; prose links never create graph edges.
43 -Use exact keys only:
37 +Every `index.md` begins with one leading YAML frontmatter map. YAML frontmatter
38 +is the graph authority; prose links never create graph edges. Preserve its
39 +source order and arbitrary extra fields. Known fields create the validated graph
40 +projection:
45 42 - spec: `id`, `type`;
46 43 - roadmap: `id`, `type`, one `spec`;
47 -- plan: `id`, `type`, one `spec`, plus `roadmap` and positive `phase` together when phase-scoped;
48 -- issue: `id`, `type`, `open|fixed` status, unique `specs` array;
49 -- research: `id`, `type`, ISO `capturedAt`, optional unique HTTPS `sources`.
44 +- plan: `id`, `type`, one `spec`, plus `roadmap` and positive `phase` together
45 + when phase-scoped;
46 +- issue: `id`, `type`, `open|fixed` `status`, and unique `specs` array;
47 +- research: `id`, `type`, ISO `capturedAt`, and optional unique-string `sources`.
51 -Specs are leaf truth and have no outgoing system-document metadata.
52 -Roadmaps point to one spec.
53 -Plans point to one spec and optionally one phase of a roadmap for that same spec.
54 -Issues point only to specs; an empty array is allowed while the violated contract is unknown.
55 -Tests use a language-appropriate `SYSTEM-SPEC: <SPEC-ID>` comment.
49 +Specs are leaf truth and have no outgoing system-document metadata. Roadmaps
50 +point to one spec. Plans point to one spec and optionally one phase of a roadmap
51 +for that same spec. Issues point only to specs; an empty array is allowed while
52 +the violated contract is unknown. Tests use a language-appropriate
53 +`SYSTEM-SPEC: <SPEC-ID>` comment.
57 -## Spec-owned mockups
55 +Use the complete rich Markdown profile: CommonMark plus GFM tables, task lists,
56 +strikethrough, autolinks, and footnotes; fenced code including Mermaid; inline
57 +and display TeX; definition lists; GitHub alerts; and trusted raw HTML. Remote
58 +references and cross-bundle links are allowed. Keep source content human-readable
59 +and directly editable.
59 -Persist only a human-accepted spec-owned mockup.
60 -Place it beside its owner as `<spec-stem>-mockup-<option-slug>.html` and link it relatively from the spec.
61 -A mockup is a constituent asset, not an authored graph node: do not add `system-meta`.
62 -Keep it standalone, editable, dependency-free, and subject to the same active-resource prohibitions.
61 +## Bundle assets and ownership
64 -## Validate and review
63 +Use relative bundle assets from `index.md`. An accepted `mockup-*.html` file is
64 +a bundle-relative asset owned by its spec, not an authored graph node.
66 -After writing or materially editing a document, run the bundled `../../scripts/doctor.mjs` through Node with `--experimental-strip-types`.
67 -Do not hide, reorder, or silently repair findings.
68 -Print the exact source path and ask whether browser review is wanted.
69 -Never open a browser or editor automatically.
70 -Only use an explicitly approved, shell-free local-file opener when one is available; otherwise leave the source path as the review interface.
66 +Humans own core laws and every existing file inside a spec bundle. An existing
67 +file inside a spec bundle requires the runtime's one explicit ownership approval
68 +before mutation. New assets require an existing valid owning bundle. Agents may
69 +author roadmaps and plans for review and maintain issues and research; their
70 +indexes still must satisfy bundle and graph validation.
72 +## Validate
74 +After writing or materially editing an index or bundle asset, run the bundled
75 +`../../scripts/doctor.mjs` through Node with `--experimental-strip-types`.
76 +Do not hide, reorder, or silently repair findings. Viewing and browser review
77 +are not part of this authority; a later renderer phase owns them.

extensions/the-system/skills/the-system-init/SKILL.md

Modified
10 10 ## Safety
12 -Before any write, explain that `.system/SYSTEM.md`, `.system/MISSION.md`, and `.system/RULES.md` are privileged instructions future agents may receive as authority.
13 -Tell the user not to place secrets, credentials, raw private data, or binary bytes in them.
14 -Preserve unrelated dirty work.
15 -Never overwrite an existing core file.
16 -Never silently repair malformed config, root conflict, prefix conflict, newer project version, or unsafe path.
17 -Resolve `../../scripts/init.mjs` and `../../scripts/doctor.mjs` against this skill directory.
18 -Use absolute paths with `node --no-warnings --experimental-strip-types`.
12 +Before any write, explain that `.system/SYSTEM.md`, `.system/MISSION.md`, and
13 +`.system/RULES.md` are privileged instructions future agents may receive as
14 +authority. Tell the user not to place secrets, credentials, raw private data, or
15 +binary bytes in them.
17 +Preserve unrelated dirty work. Never overwrite an existing core file. Never
18 +silently repair malformed config, root conflict, prefix conflict, newer project
19 +version, or unsafe path. Resolve `../../scripts/init.mjs` and
20 +`../../scripts/doctor.mjs` against this skill directory. Use absolute paths with
21 +`node --no-warnings --experimental-strip-types`.
20 23 ## Inspect
22 25 Use `scripts/init.mjs inspect`:
23 26 `node --no-warnings --experimental-strip-types <absolute-init-path> inspect <current-cwd>`.
24 -Pass a command prefix only as a proposal, not approval.
25 -Report every `ROOT`, `PREFIX`, `CORE`, `CREATE`, and `UPGRADE` line; stop on `ERROR`.
26 -Read existing `.system`, README/purpose docs, agent instructions, package/language manifests, build files, task config, conventional tests, top-level structure, and security/data/release config without mutation.
27 -Summarize facts, conflicts, and unknowns; never ask the user to repeat a consistent inspected fact.
27 +Pass a command prefix only as a proposal, not approval. Report every `ROOT`,
28 +`PREFIX`, `CORE`, `CREATE`, and `UPGRADE` line; stop on `ERROR`.
30 +Read existing `.system`, README/purpose docs, agent instructions, package/language
31 +manifests, build files, task config, conventional tests, top-level structure, and
32 +security/data/release config without mutation. Summarize facts, conflicts, and
33 +unknowns; never ask the user to repeat a consistent inspected fact.
29 35 ## Interview
31 -For first initialization or missing core truth, ask one focused question at a time and wait.
32 -Cover unresolved topics in order: purpose/outcome; audience/operators; non-goals/boundaries; engineering constraints/environments; security/trust; data ownership/retention/privacy/migration; tests/verification; release expectations/compatibility/rollout/rollback.
33 -Challenge vagueness or conflict with one follow-up at a time.
34 -When all cores exist on rerun, preserve settled truth and ask only about a machine upgrade or explicit requested gap.
37 +For first initialization or missing core truth, ask one focused question at a time and wait. Cover unresolved topics in order: purpose/outcome;
38 +audience/operators; non-goals/boundaries; engineering constraints/environments;
39 +security/trust; data ownership/retention/privacy/migration; tests/verification;
40 +release expectations/compatibility/rollout/rollback. Challenge vagueness or
41 +conflict with one follow-up at a time.
36 -## Prefix and machine assets
43 +When all cores exist on rerun, preserve settled truth and ask only about a
44 +machine upgrade or explicit requested gap.
46 +## Prefix and machine state
48 +Propose one prefix from prompt argument, repository name, package name, or title,
49 +in that order. Require `[A-Z][A-Z0-9]{1,7}` and ask `Approve project prefix
50 +PREFIX?`. Only explicit yes approves; otherwise request one replacement,
51 +validate, and ask again. Existing config prefix is authoritative; stop rather
52 +than change a conflict.
54 +config.json is the only machine-owned file. Document bundles contain index.md and assets.
55 +New initialization creates the `.system` topology, typed document directories,
56 +and config; it does not create or copy CSS. No new initialization creates or copies CSS.
38 -Propose one prefix from prompt argument, repository name, package name, or title, in that order.
39 -Require `[A-Z][A-Z0-9]{1,7}` and ask `Approve project prefix PREFIX?`.
40 -Only explicit yes approves; otherwise request one replacement, validate, and ask again.
41 -Existing config prefix is authoritative; stop rather than change a conflict.
42 58 After approval, use `scripts/init.mjs apply`:
43 59 `node --no-warnings --experimental-strip-types <absolute-init-path> apply <root> <approved-prefix>`.
44 -Relay every `WROTE` and `PENDING` line.
45 -If pending, display every config transition and CSS replacement, then ask `Approve the reported machine-owned config/CSS upgrade?`.
46 -On yes, use `scripts/init.mjs upgrade`:
60 +Relay every `WROTE`, `REMOVED`, and `PENDING` line. If pending, display every
61 +config transition and the removal of obsolete machine-owned `system.css` before
62 +asking `Approve the reported machine-owned config upgrade?`. On yes, use
63 +`scripts/init.mjs upgrade`:
47 64 `node --no-warnings --experimental-strip-types <absolute-init-path> upgrade <root> <approved-prefix>`.
48 -On no, preserve assets, state doctor remains non-green, and do not claim completion.
65 +On no, preserve assets, state doctor remains non-green, and do not claim
66 +completion.
50 68 ## Separate core approvals
52 -Use inspected facts and answers; never invent an unanswered rule.
53 -Do not modify, reformat, or seek blanket reapproval for a `preserve` core.
54 -For missing mission, show the whole project-specific draft with `# Mission`, `## Purpose`, `## Audience`, `## Outcomes`, and `## Non-goals`.
55 -Ask exactly: `Approve writing .system/MISSION.md?`
56 -Revise and redisplay when requested.
57 -Write .system/MISSION.md only after explicit approval of that displayed draft.
58 -For missing rules, show the whole project-specific draft with `# Rules`, `## Engineering constraints`, `## Security and data`, `## Testing`, and `## Release`.
59 -Ask exactly: `Approve writing .system/RULES.md?`
60 -Revise and redisplay when requested.
61 -Write .system/RULES.md only after explicit approval of that displayed draft.
70 +Use inspected facts and answers; never invent an unanswered rule. Do not modify,
71 +reformat, or seek blanket reapproval for a `preserve` core.
73 +For missing mission, show the whole project-specific draft with `# Mission`,
74 +`## Purpose`, `## Audience`, `## Outcomes`, and `## Non-goals`. Ask exactly:
75 +`Approve writing .system/MISSION.md?` Revise and redisplay when requested. Write .system/MISSION.md only after explicit approval of that displayed draft.
77 +For missing rules, show the whole project-specific draft with `# Rules`,
78 +`## Engineering constraints`, `## Security and data`, `## Testing`, and
79 +`## Release`. Ask exactly: `Approve writing .system/RULES.md?` Revise and redisplay when requested. Write .system/RULES.md only after explicit approval of that displayed draft.
62 81 For missing topology, show this complete canonical draft without project facts:
64 83 ```markdown
69 88 MISSION.md defines why this project exists.
70 89 RULES.md defines how work must be done.
71 90 Approved specs define what behavior must exist.
72 -Metadata is the authority for system-document relationships.
91 +YAML frontmatter is the authority for system-document relationships.
74 93 ## Ownership
76 -Humans own SYSTEM.md, MISSION.md, RULES.md, specs, and accepted spec-owned mockups.
77 -Agents may draft roadmaps and plans for human review and maintain issues and research.
78 -Machine-owned config.json and system.css change only through initialization.
95 +Humans own core laws and every existing file in a spec bundle.
96 +Agents author roadmaps/plans for review and maintain issues/research.
97 +config.json is machine-owned.
80 99 ## Documents
82 -Authored documents are editable HTML in matching .system directories.
83 -Each uses ../system.css and exactly one system-meta JSON block.
101 +Authored documents live at .system/<type>/<ID>-<slug>/index.md.
102 +Every other file in that directory belongs to the document.
84 103 Specs are leaf truth.
85 104 Roadmaps reference one spec; plans reference one spec and optionally one matching roadmap phase; issues reference violated specs.
86 105 Tests use SYSTEM-SPEC comments.
87 -Accepted mockups live beside and belong to their spec.
89 107 ## Safety
92 110 Invalid or outdated state is reported and never silently repaired.
95 -Ask exactly: `Approve writing .system/SYSTEM.md?`
96 -Revise and redisplay when requested.
97 -Write .system/SYSTEM.md only after explicit approval of that displayed draft.
98 -Denied approval leaves the core absent and initialization incomplete.
113 +Ask exactly: `Approve writing .system/SYSTEM.md?` Revise and redisplay when
114 +requested. Write .system/SYSTEM.md only after explicit approval of that displayed draft. Denied approval leaves the core absent and initialization incomplete.
100 116 ## Validate
102 118 Use `scripts/doctor.mjs` after approved writes:
103 119 `node --no-warnings --experimental-strip-types <absolute-doctor-path> <root>`.
104 -Preserve report order; never hide or automatically repair findings.
105 -Exit 0 with `OK The System is valid` means completion; exit 1 means incomplete or invalid.
106 -Report root, prefix, created machine paths, preserved/new cores, upgrade decision, and doctor status.
107 -Never launch a browser or editor.
108 -Do not commit unless separately asked.
120 +Preserve report order; never hide or automatically repair findings. Exit 0 with
121 +`OK The System is valid` means completion; exit 1 means incomplete or invalid.
122 +Report root, prefix, created machine paths, preserved/new cores, upgrade decision,
123 +and doctor status. Never launch a browser or editor. Do not commit unless
124 +separately asked.