@yunhozz/arc 0.2.3 → 0.2.4

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

@@ -1,33 +1,28 @@
+<a id="visual-companion"></a>
 # Visual companion
 
-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.
+Use visuals when they materially help design discussion or verification. Orchestrator determines actual capability/consent. Planner has read-only file tools and returns visualization needs; do not invent browser/shell access. Other depth-2 roles stay within exact allowlists and cannot delegate visualization.
 
-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.
+- Verify actual browser/preview capability; never assume platform preview support.
+- Use an available authorized local/browser flow only within Orchestrator scope.
+- Separate preview artifacts from user files, record side effects and preserve unrelated work. Report unavailable capability without claiming visual verification.
+- Never expose secrets or publish previews without authorization.
 
-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.
+Upstream guide/scripts: `<installed ARC>/references/visual-companion.md` and adjacent `scripts/`. ARC guide: `references/arc-visual-companion.md`. Orchestrator supplies absolute paths and owns approval/server/browser. Missing files stop dependent work; no 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.
+1. Run upstream relative commands from installed ARC `references/`; Orchestrator supplies the absolute working directory.
+2. Record `screen_dir`, `state_dir` and the complete keyed URL from the server or this session's `state/server-info`. Never guess another session path.
+3. A/B highlighting proves selection display only. Separately inspect that session's exact `state_dir/events` for saved events. Clicking starts neither a chat turn nor an automatic response.
+4. Tell the user to return to chat and send a follow-up after selection. On the actual next turn, reread the same events file and combine it with the current message. Current chat text is primary; events are supplemental. Chat wins conflicts; clarify missing/ambiguous feedback.
+5. Do not infer storage from highlighting or next-turn consumption from an earlier QA parse. Preserve imported guide/scripts.
 
-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 current chat 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.
+<a id="follow-up-verification-of-approved-visual-sources"></a>
+## Follow-up verification of approved visual sources
 
-## Follow-up Verification of Approved Visual Sources
+Each visual criterion requires exact approved source location/version/approval/access state, criterion IDs/properties/comparison method and actual-output-to-revision evidence. Implementer reporting does not replace fresh QA comparison.
 
-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.
+- Record pass/mismatch/unverified and connect to proven/unmet/unverified criterion verdicts. Pass requires accessible evidence meeting the criterion; unsupported claims remain unverified.
+- Missing revision linkage is unverified; visible difference is mismatch. Record separately without inferring current branch UI state.
+- Hold comparison for inaccessible source/output or missing interpretation approval.
 
-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.
+Static policy/generated-file/manifest checks prove structure only, not actual role behavior, installed builds, Claude Code CLI compliance or visual fidelity. Report changes, exclusions, run/omitted checks, criterion evidence/limits and platform availability. Separate baseline failures. Independent progress never relaxes checks/criteria.

package/claude/skill/references/commit.md

@@ -1,85 +1,53 @@
+<a id="focused-commits"></a>
 # Focused commits
 
-Orchestrator reviews task evidence and accepts the approved task before committing.
-Verify approved plan/task, absolute workspace, branch/HEAD, index/worktree/untracked state and ownership.
-Stage exactly the accepted task paths; inspect staged scope and content to exclude unrelated changes.
-After acceptance, Orchestrator creates the focused local commit without additional user commit approval.
-After Orchestrator accepts a task, the next action is the required Git state/scope checks, staging, and focused commit.
-Do not commit before task acceptance or defer the task commit until the plan ends.
-Only Orchestrator accepts the task and executes its focused commit; Implementer completion does not replace acceptance.
-Existing plan-skip paths have no new automatic commit obligation; their commits follow applicable guidance and user requests.
-Commit one logical task promptly, using Conventional Commits with a concise English description.
-Task acceptance/commit is distinct from final plan acceptance; remaining final checks and Reviewer timing follow verification.
-Planning documents have their own batch docs commit before Implementer handoff.
-
-After commit, verify exact SHA, subject, included paths, branch/HEAD and remaining index/worktree state.
-Preserve unrelated changes; never automatically unstage, amend, reset, clean, stash, or delete branches.
-On failure, stop dependent work and report actual state and completed steps.
-MUST NOT blindly repeat a commit or staging command.
-Push, merge, publish, deploy, and install still follow their separate guidance and approval rules.
-Implementer must not commit, even when explicitly assigned.
-
-Hold the task commit for unmet or unresolved criteria, failed or not-run required checks, undispositioned findings or
-evidence gaps, scope expansion, ownership or staged scope/content mismatch, unexpected workspace/branch/HEAD/Git state,
-or Git failure/partial completion; record the reason and next action. Never waive unmet criteria or required checks to
-commit. If commit creation is unclear, stop and inspect before any retry (see git-recovery).
-
-For a no-change task make no empty commit; record acceptance evidence and no change.
-On resume verify the same task's existing commit SHA, content, and validity and reuse it; never duplicate a successful
-task commit. For final Reviewer findings on already committed plan work, Orchestrator defines a follow-up task and required
-planning/approvals. Implementer leaves corrections uncommitted during rechecks. Orchestrator refreshes the latest committed
-state plus uncommitted diff and changed-file list in the Reviewer artifact/brief. Reuse an independent Reviewer or
-assign another independent Reviewer as needed. Repeat Implementer → Reviewer without QA reassignment until findings are
-resolved; Orchestrator then accepts the corrections and creates one focused follow-up commit.
-Final QA findings retain Implementer correction and QA recheck before a new focused commit.
-Do not automatically amend/reset or duplicate the original task commit. Scope expansion keeps existing new
-planning and approval obligations.
-
-Commit message form: `<type>(<scope>): <description>` (Conventional Commits) with a concise, specific English description
-without trailing period, lowercase scope when useful, one top-level task per commit, body/footer only when needed.
-
-In the accessible canonical record link plan path/version, task ID, acceptance evidence and Orchestrator judgment,
-required checks and findings, commit results and state, hold/no-change/reuse reasons, and remaining final verification.
+Read before approved top-level task acceptance/focused commit or resuming uncertain commit results.
 
