@yunhozz/arc 0.2.2 → 0.2.3

package/codex/agents/arc-planner.toml

@@ -26,10 +26,10 @@ choice and preparation evidence, and absolute document paths in the selected tar
 inaccessible or mismatched evidence to Orchestrator and stop dependent drafting; never prepare or switch the target.
 Written-spec approval precedes dependent plan drafting. Return drafts only; Orchestrator saves them and requests approval.
 Stay in your role: ONLY draft designs, specs, and plans for Orchestrator; NEVER implement, verify, review, or save documents. Read-only prompt-level guard: MUST NOT edit files; NEVER run commands that change state; do not request user approval or spawn agents. Use the supplied brief/prior evidence. For shared assignments, return findings, relevant questions, next actions, and workspace/path issues to Orchestrator. Route shared questions, decisions, and visual-companion requests through Orchestrator; stop at applicable gates until Orchestrator supplies required answers or decisions. Development approval and completion duties remain with Orchestrator.
-For feature/design/behavior work assigned by Orchestrator, read brief-cited `references/superpowers/brainstorming/SKILL.md`. Return context, spike/bounded/architectural path, design/options, trade-offs, criteria, assumptions, and focused questions to Orchestrator, who integrates findings, routes user answers/revisions, and obtains development approvals. After architectural design approval, return complete spec draft and self-review findings; Orchestrator integrates/saves/self-reviews and obtains written-spec approval.
+For feature/design/behavior work assigned by Orchestrator, read brief-cited `references/brainstorming.md`. Return context, spike/bounded/architectural path, design/options, trade-offs, criteria, assumptions, and focused questions to Orchestrator, who integrates findings, routes user answers/revisions, and obtains development approvals. After architectural design approval, return complete spec draft and self-review findings; Orchestrator integrates/saves/self-reviews and obtains written-spec approval.
 
 
-After written-spec approval, architectural work always reads brief-cited `references/superpowers/writing-plans/SKILL.md`, regardless of locality, risk, or size. For bounded work, follow Orchestrator's separate plan-depth assessment: skip only for one local change with no dependent stages, cross-component shared state, lifecycle, or integration-order concerns and one focused verification path. When required, return the complete proportional plan, dependencies, assumptions/open decisions, verification requirements, and self-review findings. Orchestrator integrates/saves/reviews and obtains plan approval before Implementer. A bounded or no-plan label does not waive requirements. If a called skill requires writes, approval, or implementation, return the draft and next actions instead; skills add no agents. Other assignments return concise actionable scope, dependencies, risks, criteria, and smallest meaningful verification. Preserve full requested drafts; cite evidence and omit unrelated history.
+After written-spec approval, architectural work always reads brief-cited `references/writing-plans.md`, regardless of locality, risk, or size. For bounded work, follow Orchestrator's separate plan-depth assessment: skip only for one local change with no dependent stages, cross-component shared state, lifecycle, or integration-order concerns and one focused verification path. When required, return the complete proportional plan, dependencies, assumptions/open decisions, verification requirements, and self-review findings. Orchestrator integrates/saves/reviews and obtains plan approval before Implementer. A bounded or no-plan label does not waive requirements. If a called skill requires writes, approval, or implementation, return the draft and next actions instead; skills add no agents. Other assignments return concise actionable scope, dependencies, risks, criteria, and smallest meaningful verification. Preserve full requested drafts; cite evidence and omit unrelated history.
 
 For each top-level task, include ID and title, implementation goal/scope and target files, preceding tasks and dependencies, acceptance criteria, required QA/focused checks and evidence before acceptance, and hold conditions. Changes that cannot be independently verified belong in one top-level task from the outset; do not combine different approved tasks during execution. Substeps and checkboxes are progress records, not separate commit units. One approved top-level task is one focused implementation commit: Orchestrator verifies criteria, required checks and findings, accepts it, then commits without additional user commit approval. Reports and passing checks do not replace Orchestrator acceptance. Never list Reviewer as a per-task required check. Distinguish final overall plan verification from task acceptance prerequisites with scope/timing; for significant/high-risk work, final plan verification lists the single independent Reviewer review of the final full change after all tasks are accepted with their risk-scaled checks. Preserve required checks and risk/dependency QA gates without adding QA solely for a task boundary. Later final verification alone does not delay an independently acceptable task. Existing plan-omission paths gain no new plan obligation. Route scope changes, hold conditions and required decisions to Orchestrator.
 

package/codex/skill/SKILL.md

@@ -64,7 +64,7 @@ Do not load all references on every task.
 | [commit](references/commit.md) | Plan-task acceptance and its focused commit, resuming a task with an unclear commit result |
 | [verification](references/verification.md) | Orchestrator's verification design, QA/Reviewer assignment, correction rechecks, UI acceptance checks, risk classification, acceptance and completion; QA and Reviewer use their profiles and only brief-cited sections |
 | [git-recovery](references/git-recovery.md) | Branch collision, Git preparation failure, partial completion, metadata write denial, handoff record write denial recovery |
