@yunhozz/arc 0.2.1 → 0.2.3

package/claude/skill/references/planning.md

@@ -2,28 +2,23 @@
 
 ## Authorization and scope
 
-An explicit execution request is authorization only for its sufficiently specified scope. Confirm execution intent,
+An explicit execution request authorizes only its sufficiently specified scope. Confirm execution intent,
 expected outcome, constraints, document depth, and verification risk, with no unresolved material behavior, method,
-or risk decision requiring the user. The request itself or a description explicitly referenced by the user must
-supply that scope. Record authorization evidence, scope, acceptance criteria, constraints, and depth in the brief or
-canonical record. Routine execution and check choices may be recorded by Orchestrator; added product behavior or
-material scope cannot be claimed as already approved. A restatement, role handoff, or restart does not create an
-approval requirement for the same scope.
+or risk decision requiring the user. That scope must come from the request or a description the user explicitly references. Record authorization evidence, scope, acceptance criteria, constraints, and depth in the brief or
+canonical record. Orchestrator may record routine execution and check choices; added product behavior or material scope is not already approved. Restating or handing off the same scope, or restarting, requires no new approval.
 
 Silence, ambiguous assent, approval of other work, and unspecified blanket improvement requests are not authorization.
 Planner's new material choices are not automatically approved. Ask for the missing material decision; roles route
 questions to Orchestrator. Required written specs and plans still require their individual approval in the order below.
 
-For material changes to scope, method, or risk, hold affected work and explain the missing decision or evidence and
-remaining work. Target changes, unclear ownership, unexpected state, unresolved failures, or missing required inputs
+Material scope, method, or risk changes hold affected work; explain the missing decision or evidence and remaining work. Target changes, unclear ownership, unexpected state, unresolved failures, or missing required inputs
 also hold affected work under [handoff](handoff.md) and [git-recovery](git-recovery.md). Distinguish new authorization
 needs from execution issues within existing scope: ordinary corrections and reverification do not require duplicate
 approval after failure. Revalidate affected gates after resolution.
 
 ### Probe scope
 
-A probe-only scope completes with findings, evidence, limits, and remaining uncertainty answering the approved question;
-a well-supported infeasibility result can complete it. Probe-only authorization does not authorize product retention
+A probe-only scope completes by answering the approved question with findings, evidence, limits, and remaining uncertainty; well-supported infeasibility can complete it. Probe-only authorization does not authorize product retention
 or subsequent implementation. Record question, method/scope, criteria, and constraints; a sufficiently specific probe
 request can supply that approval. Match checks to probe purpose/risk and do not report probe evidence as product proof.
 
@@ -36,12 +31,11 @@ remains separate.
 
 ## Formal drafting boundary
 
-Initial design proposals and brainstorming may precede execution-target choice. Formal spec or plan drafting includes a
-complete draft before saving, even when returned only in chat. Before formal drafting and saving, Orchestrator supplies
+Initial design proposals and brainstorming may precede execution-target choice. Formal spec or plan drafting includes a complete draft before saving, even when returned only in chat. Before formal drafting and saving, Orchestrator supplies
 and records the actual absolute workspace/repository, branch or detached HEAD, HEAD, changes and ownership,
 explicit choice and preparation evidence, and absolute document paths inside that target. Planner drafts for that
 verified workspace; Orchestrator saves directly in the selected target. Missing or mismatched evidence stops the
-affected drafting or save and is reported to Orchestrator. Planned scope and paths do not establish actual preparation.
+affected drafting or save and is reported to Orchestrator. Planned scope and paths do not prove actual preparation.
 Initial target preparation does not authorize Implementer; the complete handoff gate still applies.
 
 Orchestrator classifies scope before implementation. The Orchestrator direct path for small tasks is defined only in
@@ -58,31 +52,43 @@ Orchestrator preserves that language when saving.
 
 ## Planner drafting preparation and consolidated feedback
 
