repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs(super): roadmap the-system migration

bf88c2c467631781d4235ea8d83fad86c32268e7

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (2)

docs/super/plans/2026-07-11-the-system-phase-1-hard-rename.html

Added
new file mode 100644
1 +<!doctype html>
2 +<html lang="en">
3 +<head>
4 +<meta charset="utf-8">
5 +<meta name="viewport" content="width=device-width, initial-scale=1">
6 +<title>The System Phase 1 hard rename plan</title>
7 +<style>
8 +:root { color-scheme:light dark; --fg:#121212; --bg:#ededed; --panel:#dbdbdb; --accent:#ae2eae; --ui:#922792; }
9 +@media(prefers-color-scheme:dark) { :root { --fg:#ededed; --bg:#121212; --panel:#242424; --accent:#d151d1; --ui:#d86dd8; } }
10 +* { box-sizing:border-box; }
11 +body { margin:0; background:var(--bg); color:var(--fg); font:14px/1.5 ui-monospace,SFMono-Regular,Consolas,monospace; }
12 +article { width:min(100% - 2rem,940px); margin:1rem auto 3rem; border:3px solid var(--fg); box-shadow:9px 9px 0 var(--ui); }
13 +header,section { padding:1.2rem; border-bottom:2px solid var(--fg); }
14 +header { background:var(--panel); border-bottom-width:3px; }
15 +h1 { margin:.2rem 0 0; font:900 clamp(1.7rem,6vw,3.2rem)/.95 system-ui; text-transform:uppercase; }
16 +h2 { color:var(--accent); font:900 1rem/1 system-ui; letter-spacing:.1em; text-transform:uppercase; }
17 +code,pre { background:var(--panel); }
18 +code { padding:.1rem .3rem; }
19 +pre { overflow:auto; padding:1rem; border-left:6px solid var(--ui); }
20 +li { margin:.4rem 0; }
21 +a { color:var(--accent); font-weight:900; }
22 +@media(max-width:600px) { article { width:calc(100% - 1rem); margin:.5rem; box-shadow:5px 5px 0 var(--ui); } }
23 +</style>
24 +</head>
25 +<body>
26 +<article>
27 +<header>
28 +<p><strong>Phase 1 implementation plan · 2026-07-11</strong></p>
29 +<h1>Hard rename baseline</h1>
30 +<p><a href="../roadmaps/2026-07-11-the-system-roadmap.html">Roadmap</a> · <a href="../specs/2026-07-11-the-system-design.html">Spec</a></p>
31 +<p>Rename Super to The System without changing task, mockup, or skill behavior.</p>
32 +</header>
33 +<main>
34 +<section>
35 +<h2>Files</h2>
36 +<ul>
37 +<li>Rename <code>extensions/super/</code> to <code>extensions/the-system/</code>.</li>
38 +<li>Modify <code>extensions/the-system/package.json</code> and <code>README.md</code>.</li>
39 +<li>Modify renamed tests only where names or resolved paths expose branding.</li>
40 +<li>Modify root <code>package.json</code>, <code>package-lock.json</code>, <code>README.md</code>, and <code>tsconfig.json</code>.</li>
41 +<li>Modify <code>scripts/test_extensions_static_check.mjs</code> and <code>scripts/extensions.mjs</code>.</li>
42 +<li>Modify current example <code>extensions/shame/README.md</code>.</li>
43 +<li>Do not modify <code>docs/super/**</code> or historical changelog entries.</li>
44 +</ul>
45 +</section>
46 +<section>
47 +<h2>Task 1 · Freeze current behavior</h2>
48 +<ol>
49 +<li>Run <code>mise run test -- super</code> and record the passing baseline.</li>
50 +<li>Run <code>mise run check</code> and record the passing baseline.</li>
51 +<li>Inspect <code>git status --short</code>; preserve unrelated <code>CHANGELOG.md</code> work.</li>
52 +</ol>
53 +</section>
54 +<section>
55 +<h2>Task 2 · Rename package and directory</h2>
56 +<ol>
57 +<li>Move the directory with <code>mv extensions/super extensions/the-system</code>.</li>
58 +<li>Change package name to <code>@bugabinga/pi-ext-the-system</code>.</li>
59 +<li>Change extension title, description, and keywords from Super branding to The System branding.</li>
60 +<li>Rename test suite labels from <code>super</code> to <code>the-system</code> without changing assertions about behavior.</li>
61 +<li>Keep exported function names unless they are user-visible branding; avoid unrelated refactors.</li>
62 +</ol>
63 +</section>
64 +<section>
65 +<h2>Task 3 · Update root integration</h2>
66 +<ol>
67 +<li>Change root skill resource path to <code>extensions/the-system/skills</code>.</li>
68 +<li>Change the root README extension row and resource example.</li>
69 +<li>Replace live static-check and extension-script expectations with the new path.</li>
70 +<li>Change the TypeScript exclusion from <code>extensions/super</code> to <code>extensions/the-system</code> for a behavior-preserving phase; Phase 2 may remove the exclusion when new typed modules arrive.</li>
71 +<li>Change the current Shame README example to <code>@extensions/the-system</code>.</li>
72 +<li>Do not rewrite historical <code>docs/super/**</code> references.</li>
73 +</ol>
74 +</section>
75 +<section>
76 +<h2>Task 4 · Regenerate package lock</h2>
77 +<ol>
78 +<li>Run the existing install task through <code>mise run install</code>.</li>
79 +<li>Verify the lockfile workspace and symlink package entries use <code>extensions/the-system</code> and <code>@bugabinga/pi-ext-the-system</code>.</li>
80 +<li>Verify no live lockfile entry retains the old package.</li>
81 +</ol>
82 +</section>
83 +<section>
84 +<h2>Task 5 · Add scoped no-legacy static contract</h2>
85 +<ol>
86 +<li>Extend <code>scripts/test_extensions_static_check.mjs</code> to reject live <code>extensions/super</code> and <code>pi-ext-super</code> references.</li>
87 +<li>Exclude <code>docs/super/**</code> and historical changelog text from that scan.</li>
88 +<li>Use Node filesystem APIs already present in the script; add no dependency or shell helper.</li>
89 +<li>Run <code>mise run check</code>; confirm the renamed package and historical allowlist both pass.</li>
90 +</ol>
91 +</section>
92 +<section>
93 +<h2>Task 6 · Verification</h2>
94 +<ol>
95 +<li>Run <code>mise run fmt</code>.</li>
96 +<li>Run <code>mise run test -- the-system</code>.</li>
97 +<li>Run the renamed package harness script.</li>
98 +<li>Run <code>mise run check</code>.</li>
99 +<li>Run <code>mise run ci</code>.</li>
100 +<li>Inspect <code>git diff --stat</code> and <code>git diff</code>; verify changes are rename-only and unrelated dirty work is unchanged.</li>
101 +</ol>
102 +</section>
103 +<section>
104 +<h2>Acceptance</h2>
105 +<ul>
106 +<li>Only <code>extensions/the-system</code> exists.</li>
107 +<li>Only <code>@bugabinga/pi-ext-the-system</code> exists in live package metadata.</li>
108 +<li>Task branches, mockups, renderer, and all existing workflow skills pass unchanged.</li>
109 +<li>Real Pi extension harness loads the renamed entrypoint.</li>
110 +<li>Historical <code>docs/super/**</code> remains byte-unchanged.</li>
111 +<li>Full CI passes.</li>
112 +</ul>
113 +</section>
114 +</main>
115 +</article>
116 +</body>
117 +</html>

docs/super/roadmaps/2026-07-11-the-system-roadmap.html

Added
new file mode 100644
1 +<!doctype html>
2 +<html lang="en">
3 +<head>
4 +<meta charset="utf-8">
5 +<meta name="viewport" content="width=device-width, initial-scale=1">
6 +<title>The System implementation roadmap</title>
7 +<style>
8 +:root { color-scheme: light dark; --fg:#121212; --bg:#ededed; --panel:#dbdbdb; --accent:#ae2eae; --ui:#922792; }
9 +@media (prefers-color-scheme:dark) { :root { --fg:#ededed; --bg:#121212; --panel:#242424; --accent:#d151d1; --ui:#d86dd8; } }
10 +* { box-sizing:border-box; }
11 +body { margin:0; background:var(--bg); color:var(--fg); font:14px/1.5 ui-monospace,SFMono-Regular,Consolas,monospace; }
12 +article { width:min(100% - 2rem,980px); margin:1rem auto 3rem; border:3px solid var(--fg); box-shadow:9px 9px 0 var(--ui); }
13 +header,section { padding:clamp(1rem,3vw,1.5rem); border-bottom:2px solid var(--fg); }
14 +header { background:var(--panel); border-bottom-width:3px; }
15 +h1 { margin:.2rem 0 0; font:900 clamp(1.8rem,6vw,3.5rem)/.95 system-ui; text-transform:uppercase; }
16 +h2 { margin:0 0 1rem; color:var(--accent); font:900 1rem/1 system-ui; letter-spacing:.1em; text-transform:uppercase; }
17 +h3 { margin:1rem 0 .4rem; font-size:.9rem; text-transform:uppercase; }
18 +p,li { max-width:82ch; }
19 +.phase { border-left:8px solid var(--ui); }
20 +.phase strong { color:var(--accent); }
21 +code { background:var(--panel); padding:.1rem .3rem; }
22 +a { color:var(--accent); font-weight:900; }
23 +@media(max-width:600px) { article { width:calc(100% - 1rem); margin:.5rem; box-shadow:5px 5px 0 var(--ui); } }
24 +</style>
25 +</head>
26 +<body>
27 +<article>
28 +<header>
29 +<p><strong>Implementation roadmap · 2026-07-11</strong></p>
30 +<h1>The System</h1>
31 +<p><a href="../specs/2026-07-11-the-system-design.html">Design spec</a></p>
32 +<p>Eight independently green phases keep the hard rename, governance kernel, document workflows, and final integration reviewable.</p>
33 +</header>
34 +<main>
35 +<section class="phase">
36 +<h2>Phase 1 · Hard rename baseline</h2>
37 +<p><strong>Outcome:</strong> all existing Super behavior ships under <code>the-system</code> only.</p>
38 +<h3>Scope</h3>
39 +<ul>
40 +<li>Rename extension directory, package, branding, imports, tests, root resources, lockfile entries, static checks, TypeScript config, README rows, and current examples.</li>
41 +<li>Preserve task branches, push-task, mockup, renderer, and existing skills without semantic changes.</li>
42 +<li>Add a scoped static assertion rejecting live old paths while allowing historical <code>docs/super/**</code>.</li>
43 +</ul>
44 +<h3>Out of scope</h3>
45 +<p>Governance, HTML documents, prompts, and new skills.</p>
46 +<h3>Verification</h3>
47 +<p>Renamed focused tests, real Pi harness loading, typecheck, static checks, and full CI.</p>
48 +<h3>Boundary</h3>
49 +<p>The repository remains functionally identical except for the intentional hard public rename.</p>
50 +</section>
52 +<section class="phase">
53 +<h2>Phase 2 · Project and document kernel</h2>
54 +<p><strong>Outcome:</strong> a dormant, pure, tested model understands project roots, config, IDs, metadata, document relationships, and the shared stylesheet.</p>
55 +<h3>Scope</h3>
56 +<ul>
57 +<li>Add <code>documents.ts</code> with native JJ/Git worktree root discovery and conflict detection.</li>
58 +<li>Add normalized governed-path containment.</li>
59 +<li>Define strict config, prefix, ID, slug, filename, and metadata schemas.</li>
60 +<li>Index authored documents and report stable diagnostics for duplicate IDs, filename mismatch, dangling references, and forbidden graph edges.</li>
61 +<li>Validate the narrow authored HTML shell and obvious active-resource violations without executing content.</li>
62 +<li>Add the approved versioned Nugu <code>assets/system.css</code>.</li>
63 +</ul>
64 +<h3>Out of scope</h3>
65 +<p>Runtime hooks and filesystem mutation.</p>
66 +<h3>Verification</h3>
67 +<p>Table-driven unit tests for simple Git, Git worktrees, JJ, colocated/conflicting roots, no VCS, config, IDs, metadata, graph rules, HTML, and CSS tokens.</p>
68 +<h3>Boundary</h3>
69 +<p>New code is unused by runtime; existing extension behavior remains unchanged and CI-green.</p>
70 +</section>
72 +<section class="phase">
73 +<h2>Phase 3 · Doctor vertical slice</h2>
74 +<p><strong>Outcome:</strong> users can inspect any project system without mutation.</p>
75 +<h3>Scope</h3>
76 +<ul>
77 +<li>Add deterministic read-only doctor script using the Phase 2 kernel.</li>
78 +<li>Add <code>system-doctor</code> skill and thin <code>/system-doctor</code> prompt.</li>
79 +<li>Add initial <code>system-documents</code> skill as the single document-authoring authority.</li>
80 +<li>Export package prompts and update exact resource/static checks.</li>
81 +</ul>
82 +<h3>Out of scope</h3>
83 +<p>Initialization, injection, and write gates.</p>
84 +<h3>Verification</h3>
85 +<p>Fixture-tree diagnostics, stable ordering, exit status, no-mutation proof, skill contracts, and real package resource discovery.</p>
86 +<h3>Boundary</h3>
87 +<p>Doctor is independently useful while all existing runtime behavior remains intact.</p>
88 +</section>
90 +<section class="phase">
91 +<h2>Phase 4 · Guided initialization</h2>
92 +<p><strong>Outcome:</strong> <code>/system-init</code> creates or upgrades a valid project system through explicit human decisions.</p>
93 +<h3>Scope</h3>
94 +<ul>
95 +<li>Add thin prompt and <code>the-system-init</code> skill.</li>
96 +<li>Inspect project context and grill one focused question at a time.</li>
97 +<li>Draft and separately approve missing core Markdown files.</li>
98 +<li>Create directories/config and copy bundled CSS.</li>
99 +<li>Make reruns idempotent, core-preserving, and explicit about machine-asset upgrades.</li>
100 +<li>Validate through doctor after writes.</li>
101 +</ul>
102 +<h3>Out of scope</h3>
103 +<p>Automatic runtime injection or write interception.</p>
104 +<h3>Verification</h3>
105 +<p>Skill contract tests, config/CSS copy checks, missing/existing core behavior, prefix handling, and repeat-run fixtures.</p>
106 +<h3>Boundary</h3>
107 +<p>Initialization works as an on-demand agent workflow; the extension still does not alter normal turns.</p>
108 +</section>
110 +<section class="phase">
111 +<h2>Phase 5 · Runtime governance</h2>
112 +<p><strong>Outcome:</strong> initialized projects inject their laws and receive advisory ownership protection.</p>
113 +<h3>Scope</h3>
114 +<ul>
115 +<li>Add <code>system.ts</code> runtime orchestration.</li>
116 +<li>Resolve root per turn and inject bounded existing SYSTEM/MISSION/RULES in stable order.</li>
117 +<li>Notify once per session when initialization or version refresh is needed.</li>
118 +<li>Block edits to existing core files.</li>
119 +<li>Allow new specs and mockups; require UI approval for edits to existing spec-owned files.</li>
120 +<li>Preflight write/edit candidates with shared validation.</li>
121 +<li>Conservatively guard recognizable shell mutations and state the advisory boundary.</li>
122 +</ul>
123 +<h3>Out of scope</h3>
124 +<p>Workflow output migration.</p>
125 +<h3>Verification</h3>
126 +<p>Real event shapes, injection composition, root changes, UI approve/deny/cancel, no-UI failure, candidate validation, and retained task/mockup tests.</p>
127 +<h3>Boundary</h3>
128 +<p>Existing task workflows still function; initialized projects gain coherent governance without hidden repair.</p>
129 +</section>
131 +<section class="phase">
132 +<h2>Phase 6 · Spec authoring and browser review</h2>
133 +<p><strong>Outcome:</strong> brainstorming produces validated brutal HTML specs and separately editable spec-owned mockups.</p>
134 +<h3>Scope</h3>
135 +<ul>
136 +<li>Migrate brainstorming through <code>system-documents</code>.</li>
137 +<li>Add thin <code>/system-spec</code> prompt.</li>
138 +<li>Allocate spec IDs and write semantic HTML linked to shared CSS.</li>
139 +<li>Persist only accepted mockups as adjacent compliant assets.</li>
140 +<li>Add cross-platform shell-free browser opener script.</li>
141 +<li>Print source path and ask before opening; never auto-open browser/editor.</li>
142 +</ul>
143 +<h3>Out of scope</h3>
144 +<p>Roadmaps, plans, implementation, and issues.</p>
145 +<h3>Verification</h3>
146 +<p>Workflow contracts, generated fixtures, approval behavior, mockup ownership, opener argv/platform tests, and generic mockup regressions.</p>
147 +<h3>Boundary</h3>
148 +<p>An approved idea can complete the full design/spec review loop while later lifecycle stages remain on existing behavior.</p>
149 +</section>
151 +<section class="phase">
152 +<h2>Phase 7 · Roadmap, plan, and implementation lifecycle</h2>
153 +<p><strong>Outcome:</strong> approved specs move through HTML roadmaps/plans into execution by PLAN-ID.</p>
154 +<h3>Scope</h3>
155 +<ul>
156 +<li>Migrate writing-roadmaps and writing-plans to validated HTML, exact metadata, and project-local paths.</li>
157 +<li>Add <code>/system-roadmap</code>, <code>/system-plan</code>, and <code>/system-impl</code> prompts.</li>
158 +<li>Update reviewer prompts and downstream skills to read HTML.</li>
159 +<li>Resolve plans by ID and execute one spec or one roadmap phase with existing checkpoints.</li>
160 +</ul>
161 +<h3>Out of scope</h3>
162 +<p>Issue capture.</p>
163 +<h3>Verification</h3>
164 +<p>Prompt delegation, metadata/reference fixtures, phase boundary tests, plan execution resolution, report-only review, and full workflow-skill tests.</p>
165 +<h3>Boundary</h3>
166 +<p>The primary spec-driven development lifecycle is complete and CI-green.</p>
167 +</section>
169 +<section class="phase">
170 +<h2>Phase 8 · Issue memory and integration hardening</h2>
171 +<p><strong>Outcome:</strong> defect capture completes the system and every spec contract is verified.</p>
172 +<h3>Scope</h3>
173 +<ul>
174 +<li>Add general-purpose <code>system-issues</code> skill and <code>/system-issue</code> prompt.</li>
175 +<li>Support empty spec references while the violated contract is unknown; preserve deduplication and sanitized evidence.</li>
176 +<li>Complete startup, doctor, graph, approval, resource discovery, rename, and package integration tests.</li>
177 +<li>Update final current documentation and changelog.</li>
178 +<li>Run final typecheck, focused suites, real extension loading, static checks, and CI.</li>
179 +</ul>
180 +<h3>Out of scope</h3>
181 +<p>Provider-specific research, Git sync, compatibility aliases, and historical document migration.</p>
182 +<h3>Verification</h3>
183 +<p>Issue workflow fixtures, complete behavioral-contract audit against the spec, no live old-path references outside the historical allowlist, and <code>mise run ci</code>.</p>
184 +<h3>Boundary</h3>
185 +<p>The full design is implemented under one public extension with no half-migration or legacy surface.</p>
186 +</section>
187 +</main>
188 +</article>
189 +</body>
190 +</html>