pi-ext bugabingas pi extensions
owned by admin
README Source History Refs Compare Notes Search feat: discover system root by nearest .system marker 2fb83259f7d4f6245d91784f401c50fded182768
Oliver Jan Krylow <oliver@bugabinga.net > · 22 Sep 2026
SSH signature · not checked
Browse files Compare with HEAD
Resolve the active System root as the nearest .system directory at or
above cwd; nested systems override parents, /system init initializes at
cwd, and split Git/JJ roots no longer conflict. Extract board tool
result rendering into a shared helper.
Changed files (22) extensions/the-system/CHANGELOG.md Modified 6 + - Resolve the active System root as the nearest `.system` directory at or above cwd; nested systems override parents, `/system init` initializes at cwd, and split Git/JJ roots no longer conflict.
6 8 - Use rich Markdown bundles with YAML graph metadata, config-only machine state,
7 9 doctor validation, and file-level spec ownership.
8 10 - Add `/system board` with tracked schema-0 operational state, nested plan cards, independent issues, responsive accordions, and human-reviewed `/system assess` proposals.
extensions/the-system/__e2e__/renderer.spec.ts Modified 376 376 function systemFixture ()
: string {
377 377 const root
= mkdtempSync (path.
join (
tmpdir (),
"the-system-render-e2e-" ));
378 378 roots.
push (
root );
379 - mkdirSync (path.
join (
root ,
".git" ));
380 379 for (
const directory
of [
"specs" ,
"phases" ,
"plans" ,
"issues" ,
"research" ])
381 380 mkdirSync (path.
join (
root ,
".system" , directory), { recursive:
true });
extensions/the-system/__tests__/board-server.test.ts Modified 240 240 function fixture ()
: string {
241 241 const root
= mkdtempSync (path.
join (
tmpdir (),
"board-server-" ));
242 242 roots.
push (
root );
243 - mkdirSync (path.
join (
root ,
".git" ));
244 243 for (
const directory
of [
"specs" ,
"phases" ,
"plans" ,
"issues" ,
"research" ])
245 244 mkdirSync (path.
join (
root ,
".system" , directory), { recursive:
true });
246 245 write (
root ,
".system/config.json" ,
'{"prefix":"PX","schemaVersion":0}' );
extensions/the-system/__tests__/board-summary.test.ts Modified 15 15 const project = (board
: string )
: string => {
16 16 const root
= mkdtempSync (path.
join (
tmpdir (),
"system-board-summary-" ));
18 - mkdirSync (path.
join (
root ,
".git" ));
19 18 for (
const file
of [
"SYSTEM.md" ,
"MISSION.md" ,
"RULES.md" ])
20 19 write (
root ,
`.system/${file}` ,
`# ${file}\n` );
21 20 write (
root ,
".system/config.json" ,
'{"prefix":"PX","schemaVersion":0}' );
extensions/the-system/__tests__/bundle-slot-tool.test.ts Modified 11 11 const project = ()
=> {
12 12 const root
= mkdtempSync (path.
join (
tmpdir (),
"system-slot-" ));
14 - mkdirSync (path.
join (
root ,
".git" ));
15 14 for (
const directory
of [
"specs" ,
"phases" ,
"plans" ,
"issues" ,
"research" ])
16 15 mkdirSync (path.
join (
root ,
".system" , directory), { recursive:
true });
extensions/the-system/__tests__/doctor.test.ts Modified 19 19 const temporaryRoot = ()
=> {
20 20 const root
= mkdtempSync (path.
join (
tmpdir (),
"the-system-doctor-" ));
22 - mkdirSync (path.
join (
root ,
".git" ));
25 24 const write = (root
: string , relative
: string , content
= "" )
=> {
73 72 describe (
"system doctor" , ()
=> {
74 73 it (
"requires the system root, config, and cores but not empty collections" , ()
=> {
75 74 const root
= temporaryRoot ();
75 + mkdirSync (path.
join (
root ,
".system" ));
76 76 const result
= runDoctor (
root );
78 78 result.diagnostics.
map (({ code, path })
=> `${path} ${code}` ),
80 - ".system filesystem.missing" ,
81 80 ".system/MISSION.md filesystem.missing" ,
82 81 ".system/RULES.md filesystem.missing" ,
83 82 ".system/SYSTEM.md filesystem.missing" ,
extensions/the-system/__tests__/documents.test.ts Modified 17 17 parseAuthoredDocument,
20 21 resolveGovernedPath,
21 22 SystemDocumentError,
22 23 systemConfigForInitialization,
60 61 describe (
"project root and schema-0 config" , ()
=> {
61 - it (
"contains paths and resolves nearest marker" , ()
=> {
62 + it (
"resolves the nearest .system root" , ()
=> {
62 63 const root
= tree ();
63 - mkdirSync (path.
join (
root ,
".git" ));
64 - assert.
equal (
discoverProjectRoot (path.
join (
root ,
"nested" )),
root );
64 + dir (
root ,
".system" );
65 + const nested
= dir (
root ,
"nested" );
66 + assert.
equal (
discoverProjectRoot (nested),
root );
67 + dir (nested,
".system" );
68 + assert.
equal (
discoverProjectRoot (nested), nested);
65 69 assert.
equal (
resolveGovernedPath (
root ,
"x/../x" ), path.
join (
root ,
"x" ));
67 71 ()
=> resolveGovernedPath (
root ,
"../outside" ),
76 + it (
"returns undefined without a .system directory" , ()
=> {
77 + assert.
equal (
discoverProjectRoot (
tree ()),
undefined );
78 + assert.
throws (()
=> requireProjectRoot (
tree ()), SystemDocumentError);
81 + it (
"ignores .system files and symbolic links while walking" , ()
=> {
82 + const root
= tree ();
83 + dir (
root ,
".system" );
84 + dir (
root ,
"elsewhere" );
85 + const fileDirectory
= dir (
root ,
"file" );
86 + writeFileSync (path.
join (fileDirectory,
".system" ),
"" );
87 + const linkDirectory
= dir (
root ,
"link" );
89 + path.
join (
root ,
"elsewhere" ),
90 + path.
join (linkDirectory,
".system" ),
93 + assert.
equal (
discoverProjectRoot (fileDirectory),
root );
94 + assert.
equal (
discoverProjectRoot (linkDirectory),
root );
72 97 it (
"accepts schema 0 and prepares mismatched config for initialization" , ()
=> {
extensions/the-system/__tests__/harness.test.ts Modified 24 24 it (
"keeps system_bundle_slot through clarification and cancels it on the next lifecycle" ,
async ()
=> {
25 25 const extensionPath
= path.
resolve (
import .
meta .dirname,
"../index.ts" );
26 26 t
= await createTestSession ({ extensions: [extensionPath] });
27 - mkdirSync (path.
join (t.cwd,
".git" ));
28 27 applyInitialization (t.cwd,
"PX" );
29 28 const [extension]
= t.session.extensionRunner.extensions;
30 29 const sendUserMessage
= vi
69 68 it (
"requests one-shot approval for an existing core mutation" ,
async ()
=> {
70 69 const extensionPath
= path.
resolve (
import .
meta .dirname,
"../index.ts" );
71 70 t
= await createTestSession ({ extensions: [extensionPath] });
72 - mkdirSync (path.
join (t.cwd,
".git" ));
73 71 mkdirSync (path.
join (t.cwd,
".system" ));
74 72 writeFileSync (path.
join (t.cwd,
".system" ,
"SYSTEM.md" ),
"Approved.\n" );
extensions/the-system/__tests__/init.test.ts Modified 20 20 const root = ()
=> {
21 21 const value
= mkdtempSync (path.
join (
tmpdir (),
"the-system-init-" ));
23 - mkdirSync (path.
join (value,
".git" ));
26 25 const write = (project
: string , relative
: string , content
: string )
=> {
53 52 assert.
match (child.stdout,
/WROTE \.system\/board\.json/ );
54 53 assert.
match (child.stdout,
/WROTE \.system\/SYSTEM\.md/ );
57 - readFileSync (path.
join (project,
".system/config.json" ),
"utf8" ),
59 - { prefix:
"PX" , schemaVersion:
0 , title: path.
basename (project) },
55 + JSON .
parse (
readFileSync (path.
join (cwd,
".system/config.json" ),
"utf8" )),
56 + { prefix:
"PX" , schemaVersion:
0 , title: path.
basename (cwd) },
63 - readFileSync (path.
join (project,
".system/board.json" ),
"utf8" ),
59 + JSON .
parse (
readFileSync (path.
join (cwd,
".system/board.json" ),
"utf8" )),
65 60 { schemaVersion:
0 , items: {} },
68 - readFileSync (path.
join (project,
".system/SYSTEM.md" ),
"utf8" ),
63 + readFileSync (path.
join (cwd,
".system/SYSTEM.md" ),
"utf8" ),
69 64 /Stable project identity/ ,
72 - readFileSync (path.
join (project,
".system/MISSION.md" ),
"utf8" ),
67 + readFileSync (path.
join (cwd,
".system/MISSION.md" ),
"utf8" ),
73 68 /Enduring high-level project objective/ ,
76 - readFileSync (path.
join (project,
".system/RULES.md" ),
"utf8" ),
71 + readFileSync (path.
join (cwd,
".system/RULES.md" ),
"utf8" ),
77 72 /Concrete operating constraints/ ,
79 74 for (
const directory
of [
"specs" ,
"phases" ,
"plans" ,
"issues" ,
"research" ])
81 - lstatSync (path.
join (project,
".system" , directory), {
76 + lstatSync (path.
join (cwd,
".system" , directory), {
82 77 throwIfNoEntry:
false ,
86 81 const before
= [
"SYSTEM.md" ,
"MISSION.md" ,
"RULES.md" ].
map ((name)
=> {
87 - const target
= path.
join (project,
".system" , name);
82 + const target
= path.
join (cwd,
".system" , name);
88 83 return [name,
readFileSync (target,
"utf8" ),
lstatSync (target).mtimeMs];
90 - assert.
deepEqual (
applyInitialization (project,
"PX" ), {
85 + assert.
deepEqual (
applyInitialization (cwd,
"PX" ), {
96 91 for (
const [name, source, mtime]
of before) {
97 - const target
= path.
join (project,
".system" , name);
92 + const target
= path.
join (cwd,
".system" , name);
99 94 [
readFileSync (target,
"utf8" ),
lstatSync (target).mtimeMs],
103 - assert.
equal (
runDoctor (project).exitCode,
0 );
98 + assert.
equal (
runDoctor (cwd).exitCode,
0 );
106 101 it (
"holds a mismatched config pending, then rewrites it when approved" , ()
=> {
extensions/the-system/__tests__/startup.test.ts Modified 16 16 function validSystem ()
: string {
17 17 const root
= mkdtempSync (path.
join (
tmpdir (),
"the-system-startup-" ));
19 - mkdirSync (path.
join (
root ,
".git" ));
20 19 mkdirSync (path.
join (
root ,
".system" ));
21 20 for (
const directory
of [
"specs" ,
"phases" ,
"plans" ,
"issues" ,
"research" ])
22 21 mkdirSync (path.
join (
root ,
".system" , directory));
extensions/the-system/__tests__/system.test.ts Modified 27 27 const root = ()
=> {
28 28 const value
= mkdtempSync (path.
join (
tmpdir (),
"the-system-runtime-" ));
30 - mkdirSync (path.
join (value,
".git" ));
31 30 applyInitialization (value,
"PX" );
32 31 for (
const name
of [
"SYSTEM.md" ,
"MISSION.md" ,
"RULES.md" ])
33 32 write (value,
`.system/${name}` ,
`# ${name}\n\nApproved.\n` );
69 68 it (
"stays quiet until the project opts into .system" ,
async ()
=> {
70 69 const project
= mkdtempSync (path.
join (
tmpdir (),
"the-system-runtime-" ));
71 70 roots.
push (project);
72 - mkdirSync (path.
join (project,
".git" ));
73 71 assert.
deepEqual (
runtimeState (project), { active:
false });
74 72 assert.
deepEqual (
await startupRuntimeState (project), { active:
false });
75 73 assert.
equal (
runtimeNotice (project),
undefined );
extensions/the-system/__tests__/the-system.test.ts Modified 20 20 const temp = ()
=> {
21 21 const root
= mkdtempSync (path.
join (
tmpdir (),
"the-system-command-" ));
23 - mkdirSync (path.
join (
root ,
".git" ));
26 25 const write = (root
: string , relative
: string , content
: string )
=> {
extensions/the-system/board-runtime.ts Modified 13 13 loadSystemRenderer,
14 14 } from
"./loaders.js" ;
15 - import { discoverProjectRoot }
from "./project-root.ts" ;
15 + import { requireProjectRoot }
from "./project-root.ts" ;
16 16 import { expandableFallback }
from "./tool-rendering.ts" ;
18 18 const STATES
= [
"todo" ,
"done" ,
"open" ]
as const ;
83 + const renderBoardToolResult = (
85 + content
: Parameters <
typeof expandableFallback>[
0 ];
91 + lastComponent
: unknown ,
92 + messages
: Readonly <{ empty
: string ;
summary : (count
: number )
=> string }>,
94 + const text
= (lastComponent
as Text | undefined )
?? new Text (
"" ,
0 ,
0 );
95 + const items
= (result.details
as { items
?: BoardProposal [] }
| undefined )
103 + isError
? "error" : "muted" ,
111 + items.
length === 0 ? messages.empty
: messages.
summary (items.
length ),
83 117 export function createBoardRuntime () {
84 118 let proposalRoot
: string | undefined ;
85 119 let proposalFinished
= false ;
88 122 const proposals
= new Map <
string ,
Map <
string ,
BoardProposal >>();
89 123 const servers
= new Set <
BoardServer >();
90 124 const loadBoard = async (cwd
: string )
=> {
91 - const root
= discoverProjectRoot (cwd);
125 + const root
= requireProjectRoot (cwd);
92 126 const [projectIndex, boardState]
= await Promise .
all ([
93 127 loadProjectIndex (),
111 145 return renderBoardItems (
"system_board_propose" , args, theme, context);
113 147 renderResult (result, { expanded }, theme, context) {
115 - (context.lastComponent
as Text | undefined )
?? new Text (
"" ,
0 ,
0 );
116 - const items
= (result.details
as { items
?: BoardProposal [] }
| undefined )
120 - expandableFallback (
124 - context.isError
? "error" : "muted" ,
129 - const count
= items.
length ;
134 - ? "✓ no changes proposed" 135 - : `✓ ${count} change${count === 1 ? "" : "s"} proposed` ,
148 + return renderBoardToolResult (
152 + Boolean (context.isError),
153 + context.lastComponent,
155 + empty:
"✓ no changes proposed" ,
156 + summary : (count)
=> 157 + `✓ ${count} change${count === 1 ? "" : "s"} proposed` ,
140 161 async
execute (_toolCallId, params, _signal, _onUpdate, ctx) {
141 - const root
= discoverProjectRoot (ctx.cwd);
162 + const root
= requireProjectRoot (ctx.cwd);
142 163 if (
root !== proposalRoot)
144 165 "system_board_propose is only available during /system assess or /system exec" ,
202 223 return renderBoardItems (
"system_board_update" , args, theme, context);
204 225 renderResult (result, { expanded }, theme, context) {
206 - (context.lastComponent
as Text | undefined )
?? new Text (
"" ,
0 ,
0 );
207 - const items
= (result.details
as { items
?: BoardProposal [] }
| undefined )
211 - expandableFallback (
215 - context.isError
? "error" : "muted" ,
220 - const count
= items.
length ;
225 - ? "✓ no board changes" 226 - : `✓ ${count} board change${count === 1 ? "" : "s"} applied` ,
226 + return renderBoardToolResult (
230 + Boolean (context.isError),
231 + context.lastComponent,
233 + empty:
"✓ no board changes" ,
234 + summary : (count)
=> 235 + `✓ ${count} board change${count === 1 ? "" : "s"} applied` ,
231 239 async
execute (_toolCallId, params, _signal, _onUpdate, ctx) {
232 - const root
= discoverProjectRoot (ctx.cwd);
240 + const root
= requireProjectRoot (ctx.cwd);
233 241 if (
root !== updateRoot)
235 243 "system_board_update is only available during /system exec" ,
extensions/the-system/bundle-slot.ts Modified 4 4 import { randomBytes }
from "node:crypto" ;
5 5 import { readFileSync }
from "node:fs" ;
6 6 import path
from "node:path" ;
9 9 discoverDocumentBundles,
10 - discoverProjectRoot,
11 10 indexBundleDocuments,
13 13 }
from "./documents.js" ;
15 15 export type BundleType = "research" | "spec" | "phase" | "plan" | "issue" ;
23 23 input : {
type : BundleType;
title : string },
24 24 reserved :
Set < string
> = new Set (),
26 - const root
= discoverProjectRoot (cwd);
26 + const root
= requireProjectRoot (cwd);
27 27 const config
= parseSystemConfig (
28 28 readFileSync (path.
join (
root ,
".system/config.json" ),
"utf8" ),
extensions/the-system/doctor.ts Modified 4 4 import { lstatSync, readdirSync, readFileSync }
from "node:fs" ;
5 5 import path
from "node:path" ;
6 6 import { BOARD_PATH, boardStateFor, readBoardState }
from "./board-state.ts" ;
9 9 discoverDocumentBundles,
10 - discoverProjectRoot,
11 10 indexBundleDocuments,
15 15 type SystemDocumentError,
16 16 }
from "./documents.ts" ;
87 87 export function runDoctor (cwd
: string )
: DoctorResult {
90 - root = discoverProjectRoot (cwd);
90 + root = requireProjectRoot (cwd);
92 92 const value
= error
as SystemDocumentError ;
extensions/the-system/documents.ts Modified 16 16 discoverProjectRoot,
17 18 resolveGovernedPath,
18 19 SystemDocumentError,
19 20 }
from "./project-root.ts" ;
extensions/the-system/init.ts Modified 9 9 } from
"./board-state.ts" ;
11 - discoverProjectRoot,
12 - resolveGovernedPath,
13 - SystemDocumentError,
14 - }
from "./project-root.ts" ;
10 + import { resolveGovernedPath, SystemDocumentError }
from "./project-root.ts" ;
107 103 requestedPrefix
?: string,
108 104 ): InitializationInspection {
109 - const root
= discoverProjectRoot (cwd);
105 + const root
= path.
resolve (cwd);
110 106 for (
const relative
of DIRECTORIES)
requireKind (
root , relative,
"directory" );
111 107 for (
const relative
of COLLECTION_DIRECTORIES)
112 108 requireKind (
root , relative,
"directory" );
extensions/the-system/project-index.ts Modified 3 3 import { readFileSync }
from "node:fs" ;
4 4 import path
from "node:path" ;
7 7 discoverDocumentBundles,
9 8 indexBundleDocuments,
12 12 }
from "./documents.ts" ;
14 14 export function loadProjectIndex (cwd
: string ) {
15 - const root
= discoverProjectRoot (cwd);
15 + const root
= requireProjectRoot (cwd);
16 16 const config
= parseSystemConfig (
17 17 readFileSync (path.
join (
root ,
".system/config.json" ),
"utf8" ),
extensions/the-system/project-root.ts Modified 1 - import { existsSync }
from "node:fs" ;
1 + import { lstatSync }
from "node:fs" ;
2 2 import path
from "node:path" ;
4 4 export class SystemDocumentError extends Error {
14 - const nearestMarker = (
17 - markerExists : (candidate
: string )
=> boolean ,
19 - let current
= path.
resolve (cwd);
21 - if (
markerExists (path.
join (current, marker)))
return current;
22 - const parent
= path.
dirname (current);
23 - if (parent
=== current)
return undefined ;
28 14 export function resolveGovernedPath (root
: string , candidate
: string )
: string {
29 15 const normalizedRoot
= path.
resolve (
root );
30 16 const target
= path.
resolve (normalizedRoot, candidate);
44 - export function discoverProjectRoot (
46 - markerExists
= existsSync,
48 - const resolvedCwd
= path.
resolve (cwd);
49 - const jj
= nearestMarker (resolvedCwd,
".jj" , markerExists);
50 - const git
= nearestMarker (resolvedCwd,
".git" , markerExists);
51 - if (jj
&& git
&& jj
!== git)
30 + export function discoverProjectRoot (cwd
: string )
: string | undefined {
31 + let current
= path.
resolve (cwd);
33 + const stats
= lstatSync (path.
join (current,
".system" ), {
34 + throwIfNoEntry:
false ,
36 + if (stats?.
isDirectory ())
return current;
37 + const parent
= path.
dirname (current);
38 + if (parent
=== current)
return undefined ;
43 + export function requireProjectRoot (cwd
: string )
: string {
44 + const root
= discoverProjectRoot (cwd);
52 46 throw new SystemDocumentError (
54 - `Conflicting project roots: Git ${git}; JJ ${jj}` ,
48 + `No System project found at or above ${path. resolve (cwd)}` ,
56 - return jj
?? git
?? resolvedCwd;
extensions/the-system/startup-state.ts Modified 1 - import { existsSync }
from "node:fs" ;
2 - import path
from "node:path" ;
3 1 import { inspectInitialization }
from "./init.ts" ;
4 2 import { loadSystem }
from "./loaders.js" ;
5 3 import { discoverProjectRoot }
from "./project-root.ts" ;
22 20 export async function readStartupRuntimeState (
24 22 )
: Promise <
StartupRuntimeState > {
27 - root = discoverProjectRoot (cwd);
29 - return { active:
false };
31 - if (
! existsSync (path.
join (
root ,
".system" )))
return { active:
false };
23 + const root
= discoverProjectRoot (cwd);
24 + if (
! root )
return { active:
false };
33 26 const inspection
= inspectInitialization (
root );
34 27 if (inspection.rewrites.
length > 0 )
extensions/the-system/system-prompts.ts Modified 1 1 export const DOCUMENT_CONTRACT
= `# The System document contract 3 3 Use .system bundles only. 4 + The active System root is the nearest .system directory at or above the session cwd; nested systems stay independent and parent systems are never injected. 4 5 Authored documents live at .system/<type-plural>/<ID>-<slug>/index.md with lowercase slugs. 5 6 Type directories: research, specs, phases, plans, issues. 6 7 ID shape: <PREFIX>-<TYPE>-<8 chars from A-Z0-9_->. extensions/the-system/system.ts Modified 47 47 export function composeSystemSection (cwd
: string )
: string | undefined {
50 - root = discoverProjectRoot (cwd);
52 - return governanceError (
53 - error
instanceof Error ? error.message
: String (error),
48 + const root
= discoverProjectRoot (cwd);
49 + if (
! root )
return undefined ;
57 51 const [system, mission, rules]
= CORES.
map ((name)
=> coreBlock (
root , name));
58 52 let phase
: string | undefined ;
88 82 const SCHEMA_NOTICE
= `The System schema does not match ${SCHEMA_VERSION}; run /system init to update it.` ;
90 84 export function runtimeState (cwd
: string )
: SystemRuntimeState {
93 - root = discoverProjectRoot (cwd);
95 - return { active:
false };
97 - if (
! existsSync (path.
join (
root ,
".system" )))
return { active:
false };
85 + const root
= discoverProjectRoot (cwd);
86 + if (
! root )
return { active:
false };
99 88 const inspection
= inspectInitialization (
root );
100 89 if (inspection.rewrites.
length > 0 )
382 371 ui : GovernanceUI,
383 372 options : MutationOptions
= {},
384 373 ):
Promise < GateResult
> {
387 - root = discoverProjectRoot (cwd);
390 - `The System cannot resolve project ownership: ${error instanceof Error ? error.message : String (error)}` ,
374 + const
root = discoverProjectRoot (cwd);
375 + if (!root) return undefined;
393 376 const candidate
= path.
resolve (cwd, input.path);
394 377 const candidateRelative
= path.
relative (
root , candidate);