-Before formal drafting, Orchestrator performs a preflight of relevant policy, reference, profile, test, parity and
-manifest surfaces and conflicts. Provide one complete brief with actual absolute workspace/repository, branch or
-detached HEAD, HEAD, change state and ownership, explicit target choice and preparation evidence, approved preceding
-design/spec/plan versions, scope and exclusions, design/plan depth, dependencies and shared contracts, acceptance
-criteria, required QA/focused checks and evidence, hold conditions and open decisions. Resolve missing or conflicting
-required evidence first or hold that stage.
-
-Planner returns a complete proportional draft and self-review for the current approval stage. Orchestrator integrates,
-saves, reviews and obtains approval. Orchestrator checks once with a fixed checklist: scope and evidence; targets,
-ownership and paths; policy surfaces and conflicts; task boundaries, dependencies and acceptance criteria; checks,
-evidence and holds; roles, approval and commit boundaries; draft completeness. Gather all substantive omissions into
-one consolidated follow-up request to Planner. Do not split requests by omission or author the missing plan yourself.
-
-Initial design, required spec approval, and formal plan drafting/approval remain separate ordered stages.
-Allow additional Planner calls for substantive omissions or user-approved scope/evidence changes. There is no fixed
-call cap; never accept an incomplete draft to minimize calls. Do not add call-count conditions to Planner profiles.
-
-The complete initial brief identifies original user requirements, criteria IDs, approved decisions and open decisions;
-current behavior and connected source, generated, runtime, installer and documentation surfaces; conflicting rules and
-resolution direction; exact current-stage deliverable and absolute output path. Keep the shared brief's fixed field order
-in [coordination](coordination.md). Link accessible evidence and needed ranges instead of full dialogue or raw logs.
-Consolidated feedback contains changed fields only and marks remaining fields `unchanged` relative to the received brief.
-Do not call Planner again for already resolved questions. Missing target preparation or required decisions holds formal
-drafting; initial design proposals may still precede target selection. Written-spec approval precedes dependent plan drafting.
-
+1. Before formal drafting, Orchestrator performs a preflight of relevant policy, reference, profile, test, parity
+   and manifest surfaces and conflicts. Apply the Formal drafting boundary above and coordination's instruction
+   provenance, input-state and local-skill rules, including required reference paths, authorized bounded read
+   alternatives and return conditions. Missing required inputs or unresolved conflicts hold dependent drafting;
+   Planner returns them to Orchestrator. Optional read recovery grants no preparation, verification, writing or
+   approval authority.
+
+2. Maintain a compact ledger of original requirements/criteria IDs, approved and open decisions, exclusions and
+   scope deltas; merge intervening user changes into one next-brief delta. Distinguish user-approved decisions,
+   verified source facts with exact paths and lines, assumptions and open decisions.
+
+3. Send one complete brief for the initial call of each stage, using coordination's shared fields and evidence-link
+   rules. Include the prepared workspace, branch or detached HEAD, HEAD and ownership; scope, exclusions, depth,
+   dependencies, shared contracts, acceptance criteria, required QA/focused checks, evidence and holds. Identify
+   preceding approved versions, document/output paths, current behavior and connected source, generated, runtime,
+   installer and documentation surfaces, policy conflicts and resolution direction, open decisions and the exact
+   stage deliverable. For visual work, include approved sources/versions, criteria and unresolved interpretations.
+
+4. Planner returns a complete proportional draft and self-review. Orchestrator integrates, saves, reviews and
+   obtains approval; never authors missing content. Review the complete draft once with this fixed checklist:
+   scope and evidence; targets, ownership and paths; policy surfaces and conflicts; task boundaries, dependencies
+   and acceptance criteria; checks, evidence and holds; roles, approval and commit boundaries; draft completeness.
+   Finish the checklist before sending all substantive omissions in one consolidated follow-up request.
+   Identify each criterion, defect, evidence and expected correction. Follow coordination's changed-fields-only
+   and `unchanged` rules. Do not split requests by omission.
+
+5. After that correction, additional Planner calls require user-approved material scope/evidence changes or
+   concrete unmet checklist items, plus meaningful new input or criterion-state progress. Identify changed input,
+   target criterion, expected artifact and expected progress. Distinguish approved scope changes from ordinary
+   omissions within existing scope; omissions require no renewed scope approval. If the same criterion remains
+   unmet without meaningful new input, evidence or progress, hold the stage and report the criterion, observed
+   evidence and exact unblock input or decision. Do not repeat resolved questions, reword the same request, or
+   count rewording or agent replacement as meaningful input or progress.
+
+Initial design, required spec approval, and formal plan drafting/approval remain separate ordered stages;
+written-spec approval precedes dependent plan drafting. No fixed call cap applies; never accept an incomplete draft
+to reduce calls or add call-count conditions to Planner profiles.
 
 ## Design path and plan depth
 
