@yunhozz/arc 0.2.1 → 0.2.3

package/codex/skill/references/visual-companion.md

@@ -1,27 +1,299 @@
-# Visual companion contract
+# Visual Companion Guide
 
-Read before offering or operating a visual companion.
+Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
 
-## Visual companion
+## When to Use
 
-Visual companion design discussion is distinct from QA UI acceptance checks under the approved test brief.
+Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
 
-Planner identifies a genuinely visual question, explains why a visual helps, and returns options, the user decision,
-and a complete content draft; Planner does not write screens, start a server, operate a browser, or request approval.
-Orchestrator makes a just-in-time offer as its own message only when a question is clearer visually, then waits for
-acceptance. If declined, continue in text and do not offer again unless the user raises it. If accepted, decide per
-question whether to use the companion. Orchestrator owns its guide, server/browser, workspace paths, live-session
-checks, complete keyed URL, screens, session state, feedback/events, stale-screen clearing when returning to text, and
-cleanup. Check the server before showing a screen; after the user's reply, treat terminal text as primary and events as
-supplemental. A UI topic or accepted companion alone does not route every question through a browser.
+**Use the browser** when the content itself is visual:
 
+- **UI mockups** — wireframes, layouts, navigation structures, component designs
+- **Architecture diagrams** — system components, data flow, relationship maps
+- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
+- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
+- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
 
-Upstream guide/scripts: `<installed ARC>/references/superpowers/brainstorming/visual-companion.md` and adjacent `scripts/`.
-ARC guide: `references/visual-companion.md`; Orchestrator briefs absolute paths and retains approval/server/browser
-ownership. Missing files stop dependent work. MUST NOT use a global fallback.
+**Use the terminal** when the content is text or tabular:
 
-## Follow-up Verification of Approved Visual Sources
+- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
+- **Conceptual A/B/C choices** — picking between approaches described in words
+- **Tradeoff lists** — pros/cons, comparison tables
+- **Technical decisions** — API design, data modeling, architectural approach selection
+- **Clarifying questions** — anything where the answer is words, not a visual preference
 
-Each visual criterion requires the exact location, version, approval, and access state of the approved visual source; criterion IDs, properties, and comparison method; and evidence linking the actual output to its revision. An Implementer report does not replace fresh QA's direct comparison. Record results as pass, mismatch, or unverified and connect them to the existing proven/unmet/unverified criterion verdicts. Use pass only when accessible evidence meets the visual criterion. Keep unsupported claims unverified. Missing output-to-revision linkage is unverified; a visible difference is a mismatch. Treat these as separate observations and do not infer the current branch UI state. Hold the comparison if the approved source or actual output is inaccessible or interpretation approval is missing.
+A question *about* a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser.
 