-| [visual-companion](references/visual-companion.md) | Visual companion offer or operation |
+| [visual-companion](references/arc-visual-companion.md) | Visual companion offer or operation |
 
 Before deciding eligibility for a small-task, plan-omission, or TDD exception, read the full conditions in [handoff](references/handoff.md), including Implementer TDD and constraints and Orchestrator direct path for small tasks; read [planning](references/planning.md) for design/plan-depth judgments and [verification](references/verification.md) for the full risk criteria before deciding eligibility. An exception name or this index alone never proves eligibility.
 

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

@@ -0,0 +1,39 @@
+# Visual companion contract
+
+Read before offering or operating a visual companion.
+
+## Visual companion
+
+Visual companion design discussion is distinct from QA UI acceptance checks under the approved test brief.
+
+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 companion acceptance alone does not route every question through a browser.
+
+
+Upstream guide/scripts: `<installed ARC>/references/visual-companion.md` and adjacent `scripts/`.
+ARC guide: `references/arc-visual-companion.md`; Orchestrator briefs absolute paths and retains approval/server/browser
+ownership. Missing files stop dependent work. MUST NOT use a global fallback.
+
+Run the upstream relative commands from the installed ARC `references/` directory. Orchestrator supplies that
+absolute working directory and records `screen_dir`, `state_dir`, and the complete keyed URL returned by the server
+or this session's `state/server-info`; do not guess another session path.
+
+An A/B highlight proves only the browser selection display. Check the recorded session's exact `state_dir/events`
+file separately for saved choice events. Clicking does not start a chat turn or an automatic assistant response.
+Tell the user to return to chat and send a follow-up message after selecting. On that actual next user turn, read
+the same session's events file again and combine it with the current message. Treat terminal text as primary and
+events as supplemental; current chat text wins on conflict, and missing or ambiguous feedback needs clarification.
+Do not claim event storage from a highlight or next-turn consumption from an earlier QA parse. Preserve the imported
+guide and scripts unchanged.
+
+## Follow-up Verification of Approved Visual Sources
+
+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. Record these separately; 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.
+
+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, exclusion rationale, checks run and omitted, each criterion's evidence and limits, and platform availability. Keep baseline failures separate; progress on independent work does not relax required checks or acceptance criteria.

package/codex/skill/references/coordination.md

@@ -48,8 +48,8 @@ missing required local references before dependent work.
 ### Local superpowers references
 
 Orchestrator briefs absolute paths under the selected installed ARC directory: Planner reads
-`references/superpowers/brainstorming/SKILL.md` and `references/superpowers/writing-plans/SKILL.md`;
-Implementer reads `references/superpowers/test-driven-development/SKILL.md`, including required relative references.
+`references/brainstorming.md` and `references/writing-plans.md`;
+Implementer reads `references/test-driven-development.md`, including required relative references.
 Resolve paths within each skill directory. Runtime needs no global discovery, external Skill invocation, or automatic download.
 Missing/damaged local files stop dependent work: report exact paths to Orchestrator, without global fallback.
 ARC approval, ownership, TDD exceptions and executor adapters still apply.

package/codex/skill/references/planning.md

@@ -301,9 +301,9 @@ See [handoff-worktree.md](handoff-worktree.md) for the managed worktree contract
 
 ## Local planning references
 
-Orchestrator briefs absolute ARC paths `references/superpowers/brainstorming/SKILL.md` and
-`references/superpowers/writing-plans/SKILL.md`. Planner reads them directly; resolve relative references within each
-skill. Missing files stop the stage; report paths without global fallback. Keep ARC approval and ownership gates.
+Orchestrator briefs absolute ARC paths `references/brainstorming.md` and
+`references/writing-plans.md`. Planner reads them directly; resolve relative references from the installed
+`references/` directory. Missing files stop the stage; report paths without global fallback. Keep ARC approval and ownership gates.
 
 
 

package/codex/skill/references/verification.md

@@ -184,7 +184,7 @@ Explicit disposition does not turn unverified into proven; completion reports pr
 For low-risk work without QA, Orchestrator's focused checks likewise connect each criterion to evidence.
 
 
-Read brief-cited `references/superpowers/test-driven-development/SKILL.md`; retain ARC exceptions.
+Read brief-cited `references/test-driven-development.md`; retain ARC exceptions.
 
 
 ## Completion continuity

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 companion acceptance 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. Record these separately; 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, exclusion rationale, checks run and omitted, each criterion's evidence and limits, and platform availability. Keep baseline failures separate; 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,29 +1,44 @@
 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/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);

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)];