@@ -204,9 +210,7 @@ Written-spec approval precedes dependent plan drafting. On document-omission pat
 steps; preserve target choice, preparation, state/ownership checks and Implementer gates.
 
 While documents are being written, reviewed, or approved, do not stage documents or commit planning documents.
-Selection and initial target preparation happen before formal drafting; document completion is a staging/commit gate,
-not an initial preparation gate. An incomplete set or missing applicable approval blocks document commit and Implementer,
-not the initial choice request. No early Implementer work is authorized by approval of only some documents.
+Select and initially prepare the target before formal drafting. Document completion gates staging/commit, not initial preparation. An incomplete set or missing applicable approval blocks document commit and Implementer, but not the initial choice request. No early Implementer work is authorized by approval of only some documents.
 
 This ARC defers the local brainstorming early spec commit: save and self-review the spec, obtain written-spec
 approval without committing, then write and approve all plans; commit the spec only in the final batch.
@@ -231,8 +235,7 @@ and preparation are complete. Then reflect the approved plan version in its orig
 ## Plan updates during execution
 
 Mechanical execution records may be recorded without new user approval: checkbox completion, actual results, evidence
-links and task completion state that preserve the approved execution contract. Record their classification, reason and
-actual recording time in the canonical handoff record. Required checks' removal, invented success, unsupported acceptance
+links and task completion state that preserve the approved execution contract. Record their classification, reason and actual recording time in the canonical handoff record. Required checks' removal, invented success, unsupported acceptance
 or scope changes mixed with a completion mark are not mechanical records.
 
 Changes to goals, task scope or boundaries, acceptance criteria, method, risk, dependencies or required verification
@@ -242,8 +245,7 @@ follow the document-version approval rules; classify typos, paths, commands and
 
 Both mechanical records and approved contract revisions amend the original planning-document commit at a safe checkpoint.
 Make no separate document commit or fixup commit, including for newly approved scope. Preserve implementation task commits.
-This history update does not make actual approval time retroactive: the latest plan in the original commit is not evidence
-that its contents were approved from the outset. Never use rewritten history to justify work started before approval.
+This history update does not backdate approval: the latest plan in the original commit does not prove its contents were approved from the outset. Never use rewritten history to justify work started before approval.
 
 In the canonical handoff record preserve plan absolute/Git paths; before and after content hashes and versions; prior and
 revised approval references and actual times; change reason and classification; affected tasks and hold/preparation/resume
@@ -269,9 +271,9 @@ Return scope changes and unresolved decisions to the user through Orchestrator.
 
 ## 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.
 
 
 ## Instruction and Input Provenance
@@ -281,11 +283,11 @@ Give the Planner the exact paths and access state for required skills and refere
 [ARC role policy: contract begin]
 Generated from lib/policy/role-policy.json; do not edit this managed section manually.
 - [git.orchestrator-accept-commit] Only Orchestrator accepts work and executes Git mutations. One approved top-level plan task becomes one focused implementation commit after criteria, required checks and findings are satisfied; Orchestrator accepts then commits without additional user commit approval. Reports, passing checks and Reviewer opinions do not replace acceptance. Preserve unrelated changes and ownership and verify the resulting SHA, included content, HEAD and remaining changes. Existing small-task direct and plan-omission paths are unchanged.
-- [review.significant-no-plan] For significant/high-risk work without a plan: Implementer → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. MUST NOT omit Reviewer merely because no plan exists. This creates no new plan obligation.
-- [review.significant-plan] For significant/high-risk plan work: each task uses Implementer → fresh QA as required → Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.
+- [review.significant-no-plan] For significant/high-risk work without a plan: Implementer → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. MUST NOT omit Reviewer because no plan exists. This creates no new plan obligation.
+- [review.significant-plan] For significant/high-risk plan work: each task uses Implementer → fresh QA as required → Orchestrator acceptance and focused commit. Reviewer reviews the final full change once after all tasks are accepted and required QA is complete. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.
 - [review.final-plan-recheck] For final overall Reviewer findings on plan work, including behavior findings, use Implementer → Reviewer without QA reassignment; repeat until resolved. This exception applies only at the final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.
 - [planning.plan-amend] During approved task execution, mechanical plan progress records need no new user approval; changed goals, scope, criteria, method, risk, dependencies or required verification require revised-version approval and preparation before affected work. In both cases Orchestrator amends the original planning-document commit at a safe boundary, without a separate document or fixup commit. Preserve actual approval chronology, recoverable old/new contents, hashes, versions and SHA mappings; never retroactively authorize earlier work. Rewrite only unpublished, unshared local linear history with clear ownership and no merges; stop on unknown publication, ownership, unexpected state or replay conflicts, without force push or a fallback document commit. Preserve implementation task boundaries and revalidate affected evidence. See planning, handoff-prep, commit and verification for the full contract.