-Static policy, generated-file, and manifest checks are structural evidence. They do not prove actual role behavior, an installed build, Claude Code CLI runtime compliance, or visual fidelity. Reports include actual changes and exclusion rationale, checks run and omitted, evidence and limits by criterion, and platform availability. Preserve existing baseline failures separately; progress on independent work does not relax required checks or acceptance criteria.
+## How It Works
+
+The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content to `screen_dir`, the user sees it in their browser and can click to select options. Selections are recorded to `state_dir/events` that you read on your next turn.
+
+**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, connection status, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
+
+## Starting a Session
+
+```bash
+# Start AFTER the user approves the companion. --open auto-opens their browser on
+# the first screen; --project-dir persists mockups and enables same-port restart.
+bash scripts/start-server.sh --project-dir /path/to/project --open
+
+# Returns: {"type":"server-started","port":52341,
+#           "url":"http://localhost:52341/?key=ab12…",
+#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
+#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
+```
+
+Save `screen_dir` and `state_dir` from the response. With `--open`, the browser opens itself when you push the first screen — you don't need to ask the user to open it, but still share the URL as a fallback (headless/remote setups won't auto-open).
+
+**The URL contains a session key (`?key=…`).** The server rejects any request
+without it, so always give the user the **complete** URL from the `url` field —
+never strip the query string, and never hand out a bare `http://host:port`. The
+key gates HTTP and WebSocket access so a stray browser tab or another machine on
+the network can't read the screens or inject events. After the first load the
+browser remembers the key via a cookie, so reloads and `/files/*` assets work
+without repeating it.
+
+**Finding connection info:** The server writes its startup JSON to `$STATE_DIR/server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.superpowers/brainstorm/` for the session directory.
+
+**Note:** Pass the project root as `--project-dir` so mockups persist in `.superpowers/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.superpowers/` to `.gitignore` if it's not already there.
+
+**Launching the server by platform:**
+
+**Claude Code:**
+```bash
+# Default mode works — the script backgrounds the server itself.
+bash scripts/start-server.sh --project-dir /path/to/project --open
+```
+
+On Windows, the script auto-detects and switches to foreground mode (which blocks the tool call). Use `run_in_background: true` on the Bash tool call so the server survives across conversation turns, then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
+
+**Codex:**
+```bash
+# Codex reaps background processes. The script auto-detects CODEX_CI and
+# switches to foreground mode. Run it normally — no extra flags needed.
+bash scripts/start-server.sh --project-dir /path/to/project --open
+```
+
+**Gemini CLI:**
+```bash
+# Use --foreground and set is_background: true on your shell tool call
+# so the process survives across turns
+bash scripts/start-server.sh --project-dir /path/to/project --open --foreground
+```
+
+**Copilot CLI:**
+```bash
+# Start it with Copilot CLI's non-blocking/background shell mechanism so the
+# server survives across turns. Keep --foreground so the harness, not the
+# script, owns backgrounding. The launcher is a .sh, so invoke it via bash
+# (on Windows, call Git Bash's bash.exe from the PowerShell tool).
+bash scripts/start-server.sh --project-dir /path/to/project --open --foreground
+```
+
+**Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
+
+If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
+
+```bash
+bash scripts/start-server.sh \
+  --project-dir /path/to/project \
+  --host 0.0.0.0 \
+  --url-host localhost
+```
+
+Use `--url-host` to control what hostname is printed in the returned URL JSON.
+
+## The Loop
+
+1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
+   - **Required: confirm the server is alive before referring to the URL or pushing a screen.** Check that `$STATE_DIR/server-info` exists and `$STATE_DIR/server-stopped` does not. If it has shut down, restart it with `start-server.sh` using the **same `--project-dir`** — it reuses the same port, so the user's open tab reconnects on its own (it shows a "paused" overlay while the server is down) and you don't need to send a new URL. The server auto-exits after 4 hours idle (configurable with `--idle-timeout-minutes`).
+   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
+   - **Never reuse filenames** — each screen gets a fresh file
+   - Use your file-creation tool — **never use cat/heredoc** (dumps noise into terminal)
+   - Server automatically serves the newest file
+
+2. **Tell user what to expect and end your turn:**
+   - Remind them of the URL (every step, not just first)
+   - Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
+   - Ask them to respond in the terminal: "Take a look and let me know what you think. Click to select an option if you'd like."
+
+3. **On your next turn** — after the user responds in the terminal:
+   - Read `$STATE_DIR/events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
+   - Merge with the user's terminal text to get the full picture
+   - The terminal message is the primary feedback; `state_dir/events` provides structured interaction data
+
+4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
+
+5. **Unload when returning to terminal** — when the next step doesn't need the browser (e.g., a clarifying question, a tradeoff discussion), push a waiting screen to clear the stale content:
+
+   ```html
+   <!-- filename: waiting.html (or waiting-2.html, etc.) -->
+   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
+     <p class="subtitle">Continuing in terminal...</p>
+   </div>
+   ```
+
+   This prevents the user from staring at a resolved choice while the conversation has moved on. When the next visual question comes up, push a new content file as usual.
+
+6. Repeat until done.
+
+## Writing Content Fragments
+
+Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, connection status, and all interactive infrastructure).
+
+**Minimal example:**
+
+```html
+<h2>Which layout works better?</h2>
+<p class="subtitle">Consider readability and visual hierarchy</p>
+
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Single Column</h3>
+      <p>Clean, focused reading experience</p>
+    </div>
+  </div>
+  <div class="option" data-choice="b" onclick="toggleSelect(this)">
+    <div class="letter">B</div>
+    <div class="content">
+      <h3>Two Column</h3>
+      <p>Sidebar navigation with main content</p>
+    </div>
+  </div>
+</div>
+```
+
+That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
+
+## CSS Classes Available
+
+The frame template provides these CSS classes for your content:
+
+### Options (A/B/C choices)
+
+```html
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Title</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+**Multi-select:** Add `data-multiselect` to the container to let users select multiple options. Each click toggles the item's selected styling.
+
+```html
+<div class="options" data-multiselect>
+  <!-- same option markup — users can select/deselect multiple -->
+</div>
+```
+
+### Cards (visual designs)
+
+```html
+<div class="cards">
+  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
+    <div class="card-image"><!-- mockup content --></div>
+    <div class="card-body">
+      <h3>Name</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+### Mockup container
+
+```html
+<div class="mockup">
+  <div class="mockup-header">Preview: Dashboard Layout</div>
+  <div class="mockup-body"><!-- your mockup HTML --></div>
+</div>
+```
+
+### Split view (side-by-side)
+
+```html
+<div class="split">
+  <div class="mockup"><!-- left --></div>
+  <div class="mockup"><!-- right --></div>
+</div>
+```
+
+### Pros/Cons
+
+```html
+<div class="pros-cons">
+  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
+  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
+</div>
+```
+
+### Mock elements (wireframe building blocks)
+
+```html
+<div class="mock-nav">Logo | Home | About | Contact</div>
+<div style="display: flex;">
+  <div class="mock-sidebar">Navigation</div>
+  <div class="mock-content">Main content area</div>
+</div>
+<button class="mock-button">Action Button</button>
+<input class="mock-input" placeholder="Input field">
+<div class="placeholder">Placeholder area</div>
+```
+
+### Typography and sections
+
+- `h2` — page title
+- `h3` — section heading
+- `.subtitle` — secondary text below title
+- `.section` — content block with bottom margin
+- `.label` — small uppercase label text
+
+## Browser Events Format
+
+When the user clicks options in the browser, their interactions are recorded to `$STATE_DIR/events` (one JSON object per line). The file is cleared automatically when you push a new screen.
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
+{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
+{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
+```
+
+The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
+
+If `$STATE_DIR/events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
+
+## Design Tips
+
+- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
+- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
+- **Iterate before advancing** — if feedback changes current screen, write a new version
+- **2-4 options max** per screen
+- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
+- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
+
+## File Naming
+
+- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
+- Never reuse filenames — each screen must be a new file
+- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
+- Server serves newest file by modification time
+
+## Cleaning Up
+
+```bash
+bash scripts/stop-server.sh $SESSION_DIR
+```
+
+If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
+
+## Reference
+
+- Frame template (CSS reference): `scripts/frame-template.html`
+- Helper script (client-side): `scripts/helper.js`

package/lib/installer/install.mjs

@@ -1,7 +1,7 @@
 import {validatePlanSet} from './plan.mjs';
 import {assertPlanSnapshot,applyTransaction} from './transaction.mjs';
 function pending(plan){return{platform:plan.target.platform,status:'not-started',rollback:'not-needed',residualPaths:[],error:null};}
-export async function installTargets(plans,{safeFs,acquisition,signal,hooks={}}){
+export async function installTargets(plans,{safeFs,signal,hooks={}}){
  const ordered=[...plans].sort((a,b)=>(a.target.platform==='codex'?0:1)-(b.target.platform==='codex'?0:1));const results=ordered.map(pending);let interrupted=false;
  let invalid=false;
  for(let index=0;index<ordered.length;index++){
@@ -14,14 +14,12 @@ export async function installTargets(plans,{safeFs,acquisition,signal,hooks={}})
  if(invalid)return{results,interrupted};
  for(let index=0;index<ordered.length;index++){
   const plan=ordered[index];if(signal?.aborted){interrupted=true;break;}
-  let acquired,failed=false;
+  let failed=false;
   try{
-   hooks.fault?.({phase:'before-acquisition',plan});assertPlanSnapshot(plan,{safeFs});
-   acquired=await acquisition(plan,{signal});
-   hooks.fault?.({phase:'after-acquisition',plan});assertPlanSnapshot(plan,{safeFs});
-   const installed=applyTransaction(plan,{safeFs,acquired,signal,hooks});
+   assertPlanSnapshot(plan,{safeFs});
+   const installed=applyTransaction(plan,{safeFs,signal,hooks});
    results[index]={...results[index],status:'installed',error:installed.cleanupError??null,residualPaths:[...results[index].residualPaths,...(installed.residualPaths??[])]};if(installed.cleanupError)failed=true;
-  }catch(error){const cancelled=signal?.aborted||error.code==='ARC_ACQUISITION_CANCELLED'||error.code==='ARC_INSTALL_CANCELLED';interrupted=Boolean(cancelled);results[index]={...results[index],status:'failed',rollback:error.rollback??'not-needed',residualPaths:[...results[index].residualPaths,...(error.residualPaths??[])],error};failed=true;}finally{if(acquired?.dispose){try{const disposal=await acquired.dispose();if(disposal?.residualPaths)results[index].residualPaths=[...new Set([...results[index].residualPaths,...disposal.residualPaths])];}catch(cleanup){const result=results[index];result.error=result.error?new AggregateError([result.error,cleanup],'Installation and acquisition cleanup reported failures'):cleanup;result.residualPaths=[...new Set([...result.residualPaths,...(cleanup.residualPaths??(acquired.work?[acquired.work]:[]))])];failed=true;}}}
+  }catch(error){const cancelled=signal?.aborted||error.code==='ARC_INSTALL_CANCELLED';interrupted=Boolean(cancelled);results[index]={...results[index],status:'failed',rollback:error.rollback??'not-needed',residualPaths:[...results[index].residualPaths,...(error.residualPaths??[])],error};failed=true;}
   if(failed)break;
  }
  return{results,interrupted};

package/lib/installer/manifest.mjs

@@ -1,31 +1,46 @@
 import {COOPERATIVE_RUNTIME_MODULES} from '../runtime/bootstrap.mjs';
 import {RUNTIME_MODULE_PATHS} from './runtime-assets.mjs';
 import {POLICY_TARGETS,buildPolicyOutputs} from '../policy/render.mjs';
-import {isDynamicReferencePath,readReferenceBundle} from './superpowers.mjs';
+import {validateFlatReferenceFiles,REFERENCE_PATH_MAP} from './superpowers.mjs';
 import path from 'node:path';import crypto from 'node:crypto';import{loadModelConfig,resolveModelSettings,renderProfiles}from '../models/index.mjs';import{readCheckedFile,typeOf,sameIdentity,metadataOf}from './targets.mjs';
 export class PayloadValidationError extends Error{constructor(message,options){super(message,options);this.name='PayloadValidationError';this.code='ARC_PAYLOAD_VALIDATION';}}
 const MUTABLE=new Set(['codex/skill/models.toml','claude/skill/models.toml']);
+export const LOCAL_UPDATER_PATH='scripts/update-superpowers-local.sh';
 const ROOTS=['bin','lib','scripts','vendor','prebuilds','codex/skill','codex/agents','claude/skill','claude/agents'];
 const FIXED=['README.md','install.command','package.json','native/binding.c','native/binding.gyp'];
 function safeName(name){return typeof name==='string'&&name.length>0&&!name.includes('\\')&&!name.includes('\0')&&!name.startsWith('/')&&name.split('/').every(p=>p&&p!=='.'&&p!=='..')&&path.posix.normalize(name)===name;}
 function allowed(name){return FIXED.includes(name)||ROOTS.some(root=>name.startsWith(root+'/'));}
-export function verifyPayload({packageRoot,safeFs}){
+export function renderManifest(files){return Buffer.from([...files].filter(([name])=>!MUTABLE.has(name)&&name!==LOCAL_UPDATER_PATH&&!name.split('/').includes('.DS_Store')).sort(([a],[b])=>a<b?-1:a>b?1:0).map(([name,bytes])=>{if(!safeName(name)||!allowed(name)||!Buffer.isBuffer(bytes))throw Error('Invalid protected manifest file');return crypto.createHash('sha256').update(bytes).digest('hex')+'  '+name+'\n';}).join(''));}
+const LIFECYCLE_HOOKS=['preinstall','install','postinstall','prepublish','prepare','prepublishOnly','prepack','postpack','publish','postpublish','preuninstall','uninstall','postuninstall'];
+function sourcePayload(root,mode){
+ if(!['auto','source','package'].includes(mode))throw Error('Invalid payload mode');if(mode==='package')return false;
+ if(mode==='auto'){let marker;try{marker=root.lstat('.git');}catch(error){if(error.code==='ENOENT')return false;throw error;}
+  if(typeOf(marker)===0o040000){const directory=root.openDir('.git');try{if(!sameIdentity(marker,directory.stat()))throw Error('Source marker changed');}finally{directory.close();}}
+  else if(typeOf(marker)===0o100000){const bytes=readCheckedFile(root,'.git',marker).bytes;let text;try{text=new TextDecoder('utf-8',{fatal:true}).decode(bytes);}catch{throw Error('Invalid source Git marker');}if(!/^gitdir: [^\0\r\n]+\r?\n?$/.test(text))throw Error('Invalid source Git marker');}
+  else throw Error('Unsafe source Git marker');
+ }
+ let pkg,lock;try{pkg=JSON.parse(readCheckedFile(root,'package.json').bytes);lock=JSON.parse(readCheckedFile(root,'package-lock.json').bytes);}catch{throw Error('Source package identity or lock is invalid');}
+ const recorded=lock?.packages?.[''];if(pkg?.name!=='@yunhozz/arc'||!/^\d+\.\d+\.\d+$/.test(pkg.version)||lock.name!==pkg.name||lock.version!==pkg.version||recorded?.name!==pkg.name||recorded?.version!==pkg.version||LIFECYCLE_HOOKS.some(name=>Object.hasOwn(pkg.scripts??{},name))||Object.hasOwn(pkg.scripts??{},'build')||Object.hasOwn(pkg,'workspaces')||Object.hasOwn(recorded,'hasInstallScript'))throw Error('Source package identity or lifecycle contract is invalid');return true;
+}
+export function verifyPayload({packageRoot,safeFs,payloadMode='auto'}){
  let root;try{
-  root=safeFs.openRoot(packageRoot);const manifest=readCheckedFile(root,'MANIFEST.sha256').bytes;let text;try{text=new TextDecoder('utf-8',{fatal:true}).decode(manifest);}catch{throw Error('Manifest is not UTF-8');}
-  const listed=new Map();for(const line of text.split(/\r?\n/)){if(!line)continue;const m=/^([a-fA-F0-9]{64})  (.+)$/.exec(line);if(!m||!safeName(m[2]))throw Error('Malformed or escaping manifest path');const name=m[2];if(MUTABLE.has(name)||isDynamicReferencePath(name)||!allowed(name)||name.split('/').includes('.DS_Store')||listed.has(name))throw Error(`Duplicate, mutable or unexpected manifest entry: ${name}`);listed.set(name,m[1].toLowerCase());}
+  root=safeFs.openRoot(packageRoot);const source=sourcePayload(root,payloadMode),manifest=readCheckedFile(root,'MANIFEST.sha256').bytes;let text;try{text=new TextDecoder('utf-8',{fatal:true}).decode(manifest);}catch{throw Error('Manifest is not UTF-8');}
+  const listed=new Map();for(const line of text.split(/\r?\n/)){if(!line)continue;const m=/^([a-fA-F0-9]{64})  (.+)$/.exec(line);if(!m||!safeName(m[2]))throw Error('Malformed or escaping manifest path');const name=m[2];if(MUTABLE.has(name)||name===LOCAL_UPDATER_PATH||!allowed(name)||name.split('/').includes('.DS_Store')||listed.has(name))throw Error(`Duplicate, mutable or unexpected manifest entry: ${name}`);listed.set(name,m[1].toLowerCase());}
   const files=new Map(),snapshot=new Map(),referenceTrees={};
   function walk(directory,prefix){const before=directory.stat();for(const name of directory.readDir()){
     const relative=prefix?prefix+'/'+name:name;const stat=directory.lstat(name),type=typeOf(stat);
+    if(relative===LOCAL_UPDATER_PATH){if(!source)throw Error('Local updater wrapper is forbidden in package payload');if(type!==0o100000||!sameIdentity(stat,directory.lstat(name)))throw Error('Local updater wrapper must be a stable regular file');continue;}
     if(name==='.DS_Store'){if(type!==0o100000)throw Error('DS_Store must be a regular file');continue;}
-    if(type===0o040000){const sub=directory.openDir(name);try{if(!sameIdentity(stat,sub.stat()))throw Error('Payload directory changed');snapshot.set(relative,{...metadataOf(stat),type:'directory'});if(isDynamicReferencePath(relative))referenceTrees[relative.split('/')[0]]=readReferenceBundle({safeFs,root:path.join(packageRoot,relative),directory:sub});else walk(sub,relative);}finally{sub.close();}}
+    if(type===0o040000){const sub=directory.openDir(name);try{if(!sameIdentity(stat,sub.stat()))throw Error('Payload directory changed');snapshot.set(relative,{...metadataOf(stat),type:'directory'});walk(sub,relative);}finally{sub.close();}}
     else if(type===0o100000){const item=readCheckedFile(directory,name,stat);if(!MUTABLE.has(relative)&&(!listed.has(relative)||crypto.createHash('sha256').update(item.bytes).digest('hex')!==listed.get(relative)))throw Error(`Missing entry or hash mismatch: ${relative}`);files.set(relative,item.bytes);snapshot.set(relative,item.metadata);}
     else throw Error(`Unsafe payload type: ${relative}`);
    }if(!sameIdentity(before,directory.stat()))throw Error('Payload directory changed while reading');}
-  function select(relative,isTree){const parts=relative.split('/');let parent=root;const opened=[];try{for(const component of parts.slice(0,-1)){let st;try{st=parent.lstat(component);}catch(e){if(e.code==='ENOENT')return;throw e;}if(typeOf(st)!==0o040000)throw Error('Unsafe payload parent');const next=parent.openDir(component);if(!sameIdentity(st,next.stat())){next.close();throw Error('Payload parent changed');}opened.push(next);parent=next;}const name=parts.at(-1);let st;try{st=parent.lstat(name);}catch(e){if(e.code==='ENOENT')return;throw e;}if(isTree){if(typeOf(st)!==0o040000)throw Error('Payload root is not a directory');const sub=parent.openDir(name);try{if(!sameIdentity(st,sub.stat()))throw Error('Payload root changed');snapshot.set(relative,{...metadataOf(st),type:'directory'});if(isDynamicReferencePath(relative))referenceTrees[relative.split('/')[0]]=readReferenceBundle({safeFs,root:path.join(packageRoot,relative),directory:sub});else walk(sub,relative);}finally{sub.close();}}else{if(typeOf(st)!==0o100000)throw Error('Payload file is not regular');const item=readCheckedFile(parent,name,st);if(!listed.has(relative)||crypto.createHash('sha256').update(item.bytes).digest('hex')!==listed.get(relative))throw Error(`Missing entry or hash mismatch: ${relative}`);files.set(relative,item.bytes);snapshot.set(relative,item.metadata);}}finally{for(const h of opened.reverse())h.close();}}
+  function select(relative,isTree){const parts=relative.split('/');let parent=root;const opened=[];try{for(const component of parts.slice(0,-1)){let st;try{st=parent.lstat(component);}catch(e){if(e.code==='ENOENT')return;throw e;}if(typeOf(st)!==0o040000)throw Error('Unsafe payload parent');const next=parent.openDir(component);if(!sameIdentity(st,next.stat())){next.close();throw Error('Payload parent changed');}opened.push(next);parent=next;}const name=parts.at(-1);let st;try{st=parent.lstat(name);}catch(e){if(e.code==='ENOENT')return;throw e;}if(isTree){if(typeOf(st)!==0o040000)throw Error('Payload root is not a directory');const sub=parent.openDir(name);try{if(!sameIdentity(st,sub.stat()))throw Error('Payload root changed');snapshot.set(relative,{...metadataOf(st),type:'directory'});walk(sub,relative);}finally{sub.close();}}else{if(typeOf(st)!==0o100000)throw Error('Payload file is not regular');const item=readCheckedFile(parent,name,st);if(!listed.has(relative)||crypto.createHash('sha256').update(item.bytes).digest('hex')!==listed.get(relative))throw Error(`Missing entry or hash mismatch: ${relative}`);files.set(relative,item.bytes);snapshot.set(relative,item.metadata);}}finally{for(const h of opened.reverse())h.close();}}
   for(const item of FIXED)select(item,false);for(const item of ROOTS)select(item,true);
-  for(const platform of ['codex','claude'])if(!referenceTrees[platform])throw Error('Required superpowers reference tree is missing');
+  for(const platform of ['codex','claude'])referenceTrees[platform]=validateFlatReferenceFiles(files,platform);
+  for(const{destination}of REFERENCE_PATH_MAP)if(!referenceTrees.codex.entries.get(destination).bytes.equals(referenceTrees.claude.entries.get(destination).bytes))throw Error('Imported platform parity mismatch: '+destination);
   for(const name of listed.keys())if(!files.has(name))throw Error(`Manifest entry is missing: ${name}`);
-  const required=['claude/skill/hooks/role-git-guard.mjs','claude/skill/hooks/git-policy.json','lib/policy/claude-hook.mjs','lib/policy/role-policy.json','lib/policy/render.mjs','scripts/update-role-policy.mjs','lib/limits.mjs','lib/installer/limits.mjs','lib/installer/runtime-config.mjs','README.md','install.command','package.json','bin/arc.mjs','lib/cli/root.mjs','lib/tui/app.mjs','lib/tui/terminal.mjs','lib/tui/render.mjs','lib/tui/setup.mjs','lib/tui/workflow.mjs','lib/management/operations.mjs','lib/management/status.mjs','lib/management/update.mjs','lib/management/workflow.mjs','lib/cli/postinstall.mjs','scripts/postinstall.mjs','lib/cli/upgrade.mjs','bin/arc-upgrade.mjs','lib/installer/shell-completion.mjs','lib/installer/manifest.mjs','lib/installer/targets.mjs','lib/installer/global-config.mjs','lib/installer/plan.mjs','lib/safe-fs/index.mjs','lib/safe-fs/native.mjs','lib/models/index.mjs','lib/models/config.mjs','lib/models/profiles.mjs','vendor/toml/LICENSE','vendor/toml/package.json','vendor/toml/provenance.json','vendor/toml/dist/index.js','prebuilds/index.json'];
+  const required=['claude/skill/hooks/role-git-guard.mjs','claude/skill/hooks/git-policy.json','lib/policy/claude-hook.mjs','lib/policy/role-policy.json','lib/policy/render.mjs','scripts/update-role-policy.mjs','lib/limits.mjs','lib/installer/limits.mjs','lib/installer/runtime-config.mjs','README.md','install.command','package.json','bin/arc.mjs','lib/cli/root.mjs','lib/tui/app.mjs','lib/tui/terminal.mjs','lib/tui/render.mjs','lib/tui/setup.mjs','lib/management/operations.mjs','lib/management/status.mjs','lib/management/update.mjs','lib/management/workflow.mjs','lib/cli/postinstall.mjs','scripts/postinstall.mjs','lib/cli/upgrade.mjs','bin/arc-upgrade.mjs','lib/installer/shell-completion.mjs','lib/installer/manifest.mjs','lib/installer/targets.mjs','lib/installer/global-config.mjs','lib/installer/plan.mjs','lib/safe-fs/index.mjs','lib/safe-fs/native.mjs','lib/models/index.mjs','lib/models/config.mjs','lib/models/profiles.mjs','vendor/toml/LICENSE','vendor/toml/package.json','vendor/toml/provenance.json','vendor/toml/dist/index.js','prebuilds/index.json'];
   required.push('lib/installer/runtime-assets.mjs',...RUNTIME_MODULE_PATHS);
   for(const platform of ['codex','claude'])required.push(`${platform}/skill/runtime/role-policy.json`,...RUNTIME_MODULE_PATHS.map(name=>`${platform}/skill/runtime/${name.slice('lib/runtime/'.length)}`));
   for(const tuple of ['darwin-arm64','darwin-x64','linux-arm64-gnu','linux-x64-gnu'])required.push(`prebuilds/${tuple}/arc_safe_fs.node`);

package/lib/installer/package-references.mjs

@@ -4,14 +4,17 @@ import path from 'node:path';
 import {openRoot} from '../safe-fs/index.mjs';
 import {loadNative} from '../safe-fs/native.mjs';
 import {acquireExternalSkills} from './acquisition.mjs';
-import {DYNAMIC_ROOTS,validateReferenceBundle} from './superpowers.mjs';
+import {REFERENCE_PATH_MAP,flattenReferenceBundle} from './superpowers.mjs';
+import {verifyPayload,renderManifest} from './manifest.mjs';
 import {inspectPath} from './targets.mjs';
 import {applyTransaction} from './transaction.mjs';
 
 export async function refreshPackageReferences({packageRoot,safeFs,acquisition,signal,hooks={}}){
  if(!safeFs){const native=loadNative({root:packageRoot});safeFs={openRoot:p=>openRoot(p,{native})};}
- const paths=DYNAMIC_ROOTS.map(root=>path.join(packageRoot,root)),snapshot=new Map();
- for(const filename of paths)inspectPath(safeFs,filename,{kind:'directory',tree:true,allowLinks:true,snapshot});
+ const payload=verifyPayload({packageRoot,safeFs,payloadMode:'source'}),paths=['codex','claude'].flatMap(platform=>REFERENCE_PATH_MAP.map(({destination})=>path.join(packageRoot,platform,'skill/references',destination)));
+ paths.push(path.join(packageRoot,'MANIFEST.sha256'));
+ const snapshot=new Map([...payload.snapshot].map(([name,item])=>[path.join(packageRoot,name),item]));
+ for(const name of ['MANIFEST.sha256','package-lock.json'])inspectPath(safeFs,path.join(packageRoot,name),{kind:'file',snapshot});
  let acquired;
  try{
   if(acquisition)acquired=await acquisition({signal});
@@ -20,9 +23,11 @@ export async function refreshPackageReferences({packageRoot,safeFs,acquisition,s
    try{acquired=await acquireExternalSkills({work,safeFs,signal});}catch(error){if(!error.residualPaths?.length)fs.rmdirSync(work);throw error;}
    const dispose=acquired.dispose;acquired.dispose=async()=>{await dispose();fs.rmdirSync(work);};
   }
-  validateReferenceBundle(acquired.references);
+  const flat=flattenReferenceBundle(acquired.references),candidate=new Map(payload.files),specs=[];
+  for(const platform of ['codex','claude'])for(const[destination,entry]of flat){const name=platform+'/skill/references/'+destination;candidate.set(name,entry.bytes);specs.push({path:path.join(packageRoot,name),bytes:entry.bytes});}
+  specs.push({path:path.join(packageRoot,'MANIFEST.sha256'),bytes:renderManifest(candidate)});
   const plan={target:{home:packageRoot},managedPaths:paths,externalPaths:[],snapshot};
-  const result=applyTransaction(plan,{safeFs,signal,hooks,specs:paths.map(filename=>({path:filename,tree:acquired.references.entries}))});
+  const result=applyTransaction(plan,{safeFs,signal,hooks,specs});
   if(result.cleanupError)throw result.cleanupError;
   return{...result,provenance:acquired.references.provenance};
  }catch(error){

package/lib/installer/plan.mjs

@@ -61,7 +61,7 @@ export function buildInstallPlan({payload,target,preset,skipGlobal=false,safeFs,
  for(const name of [home,skills,agents])inspectPath(safeFs,name,{kind:'directory',snapshot});
  inspectPath(safeFs,arc,{kind:'directory',tree:true,allowLinks:true,snapshot});
  const profilePaths=target.profileNames.map(name=>path.join(agents,name));for(const name of profilePaths)inspectPath(safeFs,name,{kind:'file',snapshot});
- const externalPaths=[],summary=['Fresh superpowers references will be acquired inside ARC'];
+ const externalPaths=[],summary=['Verified packaged Superpowers references will be installed inside ARC'];
  summary.push(`ARC limits: total ${limits.max_total_subagents}; concurrent ${limits.max_concurrent_subagents} (policy: ${arc}/limits.toml)`);
  const globalChanges=renderNativeChanges({target,safeFs,snapshot,skipGlobal,preview,concurrentExplicit,limits,summary,language});
  const managedPaths=[arc,...profilePaths,...(skipGlobal?[]:target.globalPaths)];

package/lib/installer/superpowers.mjs

@@ -2,7 +2,7 @@ import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {readCheckedFile,sameIdentity,typeOf,metadataOf} from './targets.mjs';
 export const REQUIRED=Object.freeze({
- 'brainstorming':['SKILL.md','visual-companion.md','scripts/start-server.sh','scripts/stop-server.sh','scripts/server.cjs','scripts/helper.js','scripts/frame-template.html'],
+ 'brainstorming':['SKILL.md','visual-companion.md','builder-check-prompt.md','scripts/start-server.sh','scripts/stop-server.sh','scripts/server.cjs','scripts/helper.js','scripts/frame-template.html'],
  'writing-plans':['SKILL.md'],
  'test-driven-development':['SKILL.md','writing-good-tests.md'],
 });
@@ -10,6 +10,12 @@ export const SKILLS=Object.freeze(Object.keys(REQUIRED));
 export const REPOSITORY='https://github.com/obra/superpowers';
 export const DYNAMIC_ROOTS=Object.freeze(['codex','claude'].map(platform=>`${platform}/skill/references/superpowers`));
 export const isDynamicReferencePath=name=>DYNAMIC_ROOTS.some(root=>name===root||name.startsWith(root+'/'));
+export const REFERENCE_PATH_MAP=Object.freeze([
+ ['brainstorming/SKILL.md','brainstorming.md'],['writing-plans/SKILL.md','writing-plans.md'],['test-driven-development/SKILL.md','test-driven-development.md'],
+ ['brainstorming/visual-companion.md','visual-companion.md'],['brainstorming/builder-check-prompt.md','builder-check-prompt.md'],['test-driven-development/writing-good-tests.md','writing-good-tests.md'],
+ ['brainstorming/scripts/start-server.sh','scripts/start-server.sh'],['brainstorming/scripts/stop-server.sh','scripts/stop-server.sh'],['brainstorming/scripts/server.cjs','scripts/server.cjs'],['brainstorming/scripts/helper.js','scripts/helper.js'],['brainstorming/scripts/frame-template.html','scripts/frame-template.html'],
+ ['LICENSE','superpowers-LICENSE'],['provenance.json','superpowers-provenance.json'],
+].map(([source,destination])=>Object.freeze({source,destination})));
 const hash=bytes=>createHash('sha256').update(bytes).digest('hex');
 function failure(message){throw new Error(message);}
 export function snapshotSkill(root,absolute,required){
@@ -111,3 +117,22 @@ export function composeArcSkillTree(skillFiles,references){
  entries.set('references',{type:'directory',mode:0o700n});entries.set('references/superpowers',{type:'directory',mode:0o700n});
  for(const[name,entry]of references.entries)entries.set('references/superpowers/'+name,{...entry});return entries;
 }
+export function flattenReferenceBundle(bundle){
+ validateReferenceBundle(bundle);const allowedFiles=new Set(REFERENCE_PATH_MAP.map(item=>item.source)),allowedDirectories=new Set();
+ for(const name of allowedFiles){const parts=name.split('/');for(let i=1;i<parts.length;i++)allowedDirectories.add(parts.slice(0,i).join('/'));}
+ for(const[name,entry]of bundle.entries){if(entry.type==='symlink')failure('Unsupported reference link in flat payload');if(entry.type==='file'&&!allowedFiles.has(name)||entry.type==='directory'&&!allowedDirectories.has(name))failure('Unsupported reference file in flat payload');}
+ return new Map(REFERENCE_PATH_MAP.map(({source,destination})=>{const entry=bundle.entries.get(source);if(entry?.type!=='file')failure('Required flat reference is missing or not regular');return[destination,{...entry,bytes:Buffer.from(entry.bytes)}];}));
+}
+export function validateFlatReferenceFiles(files,platform){
+ if(!(files instanceof Map)||!['codex','claude'].includes(platform))failure('Invalid flat reference input');
+ const prefix=platform+'/skill/references/',entries=new Map();
+ for(const name of files.keys())if(name.startsWith(prefix+'superpowers/'))failure('Unexpected nested reference payload');
+ for(const{source,destination}of REFERENCE_PATH_MAP){const bytes=files.get(prefix+destination);if(!Buffer.isBuffer(bytes))failure('Required flat reference file is missing: '+prefix+destination);const parts=source.split('/');for(let i=1;i<parts.length;i++)entries.set(parts.slice(0,i).join('/'),{type:'directory',mode:0o755n});entries.set(source,{type:'file',bytes,mode:0o644n});}
+ let provenance;try{provenance=JSON.parse(entries.get('provenance.json').bytes);}catch{failure('Malformed flat reference provenance');}
+ const bundle=validateReferenceBundle({entries,provenance});return{provenance,entries:flattenReferenceBundle(bundle)};
+}
+export function composeStaticArcSkillTree(skillFiles){
+ const entries=new Map();
+ for(const[name,bytes]of skillFiles){const parts=name.split('/');if(parts.some(part=>!part||part==='.'||part==='..')||name.includes('\\')||name.includes('\0')||name==='references/superpowers'||name.startsWith('references/superpowers/'))failure('Unsafe static ARC path');if(!Buffer.isBuffer(bytes))failure('Invalid static ARC bytes');for(let i=1;i<parts.length;i++)entries.set(parts.slice(0,i).join('/'),{type:'directory',mode:0o700n});entries.set(name,{type:'file',bytes:Buffer.from(bytes),mode:0o600n});}
+ return entries;
+}

package/lib/installer/transaction.mjs

@@ -1,4 +1,4 @@
-import {composeArcSkillTree} from './superpowers.mjs';
+import {composeStaticArcSkillTree} from './superpowers.mjs';
 import path from 'node:path';
 import {cleanupStage,captureCleanupEntry} from './stage-cleanup.mjs';
 import {randomUUID,createHash} from 'node:crypto';
@@ -53,13 +53,13 @@ function writeTree(directory,entries){
 }
 function snapshotEntry(parent,name){const stat=exists(parent,name);if(!stat)return null;const type=typeOf(stat);if(type===0o100000)return readCheckedFile(parent,name,stat).metadata;if(type===0o120000)return{...metadataOf(stat),type:'symlink',link:parent.readlink(name)};if(type===0o040000){const dir=parent.openDir(name);try{if(!sameObjectIdentity(stat,dir.stat()))fail('Entry directory changed');const entries=treeFromDirectory(dir);const hash=createHash('sha256');for(const[k,v]of entries){hash.update(JSON.stringify([k,v.type,...['dev','ino','mode','size','mtimeNs','ctimeNs'].map(field=>String(v.times[field])),v.bytes?.toString('hex')??v.link??null]));}return{...metadataOf(stat),type:'directory',sha256:hash.digest('hex'),children:captureCleanupEntry(parent,name).children};}finally{dir.close();}}fail('Special target entry');}
 function equalMoved(a,b){return a&&b&&['dev','ino','mode','size','mtimeNs','type','sha256','link'].every(k=>a[k]===b[k]);}
-export function applyTransaction(plan,{safeFs,acquired,signal,hooks={},specs:explicitSpecs}){
+export function applyTransaction(plan,{safeFs,signal,hooks={},specs:explicitSpecs}){
  assertPlanSnapshot(plan,{safeFs});const actions=[],areas=[],parents=[],created=[],actionLog=[],byParent=new Map();
  const cleanAreas=()=>{const paths=[],errors=[];for(const area of areas){const result=cleanupStage(area,{safeFs,hooks:{fault:event=>hooks.fault?.({...event,plan})}});paths.push(...result.residualPaths);if(result.cleanupError)errors.push(result.cleanupError);}return{paths,error:errors.length?Object.assign(new AggregateError(errors,errors.map(error=>error.message).join('; ')),{code:'ARC_INSTALL_CLEANUP',residualPaths:paths}):null};};
  const event=(phase,details={})=>{actionLog.push({phase,...details});if(signal?.aborted)throw new InstallError('Install interrupted','ARC_INSTALL_CANCELLED');hooks.fault?.({phase,...details,plan});};
  try{
   event('before-prepare');
-  const specs=explicitSpecs??plan.uninstallSpecs??[...plan.externalPaths.map(p=>({path:p,tree:acquired.skills.get(path.basename(p))?.entries,rootMetadata:acquired.skills.get(path.basename(p))?.rootMetadata})),{path:plan.target.home+'/skills/arc',tree:composeArcSkillTree(plan.generated.skill,acquired.references)},...[...plan.generated.profiles].map(([name,bytes])=>({path:plan.target.home+'/agents/'+name,bytes})),...plan.globalChanges.map(change=>({path:change.path,bytes:change.content}))];
+  const specs=explicitSpecs??plan.uninstallSpecs??[{path:plan.target.home+'/skills/arc',tree:composeStaticArcSkillTree(plan.generated.skill)},...[...plan.generated.profiles].map(([name,bytes])=>({path:plan.target.home+'/agents/'+name,bytes})),...plan.globalChanges.map(change=>({path:change.path,bytes:change.content}))];
   for(const spec of specs){if(!spec.remove&&!spec.tree&&!Buffer.isBuffer(spec.bytes))fail('Missing verified staged data');const parent=openParent(safeFs,spec.path,created);parents.push(parent);const name=path.basename(spec.path);event('before-stage',{path:spec.path});let area=byParent.get(path.dirname(spec.path));if(area&&!sameObjectIdentity(parent.stat(),area.parent.stat()))fail('Reused staging parent identity changed','ARC_INSTALL_DRIFT');if(!area){const stageName='.arc-stage-'+randomUUID();parent.mkdir(stageName,0o700);const stage=parent.openDir(stageName);area={parent,stage,name:stageName,path:path.dirname(spec.path)+'/'+stageName,identity:stage.stat(),expected:new Map()};areas.push(area);byParent.set(path.dirname(spec.path),area);}const stage=area.stage,preparedName='prepared-'+actions.length,previousName='previous-'+actions.length,rollbackName='rollback-installed-'+actions.length;
    if(spec.remove){}
    else if(spec.tree){stage.mkdir(preparedName,0o700);const dir=stage.openDir(preparedName);try{writeTree(dir,spec.tree);if(spec.rootMetadata)finishDirectory(dir,spec.rootMetadata.mode,spec.rootMetadata);else dir.sync();}finally{dir.close();}}

package/lib/installer/upgrade.mjs

@@ -1,6 +1,3 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
 import {buildInstallPlan,validatePlanSet} from './plan.mjs';
 import {assertPlanSnapshot} from './transaction.mjs';
 import {inspectPath} from './targets.mjs';
@@ -8,7 +5,6 @@ import {renderManagedBlock,removeManagedBlock,agentsBlockBody} from './global-co
 import {attachShellCompletionCleanup} from './shell-completion.mjs';
 import {verifyPayload} from './manifest.mjs';
 import {installTargets} from './install.mjs';
-import {acquireExternalSkills} from './acquisition.mjs';
 export function buildUpgradePlans({payload,state,safeFs}){
  for(const entry of state.targets)assertPlanSnapshot(entry,{safeFs});
  const plans=state.targets.map(entry=>{
@@ -22,10 +18,7 @@ export function buildUpgradePlans({payload,state,safeFs}){
  attachShellCompletionCleanup(plans,{safeFs});
  validatePlanSet(plans);return plans;
 }
-export async function upgradeInstalledTargets({packageRoot,state,safeFs,signal,acquisition}){
+export async function upgradeInstalledTargets({packageRoot,state,safeFs,signal}){
  const payload=verifyPayload({packageRoot,safeFs}),version=JSON.parse(payload.files.get('package.json').toString('utf8')).version,plans=buildUpgradePlans({payload,state,safeFs});
- const acquire=acquisition??(async()=>{const work=fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()),'arc-acquire-'));let acquired;
-  try{acquired=await acquireExternalSkills({work,safeFs,signal});}catch(error){if(!error.residualPaths?.length)try{fs.rmdirSync(work);}catch(cleanup){throw Object.assign(new AggregateError([error,cleanup],'Cannot clean private acquisition work'),{code:'ARC_ACQUISITION_CLEANUP',residualPaths:[work]});}throw error;}
-  return{...acquired,dispose:async()=>{await acquired.dispose();fs.rmdirSync(work);}};});
- return{version,...await installTargets(plans,{safeFs,signal,acquisition:acquire})};
+ return{version,...await installTargets(plans,{safeFs,signal})};
 }