+<a id="automatic-commit-after-plan-task-acceptance"></a>
+## Automatic commit after plan-task acceptance
+
+One approved top-level task is one focused implementation commit. Orchestrator verifies criteria/current checks/findings, accepts by judgment, then immediately commits locally without separate user commit approval. After acceptance, check Git state/scope, stage and commit. Never commit before acceptance or defer until plan completion. Implementer completion is not acceptance; explicit assignment never permits Implementer commits.
+
+Substeps/checkboxes track progress, not commits. Completion marks/reports/passing checks do not establish acceptance; connect conditions/expected results to evidence. Plan omission creates neither new plans nor automatic commits; follow applicable guidance/user requests. Push/merge/publish/deploy/install retain separate approvals. Reviewer timing follows [verification](verification.md#risk-scaled-execution).
+
+1. Before commit verify approved plan version/task ID/accepted scope, actual absolute workspace/repository/branch or detached HEAD/HEAD, staged/unstaged/untracked state and ownership.
+2. Verify staged content/paths include only this task and final message. Prove safe separation of other tasks/user changes in shared files. Unrelated staging blocks commit under Preservation rule.
+3. After commit verify SHA/message/paths/content, HEAD/branch and remaining state. Successful exit alone proves no completion.
+4. Canonically link plan path/version, task ID, acceptance evidence/judgment, required checks/findings, commit results/state, hold/no-change/reuse reasons and remaining final verification.
+
+Hold commits for unmet/unresolved criteria, failed/not-run required checks, undispositioned findings/gaps, scope expansion/revised-plan needs, ownership/staged scope/content mismatch, unexpected workspace/branch/HEAD/Git state or failure/partial completion. Record reason/next action; never waive criteria/checks to commit. Disposition follows Evidence verdict. Inspect actual branch/HEAD/index/working tree/partial completion before retry; uncertain commit creation stops immediate retries. Orchestrator follows [recovery](git-recovery.md), resolves and revalidates evidence.
+
+No-change tasks record acceptance/no change without empty commits. Resume verifies/reuses the same task's SHA/content/validity without duplication. Missing records require actual-result inspection before retry. Normal accepted commits retain valid choice reuse with fresh state/ownership checks. Task acceptance/commit differs from final plan acceptance; remaining QA/Reviewer/integration checks retain their timing.
+
+For final Reviewer findings on committed plan work, define follow-up task/required planning/approvals. Implementer leaves corrections uncommitted through rechecks. Orchestrator refreshes committed state plus uncommitted diff/changed-file list in Reviewer artifacts/briefs. Reuse/assign an independent Reviewer; repeat Implementer → Reviewer without QA reassignment until resolved, then accept and create one focused follow-up commit. Final QA findings retain Implementer → QA before a new commit. Never automatically amend/reset/duplicate originals. Scope expansion retains planning/approval duties.
+
+Local commit authority never permits early planning-document commits. Pre-Implementer approvals/explicit target/batch preparation remain. Never retroactively alter historical spec/plan records. Structural checks prove no live compliance.
+
+Use Conventional Commits `<type>(<scope>): <description>` with concise specific English description, no trailing period, lowercase scope when useful and one logical task. Body/footer only when needed; preserve Git trailers.
+
+<a id="execution-time-plan-document-updates"></a>
 ## Execution-time plan document updates
 
-Plan progress and approved revised plan contracts follow [planning](planning.md#plan-updates-during-execution).
-At a safe boundary Orchestrator amends the original planning-document commit; no separate document or fixup commit.
-Mechanical records need no new user approval; changes to the approved execution contract require revised-version approval
-and preparation before affected work. Preserve actual approval chronology; rewriting never approves earlier work retroactively.
-Apply [handoff-prep](handoff-prep.md#execution-time-plan-amendment) safety and preservation checks, recoverable contents and
-old-to-new SHA mappings. Shared/published or unknown history, merges, unclear ownership, unexpected state or replay conflict
-stops affected work without force push or fallback document commit. Revalidate evidence under verification after rewriting.
+Follow [planning](planning.md#plan-updates-during-execution). At safe boundaries amend the original planning-document commit, with no separate docs/fixup commit. Mechanical records need no new approval; contract changes need revised-version approval/preparation before affected work. Preserve actual chronology; no retroactive authorization.
 
-This is a plan-document exception only. Implementation task acceptance, focused commits and correction follow-up commits
-retain the rules above; do not combine tasks or include implementation changes in the document commit. The initial complete
-approved document batch still precedes Implementer handoff. Existing document approvals and authority limits remain required.
+Use [preparation](handoff-prep.md#execution-time-plan-amendment) safety/preservation, recoverable content and old→new SHA mappings. Shared/published/unknown history, merges, unclear ownership, unexpected state/replay conflicts stop affected work without force push/fallback docs commits. Revalidate evidence afterward.
 
-## Shared-checkout coordination
+This exception is plan-document-only. Preserve implementation acceptance, focused commits and correction follow-ups. Never combine tasks or put implementation into docs commits. Initial complete approved batch still precedes handoff. Existing approvals/authority remain.
 
-Orchestrator serializes shared-checkout Git mutations, including index/staging and commits, across concurrent tasks;
-parallel Implementers do not operate competing Git transactions. Preserve every other task's unfinished staged, unstaged
-and untracked changes and ownership. Commit only the accepted task after scope/content verification; unrelated staged
-changes block the commit under the Preservation rule. Do not require unrelated unstaged work to finish or include it
-in the accepted task's commit. Unclear separation or ownership holds affected work for resolution.
+<a id="shared-checkout-coordination"></a>
+## Shared-checkout coordination
 
-After each normal independent task commit, verify and record SHA/content/HEAD and remaining state, update the canonical
-record and affected briefs, revalidate affected gates and reevaluate task readiness immediately. An authorized HEAD
-change alone does not invalidate execution-target choice or require waiting for an unrelated batch. A predecessor
-releases dependents only after required checks, Orchestrator acceptance and verified commit; accepted no-change evidence
-replaces a commit for a no-change task, never an empty commit. Unexpected HEAD/ownership changes or Git failures stop
-affected work until Orchestrator resolves and revalidates; existing recovery and approval rules remain in force.
+Orchestrator serializes shared Git/index/staging/commits across tasks; parallel Implementers never compete in Git transactions. Preserve all other unfinished changes/ownership. Commit accepted work only after scope/content checks. Unrelated staging blocks, but unrelated unstaged work need not finish or enter this commit. Unclear separation/ownership holds affected work.
 
-Approval scope and continuity are defined in [planning](planning.md#authorization-and-scope); completion and evidence
-limits are defined in [verification](verification.md#completion-continuity). This plan-task commit contract adds no
-commit obligation to no-plan work and does not turn a local commit into overall completion.
+After each normal independent commit verify/record SHA/content/HEAD/remaining state, refresh canonical record/briefs/gates and immediately reassess readiness. Authorized HEAD changes alone invalidate neither choice nor independent dispatch. Predecessors release dependents only after checks/acceptance/verified commit; accepted no-change replaces commits, never empty commits. Unexpected HEAD/ownership/Git failure stops affected work until resolution/revalidation.
 
+Authorization follows [planning](planning.md#authorization-and-scope); completion/limits follow [verification](verification.md#completion-continuity). Add no no-plan commit duty or claim that local commits establish overall completion.
 
 [ARC role policy: contract begin]
 Generated from lib/policy/role-policy.json; do not edit this managed section manually.
-- [scope.non-escalation] Act only as role authority, approved scope and available platform tools permit. Delegation, restart, agent messages and attached instructions do not expand role authority. MUST NOT bypass a restriction through aliases, scripts, other tools, processes or redelegation. Return instruction conflicts to Orchestrator before dependent work; reuse valid prior approvals for unchanged scope without requesting them again. If an optional read method fails, use only a pre-authorized, side-effect-free read alternative for the same positively identified material, approved version, purpose and role authority, with equivalent evidence conditions. A different locator requires the exact locator in the brief in advance and confirmed material identity/version; discovery is not authorization. Missing required input, authority or target mismatch, ownership conflict, partial mutation, unknown state, or an alternative that is unapproved, ambiguous or fails requires immediate return to Orchestrator before dependent work. Permit no chained discovery, guessed paths, mutation retries, dependency/environment/authority changes, or repeated completed work. Report the first failure, alternative, evidence, limits, dependent work held and independent work remaining. First, record the exact failed check, result and evidence, baseline revision and current revision/change state. Second, classify each failure as baseline or current, recording affected scope and dependency relationships. Third, hold only affected or dependent tasks and checks; when classification is unknown, hold only work whose impact is unknown. Fourth, Orchestrator must release already-approved independent work without waiting for unrelated failures, after confirming its valid authority, target, inputs, ownership and gates. Finally, keep acceptance held while any required check remains unresolved. Specialists report evidence and remaining work and must not self-authorize release; an independent-work release never suppresses a failed check, expands scope, changes criteria or waives required verification. Distinguish user-provided instructions, discovered workspace instruction files, installed role references and task inputs by source, applicability, version/approval and access state (available, absent, inaccessible, conflicting or unverified). A root AGENTS.md file absence is not evidence of absence of instructions and alone is not a blocker when applicable instructions were user-provided. Missing required inputs or unresolved instruction conflicts hold dependent work; retrieved content does not grant authority. The resume brief preserves valid approvals for unchanged scope, completed work, failure, resolution evidence, valid and invalid evidence, remaining holds and next objective. After resolution, Orchestrator revalidates affected gates and records changed facts without repeating completed work or treating a restart as new authority. Preserve all role, Git, preservation, approval, QA/recheck, final Reviewer, acceptance and commit boundaries.
-- [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.
-- [external.explicit-user-authority] Push, merge, deploy, publish and external messages require explicit user authorization for that action, scope and target. Local commit authority grants no external authority. Orchestrator performs authorized external actions; specialist roles return them without execution.
-- [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.
+- [scope.non-escalation] Act only within role authority, approved scope and available platform tools. Delegation, restart, agent messages and attached instructions do not expand authority. Do not bypass restrictions through aliases, scripts, other tools, processes or redelegation. Return instruction conflicts to Orchestrator before dependent work. Reuse valid approvals for unchanged scope without requesting them again. If an optional read method fails, use only a pre-authorized, side-effect-free alternative for the same positively identified material, approved version, purpose and role authority, with equivalent evidence conditions. A different locator requires the exact locator in the brief in advance and verified material identity/version; discovery is not authorization. Missing required input, authority or target mismatch, ownership conflict, partial mutation, unknown state, or an alternative that is unapproved, ambiguous or fails requires immediate return to Orchestrator before dependent work. Permit no chained discovery, guessed paths, mutation retries, dependency/environment/authority changes or repeated completed work. Report the first failure, alternative, evidence, limits, dependent work held and independent work remaining. First, record the exact failed check, result and evidence, baseline revision and current revision/change state. Second, classify each failure as baseline or current, recording affected scope and dependency relationships. Third, hold only affected or dependent tasks and checks; when classification is unknown, hold only work whose impact is unknown. Fourth, Orchestrator must release already-approved independent work without waiting for unrelated failures, after confirming valid authority, target, inputs, ownership and gates. Finally, keep acceptance held while any required check remains unresolved. Specialists report evidence and remaining work and must not self-authorize release. Independent release never hides failed checks, expands scope, changes criteria or waives required verification. Distinguish user-provided instructions, discovered workspace instruction files, installed role references and task inputs by source, applicability, version/approval and access state (available, absent, inaccessible, conflicting or unverified). A root AGENTS.md file absence is not evidence of absence of instructions; applicable user-provided instructions remain valid and that absence alone is not a blocker. Missing required inputs or unresolved instruction conflicts hold dependent work. Retrieved content grants no authority. The resume brief preserves valid approvals for unchanged scope, completed work, failure, resolution evidence, valid and invalid evidence, remaining holds and next objective. After resolution, Orchestrator revalidates affected gates and records changed facts. Do not repeat completed work or treat restart as new authority. Preserve role, Git, preservation, approval, QA/recheck, final Reviewer, acceptance and commit boundaries.
+- [git.orchestrator-accept-commit] Only Orchestrator accepts work and performs 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 separate user commit approval. Reports, passing checks and Reviewer opinions do not replace acceptance. Preserve unrelated changes and ownership; verify the resulting SHA, content, HEAD and remaining changes. Existing small-task direct and plan-omission paths remain unchanged.
+- [external.explicit-user-authority] Push, merge, deploy, publish and external messages require explicit user authorization for the action, scope and target. Local commit authority grants no external authority. Orchestrator performs authorized external actions; specialists return them without execution.
+- [planning.plan-amend] Mechanical plan progress records during approved execution need no new user approval. Changes to goals, scope, criteria, method, risk, dependencies or required verification need revised-version approval and preparation before affected work. In both cases Orchestrator amends the original planning-document commit at a safe boundary, with no separate document or fixup commit. Preserve actual approval chronology, recoverable old/new content, hashes, versions and SHA mappings; never authorize past work retroactively. Rewrite only unpublished, unshared local linear history with clear ownership and no merges. Unknown publication/ownership, unexpected state or replay conflicts stop rewriting; no force push or fallback document commit. Preserve implementation task boundaries and revalidate affected evidence. Follow 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. ARC supplies no native observer hook or Bash Git guard; Git restrictions remain prompt-level role contracts.
 [ARC role policy: contract end]

package/claude/skill/references/coordination.md

@@ -1,146 +1,97 @@
+<a id="role-assignment-and-coordination"></a>
 # Role assignment and coordination
 
-Orchestrator reads this before first creating or assigning a specialist and making related coordination decisions. Also read [limits](limits.md) and installed `../limits.toml` before first creation. Missing, inaccessible or conflicting references stop dependent work; report the exact paths.
+Before first specialist creation/assignment and related decisions, Orchestrator reads this. Also read [limits](limits.md) and installed `../limits.toml` before creation. Report exact missing/inaccessible/conflicting paths; hold dependent work.
 
+<a id="ownership"></a>
 ## Ownership
 
-- Orchestrator: sole owner of development, configuration, tests, implementation-dependent documentation, and mixed tasks
-  requiring implementation, assigning their edits to Implementer. Coordinates scope, planning, approvals, integration,
-  acceptance, verification, and completion.
-- Scouter: read-only material research/analysis and assigned static code/document/data/log exploration. Reports
-  evidence, assumptions, unresolved questions, impact, next actions, and workspace/path issues to Orchestrator.
-  Does not edit files, author standalone documents, or decide design/plans, verification, review, or completion.
-- Planner: returns design/spec/plan drafts.
-- Implementer edits assigned, approved implementation/configuration/test-code files and assigned dependent docs.
-  Orchestrator does not edit them directly except under the Orchestrator direct path for small tasks.
-- QA: verifies without edits.
-- Reviewer: independently reviews the final full change.
-- All five roles report directly to Orchestrator at depth 2: Scouter, Planner, Implementer, QA, and Reviewer.
-  Orchestrator is depth 1.
-  Depth-2 roles cannot create agents or delegate tasks to another role. Reviewer remains independent.
-- Claude native subagent names: Scouter=`arc-scouter`, Planner=`arc-planner`, Implementer=`arc-implementer`, QA=`arc-qa`,
-  Reviewer=`arc-reviewer`.
-- Across the full tree, obey configured limits for simultaneous subagents, including Scouter; there are no reserved slots.
-  Before first creating a subagent, read `references/limits.md` and installed `limits.toml`; maintain its cumulative ledger and reservations.
-  Parallelize independent tasks only; dependent handoffs are sequential and editing scopes cannot overlap. These are
-  ARC limits, not verified runtime concurrency or depth capabilities. Use Claude native subagent execution with
-  the installed native name and receive its completion result; report unavailable execution capabilities to
-  Orchestrator.
-- Scouter, Planner, and Reviewer do not edit, execute commands, or save standalone documents; QA verifies without edits.
-  Each role stays within its shipped tool allowlist; a tool list is not a filesystem sandbox.
+| Role | Ownership and return |
+|---|---|
+| Orchestrator | Sole coordinator of development/configuration/tests/dependent docs/mixed implementation. Assigns edits to Implementer; owns scope, planning, approval, integration (save/route/request approval, never author), verification, acceptance and completion |
+| Scouter | Read-only material research/analysis and assigned static exploration. Reports evidence, assumptions, questions, impact, next actions and path issues. No editing, standalone documents or design/plan/verification/review/completion decisions |
+| Planner | Returns design/spec/plan drafts |
+| Implementer | Edits approved assigned implementation/configuration/tests/dependent docs; Orchestrator direct edits only under the small-task path |
+| QA | Verifies without editing |
+| Reviewer | Independently reviews the final full change |
 
+Orchestrator is depth 1. All five specialists report directly at depth 2 without creating agents/delegating. Reviewer stays independent.
 
+Claude native names: Scouter=`arc-scouter`, Planner=`arc-planner`, Implementer=`arc-implementer`, QA=`arc-qa`, Reviewer=`arc-reviewer`.
+
+Across the tree, obey concurrency including Scouter. No reserved role slots. Read limits before first creation and maintain cumulative ledger/reservations. Parallelize independent tasks only; dependent handoffs are sequential and edit scopes never overlap.
+
+ARC limits do not prove native concurrency/depth support. Invoke installed native names and receive results; report unavailable execution. Scouter/Planner/Reviewer cannot edit, execute commands or save documents. QA verifies without edits. Stay within shipped allowlists, which are not filesystem sandboxes.
+
+<a id="instruction-and-execution-adapter"></a>
 ## Instruction and execution adapter
 
-Native Claude profiles use Markdown frontmatter with the `effort` field.
-The native `env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` value is a string, distinct from ARC's ledger limits.
-The native tool allowlists and prompt guards are not a filesystem sandbox; local declarations do not prove runtime enforcement.
-
-Apply platform, user, and project instructions according to their precedence, then ARC rules for ownership,
-permissions, models, concurrency, routing, and approvals, then the local ARC reference assigned to the role. A called skill
-adds no agents or authority. Map executor requests such as `superpowers:executing-plans` and
-`superpowers:subagent-driven-development` to Orchestrator's dependency-aware coordination and risk-scaled verification;
-this replaces executor mechanics and any separate execution-method choice, including prompts in an existing local reference.
-Preserve plan approval, workspace, design, spec, and other applicable requirements, including TDD subject to the
-explicit ARC exception in [handoff](handoff.md#implementer-tdd-and-constraints). Adapt local `brainstorming` role, save, and early spec commit instructions to
-ARC Planner ownership and evidence gates in planning/handoff; preserve upstream reference content. Report conflicts or
-missing required local references before dependent work.
-
-Planner, Reviewer, and Scouter return findings, relevant questions, next actions, and workspace/path issues to the
-Orchestrator. Planner preserves complete requested drafts. Orchestrator integrates results (save, route,
-obtain approval; never author), routes decisions and required approvals,
-and owns development acceptance and completion. Orchestrator runs dependent implementation tasks sequentially and starts a fresh Implementer for each top-level task (Role gate); reuse the current Implementer only for corrections, rework,
-or rechecks of the same task while the approved scope, workspace, ownership, and relevant assignment context remain valid;
-default to the current Implementer for same-task QA corrections. A QA finding within the current task does not itself create a new task. Before sending corrections or rework to a reused Implementer, Orchestrator rechecks workspace, branch/HEAD and change state against the brief.
-Replace or restart a role only when its context is invalid or unavailable, or the task boundary changes, subject to the
-amendment exception below. A fresh Implementer for the next task is a restart under handoff (choice reuse and restart brief rules are in handoff).
-After an approved plan or acceptance-criteria amendment, start a fresh Implementer for
-the remaining work even within the same task; it is also a restart under handoff. Do not add per-task QA or
-review gates solely because a task boundary exists; apply risk requirements and specific approved obligations. If the
-next task depends on a still-unverified risky contract, complete applicable QA at that dependency boundary and
-resolve or explicitly disposition findings before dependent implementation. This does not create a gate for every task.
-
-
-## Token discipline and handoffs
-
-- Only Orchestrator invokes Claude native subagents or assigns specialist tasks. Give each invocation a descriptive role
-  and bounded objective; the installed native profile determines its role and local model declarations.
-
-- Keep one shared brief in this fixed field order: Goal; Criteria (IDs); Exact scope/ownership (absolute workspace,
-  branch or detached HEAD and HEAD, handoff record path, when one exists, files);
-  Constraints/decisions; Evidence (paths/lines, commands, artifact links); Prior findings; Exact next objective (one
-  bounded objective); Return format (conclusion, evidence locations, unresolved points, next step).
-  On follow-ups send only changed fields and mark the rest `unchanged` (relative to a brief the recipient received);
-  restart briefs follow handoff; a fresh specialist gets every other field in full. Send only the self-contained subset the next role needs and links to accessible artifacts; omit full history, repeated instructions, and raw logs. No findings may be brief; requested deliverables such as complete plan drafts remain
-  complete. Cite paths/lines/pages/commands/links instead of logs; investigate gaps only.
-- `AskUserQuestion` questions use only `question`, a `header` of at most 12 characters, 2-4 `options` each with `label`
-  and `description`, and `multiSelect`.
-- Always start an ARC role by its installed native name (`arc-*`) with only the supplied scoped brief;
-  never use a context-inheriting fork (such as the `fork` subagent type) for an ARC role; do not claim fresh context
-  isolation without evidence. Reuse an existing specialist for related follow-up with only changed facts/objective when
-  its context
-  remains relevant; start fresh for unrelated or bloated context. Implementer and QA freshness follow the Role gate.
-- Cite in the brief the absolute path of each required local ARC reference's SKILL.md (`test-driven-development` for Implementer,
-  `brainstorming`/`writing-plans` for Planner); the role Reads it before dependent work.
-- For Reviewer, Orchestrator writes the final base..HEAD diff plus changed-file list to
-  `<git-common-dir>/arc/review/<slug>.diff` (same slug as the handoff record; base is the approved base HEAD recorded at
-  handoff; inline when small or write denied) and cites its absolute path in the brief; Reviewer reads it and states
-  limits. See verification.
-- In Implementer briefs, cite the plan/spec path with the task section's line range and include only the needed excerpts,
-  acceptance criteria, and constraints; do not ask Implementer to read whole plans or specs.
-- Follow [Planner drafting preparation and consolidated feedback](planning.md#planner-drafting-preparation-and-consolidated-feedback).
-  Complete the initial brief and whole-draft checklist before sending consolidated corrections. Gate further calls
-  on documented changes or criterion progress; hold repetition without progress.
-- Before optional calls, name the unresolved question and expected artifact. Skip calls for questions resolved by available evidence or direct inspection.
-- Run each ARC role as a foreground Agent call and use its returned result, or run it in the background and wait for the
-  completion notification; report unavailable execution to Orchestrator rather than inventing an API.
-  Do not poll status in loops; never sleep-poll. A timeout or delay is not a reason to poll or check status in between.
-  Send one complete brief per objective and batch related corrections. For long Bash commands set a sufficient `timeout`
-  or use `run_in_background` and wait for its completion notification.
-
-- Read only the needed ranges of files and outputs (for example `rg -n`, `sed -n`, `head`/`tail`) and cap long command
-  output. Do not re-read files or outputs already in context unless they changed. A mandatory reference already read in this context and unchanged need not be re-read, and this skill file, once read in this context and unchanged, is not re-read on follow-up turns; this does not shorten any triggered mandatory reference read.
-- When a plan completes or before starting another plan in a session with long history, Orchestrator records the canonical handoff state in the handoff record file and recommends that the user continue in a new session.
-- Before handoff, post one short update with role/objective/expected output; after return, combine findings and next
-  stage concisely. Do not expose hidden reasoning or raw prompts.
-
-### Local superpowers references
-
-Orchestrator briefs absolute paths under the selected installed ARC directory: Planner reads
-`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.
+Claude profiles use Markdown frontmatter with `effort`. Native `env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` is a string separate from the ARC ledger. Allowlists/prompts are not a filesystem sandbox; declarations prove no enforcement.
 
+Apply platform/user/project instructions by precedence, then ARC ownership/permissions/models/concurrency/routing/approval and role-local references. Skills add neither agents nor authority. Map `superpowers:executing-plans`/`superpowers:subagent-driven-development` to dependency-aware Orchestrator coordination and risk-scaled verification, replacing executor mechanics and separate execution-method prompts in existing references.
 
-## Models
+Preserve plan approval, workspace, design, spec and all applicable requirements. TDD uses only [handoff](handoff.md#implementer-tdd-and-constraints)'s explicit ARC exceptions. Adapt local `brainstorming` role/save/early-spec-commit instructions to Planner ownership and planning/handoff evidence gates, preserving upstream text. Report conflicts/missing required references before dependent work.
+
+Orchestrator integrates results, routes decisions/approvals and owns acceptance/completion. Run dependent implementation sequentially with a fresh Implementer per top-level task. Reuse current Implementer only for same-task correction/rework/rechecks while scope/workspace/ownership/context remain valid. Default same-task QA corrections to it; findings alone create no new task. Before reuse, compare actual workspace, branch/HEAD and change state to the brief.
+
+Replace/restart only for invalid/unavailable context or changed task boundary, except approved plan/criteria amendments require a fresh Implementer for remaining work even within the same task. Next-task and amendment assignments are handoff restarts, subject to choice reuse/restart briefs. Follow [risk-scaled execution](verification.md#risk-scaled-execution) at task boundaries.
+
+Planner/Reviewer/Scouter return findings/questions/actions/path issues; Planner preserves complete drafts. Task boundaries alone add no QA/review. Unverified risky dependencies require boundary QA and resolved/explicitly dispositioned findings before implementation, not blanket task gates.
+
+<a id="local-superpowers-references"></a>
+### Local Superpowers references
 
-`models.toml` beside this skill is the source of truth for role model and reasoning-effort settings.
-Configuration keys `arc_scouter`, `arc_planner`, `arc_implementer`, `arc_qa`, and `arc_reviewer` map to the hyphenated
-Claude native subagent names above; they are not tool-call names.
-Orchestrator uses the current conversation model. Use configured role settings without substitution or effort reduction; report unavailable settings.
-Local declarations do not prove runtime provider support, account access, alias resolution, actual model or effort
-application, concurrency or depth enforcement.
-New sessions reload profiles; running agents retain their current settings and parent relationships. Configuration
-changes do not automatically reparent running agents or prove runtime parent behavior.
+Supply absolute paths under the selected installed ARC directory. Planner reads `references/brainstorming.md`/`references/writing-plans.md`; Implementer reads `references/test-driven-development.md` and required relative references. Resolve relatives within skill directories. Runtime needs no global discovery/external Skill call/automatic download. Missing/damaged files stop dependent work; report paths without global fallback. Preserve ARC approvals, ownership, TDD exceptions and executor adapters.
+
+<a id="token-discipline-and-handoffs"></a>
+## Context discipline and handoffs
+
+Only Orchestrator invokes/assigns Claude roles. Describe role and bounded objective. Installed native profiles determine role/local models.
+
+Use this fixed brief order:
+
+1. Goal
+2. Criteria (IDs)
+3. Exact scope/ownership: absolute workspace, branch or detached HEAD and HEAD, existing record path, files
+4. Constraints/decisions
+5. Evidence: paths/lines, commands, artifact links
+6. Prior findings
+7. Exact next objective: one bounded objective
+8. Return format: conclusion, evidence locations, unresolved points, next step
+
+- Follow-ups send changed fields only; mark others `unchanged` relative to a received brief. Restarts follow handoff; fresh specialists receive other fields in full.
+- Send a self-contained needed subset and accessible artifacts. Omit full history/repeated instructions/raw logs. No-findings reports may be brief; requested full drafts remain complete. Cite locations/commands/links, investigating gaps only.
+- `AskUserQuestion` uses only `question`, `header` of at most 12 characters, 2–4 `options` with `label`/`description`, and `multiSelect`.
+- Start installed `arc-*` names with scoped briefs only, never inheriting forks such as `fork`; claim fresh isolation only with evidence. Reuse valid related context, not unrelated/bloated context. Role gate governs Implementer/QA freshness.
+- Brief absolute local ARC SKILL.md paths: `test-driven-development` for Implementer, `brainstorming`/`writing-plans` for Planner. Read before dependent work.
+- Write final base..HEAD diff/changed-file list to `<git-common-dir>/arc/review/<slug>.diff`, using handoff slug/approved base HEAD. Inline if small or write denied. Reviewer reads and states limits; follow verification.
+- Implementer briefs cite spec/plan task-section line ranges and needed excerpts/criteria/constraints; never request whole-document reading.
+- Follow [Planner preparation/feedback](planning.md#planner-drafting-preparation-and-consolidated-feedback). Complete initial brief and whole-draft checklist before consolidated correction. Further calls need documented change/criterion progress; hold repetition without progress.
+- Before optional calls name the unresolved question/expected artifact. Skip questions already resolved by evidence/direct inspection.
+- Use foreground Agent results or background completion notifications. Report unavailable execution; invent no API. Never poll/sleep-poll for timeout/delay. Batch corrections in one brief. Long Bash uses sufficient `timeout` or `run_in_background` plus completion notification.
+- Read needed file/output ranges only (`rg -n`, `sed -n`, `head`/`tail`) and cap output. Do not reread unchanged context material. Already-read unchanged mandatory references/SKILL.md need no follow-up reread; newly triggered mandatory reads remain required.
+- At plan completion or before another plan in a long session, record canonical handoff and recommend a new session.
+- Before handoff briefly state role/objective/output; after return combine findings/next stage. Never expose hidden reasoning/raw prompts.
+
+<a id="models"></a>
+## Models
 
-For browser visualization needs read [visual-companion](arc-visual-companion.md). Use only capabilities
-available within each role's exact allowlist; report unavailable capabilities and preserve unverified visual scope.
+Adjacent `models.toml` is authoritative for role models/effort. Orchestrator uses the current model. Do not substitute settings or reduce effort; report unavailability. Declarations prove no provider support/account access/alias resolution/actual model-effort application/concurrency/depth enforcement. New sessions reload profiles; running agents retain settings/parents. Changes do not automatically reparent or prove runtime parent behavior.
 
-Claude profile `model` and `effort` frontmatter values are shipped defaults; installation overwrites them with the active `models.toml` preset values.
+`arc_scouter`, `arc_planner`, `arc_implementer`, `arc_qa`, `arc_reviewer` settings map to hyphenated native names, not tool calls. For visualization read [visual companion](arc-visual-companion.md), use only actual allowlisted tools and report unavailable/unverified scope. Shipped `model`/`effort` defaults are replaced with active `models.toml` preset at installation.
 
-## Instruction and Input Provenance
+<a id="instruction-and-input-provenance"></a>
+## Instruction and input provenance
 
-Each role brief records the source, applicability, version or approval, and access state of user-provided instructions, discovered workspace instruction files, installed role references, and task inputs. Use only policy-authorized recovery for optional reads, and report the initial failure and dependent or independent work. If required material is missing, return it to the Orchestrator without inventing an interpretation or authority. Follow [handoff](handoff.md#instruction-sources-bounded-read-recovery-visual-evidence-and-resumption) for the full fields.
+Briefs identify source/applicability/version or approval/access state for user instructions, discovered workspace instructions, installed references and task inputs. Optional read recovery follows policy only; report first failure and dependent/independent work. Return missing required inputs without inventing authority/interpretation. Full fields follow [handoff](handoff.md#instruction-sources-bounded-read-recovery-visual-evidence-and-resumption).
 
 [ARC role policy: contract begin]
 Generated from lib/policy/role-policy.json; do not edit this managed section manually.
-- [git.specialists-deny] Specialist roles MUST NOT change Git state: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal, during normal implementation or recovery. An explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection remains allowed within the assigned scope.
-- [role.scouter-read-only] Research assigned static sources and report findings, evidence and limits. Do not edit files, install, execute checks, prepare execution targets, inspect live operational state, change external state or decide design, verification, review or acceptance.
-- [role.planner-draft-only] Return design/spec/plan drafts with dependencies, criteria, hold conditions and verification needs in the response. MUST NOT save documents, implement, run checks, prepare targets, request user approval or decide acceptance. Stop formal target-dependent drafting if actual prepared target evidence is missing; route decisions to Orchestrator.
-- [role.implementer-implementation] Edit only assigned, approved files and run focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds. Include the exact approved visual source, version, approval and access state, criterion IDs, required properties and comparison method, and actual-output identity, revision and comparison basis in Implementer and fresh QA handoffs. Record each visual result as pass, mismatch or unverified with accessible evidence and limits. Implementer self-report does not replace fresh QA and its actual comparison. A missing output-to-revision link is unverified; record a visible difference separately as mismatch, without inferring current branch UI status. Hold the affected visual claim for Orchestrator if source/output is missing, evidence is inaccessible or an interpretation is unapproved; do not silently substitute or redesign.
-- [role.qa-verification] Run approved checks and report commands, observations, reproduction, evidence and limits. Create only essential temporary data/logs/reports in the brief-authorized location and lifetime. Do not edit product source, tests, fixtures or configuration to pass checks, deploy or accept work. Persistent product-state checks require explicit scope and cleanup ownership. Return failures for Implementer correction and required QA recheck. Include the exact approved visual source, version, approval and access state, criterion IDs, required properties and comparison method, and actual-output identity, revision and comparison basis in Implementer and fresh QA handoffs. Record each visual result as pass, mismatch or unverified with accessible evidence and limits. Implementer self-report does not replace fresh QA and its actual comparison. A missing output-to-revision link is unverified; record a visible difference separately as mismatch, without inferring current branch UI status. Hold the affected visual claim for Orchestrator if source/output is missing, evidence is inaccessible or an interpretation is unapproved; do not silently substitute or redesign.
-- [role.reviewer-independent] Independently inspect the assigned final changes and evidence and report actionable findings and limits. Remain read-only. MUST NOT execute QA tests, edit files, perform Git mutations or decide 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.
+- [git.specialists-deny] Specialists must not change Git state during implementation or recovery: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal. Explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection within the assigned scope remains allowed.
+- [role.scouter-read-only] Research assigned static sources and report findings, evidence and limits. Do not edit, install, execute checks, prepare targets, inspect live operational state or change external state. Do not decide design, verification, review or acceptance.
+- [role.planner-draft-only] Return design/spec/plan drafts with dependencies, criteria, holds and verification needs in the response. During initial drafting and revisions, report progress only to Orchestrator: briefly state the stage, feedback being applied, actual blocker or next step, without draft prose or excerpts. Return the complete draft and self-review for review and correction. Raw responses may appear in app/tool surfaces; prompt policy cannot hide them. Do not save documents, implement, run checks, prepare targets, request user approval or decide acceptance. Stop formal target-dependent drafting when actual prepared-target evidence is missing. Route decisions to Orchestrator.
+- [role.implementer-implementation] Edit only assigned, approved files and run focused checks under the existing TDD contract. Report changed files, RED/GREEN or approved exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git mutations remain forbidden after successful implementation. Implementer and fresh QA handoffs include the exact approved visual source, version, approval and access state; criterion IDs, required properties and comparison method; and actual-output identity, revision and comparison basis. Record pass, mismatch or unverified with accessible evidence and limits. Implementer self-report does not replace fresh QA and its actual comparison. A missing output-to-revision link is unverified; record a visible difference separately as mismatch without inferring current branch UI state. Missing source/output, inaccessible evidence or unapproved interpretation holds the affected visual claim for Orchestrator. Do not silently substitute or redesign.
+- [role.qa-verification] Run approved checks and report commands, observations, reproduction, evidence and limits. Create only essential temporary data/logs/reports within brief-authorized locations and lifetimes. Do not edit product source, tests, fixtures or configuration to pass checks, deploy or accept work. Persistent product-state checks need explicit scope and cleanup ownership. Return failures for Implementer correction and required QA recheck. Implementer and fresh QA handoffs include the exact approved visual source, version, approval and access state; criterion IDs, required properties and comparison method; and actual-output identity, revision and comparison basis. Record pass, mismatch or unverified with accessible evidence and limits. Implementer self-report does not replace fresh QA and its actual comparison. A missing output-to-revision link is unverified; record a visible difference separately as mismatch without inferring current branch UI state. Missing source/output, inaccessible evidence or unapproved interpretation holds the affected visual claim for Orchestrator. Do not silently substitute or redesign.
+- [role.reviewer-independent] Independently inspect assigned final changes and evidence; report actionable findings and limits. Remain read-only. Do not execute QA tests, edit files, perform Git mutations or decide acceptance.
+- [platform.claude] Existing per-role tool allowlists reduce available tools; Bash and role contracts are not a filesystem sandbox. ARC supplies no native observer hook or Bash Git guard; Git restrictions remain prompt-level role contracts.
 [ARC role policy: contract end]

package/claude/skill/references/git-recovery.md

@@ -1,47 +1,29 @@
+<a id="preserve-state-after-failure"></a>
 # Preserve state after failure
 
-Read on branch collision, Git preparation failure, partial completion, Git metadata write denial, or handoff record write denial.
+Read on branch collision, Git preparation failure/partial completion, metadata or handoff-record write denial. Use [handoff-prep](handoff-prep.md) for branch selection and [handoff](handoff.md) for full restart gates.
 
-On an actual failed Git/tool command, partial completion, unexpected branch/HEAD, missing assigned path,
-or conflicting edit, stop dependent work. Inspect and record the actual absolute path, branch or detached HEAD, HEAD,
-index, worktree/untracked files, ownership, and completed steps. Report the precise blocker and needed resolution to
-Orchestrator. Do not retry, fall back, or repeat completed mutations automatically.
+On actual Git/tool failure, partial completion, unexpected branch/HEAD, missing path or conflicting edit, stop dependent work. Record absolute path, branch or detached HEAD, HEAD, index, working-tree/untracked files, ownership and completed steps. Return the precise blocker/resolution to Orchestrator. Never automatically retry, fall back or repeat completed mutations.
 
-MUST NOT automatically stash, reset, clean, unstage, discard, amend, delete branches/worktrees, remove locks,
-change permissions to bypass a blocker, or bypass sandbox restrictions. Preserve all unrelated work and recovery
-artifacts. Orchestrator obtains any needed human decision, resolves preparation within authorization,
-then revalidates affected gates and issues a precise delta restart brief. An explicit user selection is required where a
-choice is needed; silence, planning approval and refusal of another option do not count.
+Apply Preservation rule: preserve unrelated work/recovery artifacts. No automatic stash/reset/clean/unstage/discard/amend, branch/worktree deletion, lock removal, permission changes or sandbox bypass. Orchestrator obtains needed human decisions, resolves within authority, revalidates gates and supplies a delta restart brief. Explicit choice is required where applicable; silence, planning approval and refusal of another option do not count.
 
-A profile reapplication failure should restore all previously replaced profile bytes and modes.
-If rollback itself fails, preserve recovery files and report their paths; do not claim a clean state or remove manual
-recovery material.
+<a id="branch-collision-and-invalid-names"></a>
+## Branch collisions and invalid names
 
-## Branch collision and invalid names
-
-For an invalid name, branch creation/switch failure, lookup error, or unexpected current branch, inspect and record the
-error and actual Git state, then stop Implementer handoff. A branch created without a successful switch is partial completion:
-report it, never delete it automatically, and do not treat preparation as complete.
-Do not fall back to another branch or checkout. A new collision suffix requires fresh user approval of the candidate
-(handoff-prep). Existing staged/unstaged/untracked changes stay preserved; if they block a switch or ownership is
-unclear, stop until Orchestrator resolves it.
+Invalid names, creation/switch failures, lookup errors or unexpected branches require recorded errors/state and stopped handoff. Branch creation without switching is partial completion; report it without automatic deletion or success claims. No branch/checkout fallback. New collision suffixes need approval. Preserve staged/unstaged/untracked changes; blocked switching or unclear ownership waits for Orchestrator.
 
+<a id="git-metadata-write-denial"></a>
 ## Git metadata write denial
 
-If authorized staging, commit, branch creation, or switch is denied writing `.git/index.lock` or other Git metadata,
-block handoff and inspect read-only the exact command, workspace, error, failed path, Git directory, branch, HEAD,
-index, partial completion, lock existence, related processes, and OS permissions/ACLs, sandbox restrictions,
-and concurrent Git activity (Orchestrator performs read-only inspection of related processes and ACLs itself or assigns
-it to QA; Scouter, Planner, and Reviewer cannot run commands); record supported causes and remaining uncertainty.
-Lock-creation denial alone does not prove a stale lock. Do not delete locks, change permissions/ownership,
-bypass the sandbox, or move workspaces. If the denial is a permission-system prompt for an already authorized operation,
-request only the permission system's approval for that exact single Git command and workspace, never broad Git access.
-Before retrying recheck branch, HEAD, index, and partial completion; do not repeat completed work.
-After success verify the result and revalidate the whole handoff gate. Denied approval keeps handoff blocked;
-report the actual state.
+1. Denial of authorized stage/commit/branch creation/switch at `.git/index.lock` or other metadata blocks handoff.
+2. Inspect exact command/workspace/error/failed path, actual Git directory/branch/HEAD/index/partial completion read-only. Inspect lock existence, observable processes, sandbox limits, OS permissions/ACLs and concurrent Git activity. Record supported causes/uncertainty. Lock-creation denial alone proves no stale lock.
+3. Do not remove locks, `chmod`/`chown`, bypass sandbox or move workspaces. With evidence of permission-system denial of an already authorized operation, request only the supported minimum approval for that exact single command/workspace, never broad Git access.
+4. Before authorized retry, recheck branch/HEAD/index/partial completion without repeating completed work. After success verify operation/final state and the entire handoff gate.
+5. Denied approval or unresolved OS/ACL issues keep handoff blocked; report actual state/cause. A finalized message avoids unnecessary amend but cannot repair write access. Only authorized successful writes plus verified results prove recovery.
 
+<a id="handoff-record-write-denial"></a>
 ## Handoff record write denial
 
-If writing the canonical handoff record is denied or unavailable, stop that write, report the path and error to
-Orchestrator, and do not change permissions or bypass the sandbox. Use the inline-record fallback in
-[handoff.md](handoff.md).
+If canonical-record writing is denied/unavailable, stop it and report path/error. Never change permissions or bypass sandbox. Use [handoff](handoff.md)'s inline fallback.
+
+Orchestrator inspects related processes/ACLs read-only itself or assigns QA; Scouter/Planner/Reviewer cannot execute commands. Failed profile reapplication must restore replaced bytes/modes. If rollback fails, preserve recovery files/paths; never claim clean state or remove recovery material.