-- [planning.planner-brief] Before formal drafting, Orchestrator supplies one complete stage-specific brief with original requirements and criteria IDs, approved/open decisions, verified target and ownership, document paths and preceding approved versions, current behavior and connected source/generated/runtime/installer/documentation surfaces, policy conflicts, depth, dependencies, checks, holds and exact deliverable. Preserve shared brief field order. Review the complete draft once and consolidate substantive feedback as changed fields with other fields marked unchanged. Preserve sequential design, spec and plan approvals; no fixed call cap or incomplete drafts, and no calls for already resolved questions. Include instruction provenance and input states, required skill/reference paths, bounded read alternatives and return conditions, approved visual sources/versions and criteria, and unresolved interpretation decisions before dependent drafting. Planner returns incomplete required inputs to Orchestrator; optional reading recovery never grants preparation, verification, writing or approval authority.
+- [planning.planner-brief] Follow planning.md's Planner drafting preparation and consolidated feedback procedure, including preflight, ledger, evidence classification, target preparation, preceding approvals, provenance and reference gates. Send one complete stage-specific initial brief. Planner returns a complete proportional draft and self-review; Orchestrator reviews once with the fixed checklist and sends one consolidated correction using changed fields only. Additional Planner calls require user-approved material scope/evidence changes or concrete unmet checklist items after correction, plus meaningful new input or criterion-state progress; state changed input, target criterion, expected artifact and expected progress. Hold repeated unmet criteria without new input, evidence or progress and report the criterion, observed evidence and exact unblock input or decision. Do not split omissions, repeat resolved items, or count rewording or agent replacement as progress. Preserve separate sequential design/spec/plan approvals; no fixed call cap, Planner-profile call-count conditions or incomplete draft acceptance.
 - [platform.claude] Existing per-role tool allowlists reduce available tools; Bash and role contracts are not a filesystem sandbox. A role-scoped Git guard is a separate integration and is not supplied by these policy sections alone.
 [ARC role policy: contract end]
 

package/claude/skill/references/verification.md

@@ -102,7 +102,7 @@ Orchestrator accepts using verdicts, findings, rechecks, and remaining gaps, not
 disposition never turns unverified into proven. Low-risk work without QA likewise links each criterion to Orchestrator
 focused-check evidence.
 
-Read brief-cited `references/superpowers/test-driven-development/SKILL.md`; preserve ARC TDD exceptions.
+Read brief-cited `references/test-driven-development.md`; preserve ARC TDD exceptions.
 
 
 ### Final plan Reviewer correction loop
@@ -123,8 +123,8 @@ report only checks actually performed, their actor, target state, results and re
 Once applicable authorization, document-depth, execution-target, and handoff conditions hold for the approved scope,
 continue through execution, correction, reverification, required QA and Reviewer, findings disposition, Orchestrator
 acceptance, and the result report. Apply risk-scaled timing above; this adds no per-task Reviewer or new QA obligation.
-A role completion report, probe findings, or passing commands are not overall completion when approved work remains.
-Remaining approved execution is not an optional suggestion waiting for a user response. A probe-only scope
+Role reports, probe findings, or passing commands do not establish overall completion while approved work remains.
+Do not present remaining approved execution as an optional suggestion awaiting a user response. A probe-only scope
 ends at its approved question's evidence and limits; a combined scope continues under planning's scope rules.
 Document omission changes neither verification risk nor acceptance responsibility. Hold only affected work for an
 actual unmet condition and report what is needed to resume. Structural evidence does not prove live agent compliance.
@@ -133,9 +133,9 @@ For Orchestrator, **Evidence verdict**: each criterion is proven, unmet, or unve
 
 ## Visual Evidence and Adjudication
 
-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.
+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 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.
+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.
 
 ## Risk-scaled execution
 
@@ -205,7 +205,7 @@ This is an operator verdict record; it does not replace semantic proof of a crit
 Failures, unknown, mismatch and unverified outcomes are not passing evidence. Preserve previous results and failure records.
 
 A failed check/review leaves an open finding. Link a separate finding to an existing check/review through `record` with
-`data: {action: "open", id, checkId, message}`. After a Implementer fix, record
+`data: {action: "open", id, checkId, message}`. After an Implementer fix, record
 `data: {action: "resolve", id, actor: {id, role: "implementer"}, changeFingerprint}` and the fix evidence messageRef.
 The actor must be the Implementer assigned to that task, or a relevant task for an overall finding. This marks the finding resolved;
 it becomes closed only when a subsequent prepare includes it in `findingIds` and revalidation passes for the same change version.
@@ -257,8 +257,8 @@ A changed runtimeHash follows the existing stale/hold rules; the stored version
 [ARC role policy: contract begin]
 Generated from lib/policy/role-policy.json; do not edit this managed section manually.
 - [git.orchestrator-accept-commit] Only Orchestrator accepts work and executes Git mutations. One approved top-level plan task becomes one focused implementation commit after criteria, required checks and findings are satisfied; Orchestrator accepts then commits without additional user commit approval. Reports, passing checks and Reviewer opinions do not replace acceptance. Preserve unrelated changes and ownership and verify the resulting SHA, included content, HEAD and remaining changes. Existing small-task direct and plan-omission paths are unchanged.
-- [review.significant-no-plan] For significant/high-risk work without a plan: Implementer → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. MUST NOT omit Reviewer merely because no plan exists. This creates no new plan obligation.
-- [review.significant-plan] For significant/high-risk plan work: each task uses Implementer → fresh QA as required → Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.
+- [review.significant-no-plan] For significant/high-risk work without a plan: Implementer → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. MUST NOT omit Reviewer because no plan exists. This creates no new plan obligation.
+- [review.significant-plan] For significant/high-risk plan work: each task uses Implementer → fresh QA as required → Orchestrator acceptance and focused commit. Reviewer reviews the final full change once after all tasks are accepted and required QA is complete. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.
 - [review.final-plan-recheck] For final overall Reviewer findings on plan work, including behavior findings, use Implementer → Reviewer without QA reassignment; repeat until resolved. This exception applies only at the final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.
 - [planning.plan-amend] During approved task execution, mechanical plan progress records need no new user approval; changed goals, scope, criteria, method, risk, dependencies or required verification require revised-version approval and preparation before affected work. In both cases Orchestrator amends the original planning-document commit at a safe boundary, without a separate document or fixup commit. Preserve actual approval chronology, recoverable old/new contents, hashes, versions and SHA mappings; never retroactively authorize earlier work. Rewrite only unpublished, unshared local linear history with clear ownership and no merges; stop on unknown publication, ownership, unexpected state or replay conflicts, without force push or a fallback document commit. Preserve implementation task boundaries and revalidate affected evidence. See planning, handoff-prep, commit and verification for the full contract.
 - [platform.claude] Existing per-role tool allowlists reduce available tools; Bash and role contracts are not a filesystem sandbox. A role-scoped Git guard is a separate integration and is not supplied by these policy sections alone.

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

@@ -1,21 +1,299 @@
-# Visual companion
+# Visual Companion Guide
 
-Use a visual when it materially helps design discussion or verification. Orchestrator determines the available
-capability and consent required by the actual tool. Planner returns visualization needs to Orchestrator because its
-tools are read-only file inspection; do not invent browser or shell access for it.
-Other depth 2 roles must stay within their exact allowlists and may not delegate visualization to another agent.
+Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
 
-Determine actual available browser and preview capabilities before use; do not assume the platform provides a preview tool.
-Use an available authorized local/browser workflow only when scoped by Orchestrator.
-Keep preview artifacts separate from user files, record generated side effects, preserve unrelated work,
-and report unavailable capabilities without claiming visual verification. MUST NOT expose secrets or publish a preview without authorization.
+## When to Use
 
-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.
+Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
 
-## Follow-up Verification of Approved Visual Sources
+**Use the browser** when the content itself is visual:
 
-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.
+- **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
 
-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.
+**Use the terminal** when the content is text or tabular:
+
+- **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
+
+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.
+
+## 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`