@yunhozz/arc 0.2.2 → 0.2.4

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/superpowers/brainstorming/SKILL.md` and `references/superpowers/writing-plans/SKILL.md`;
-Implementer reads `references/superpowers/test-driven-development/SKILL.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](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.

package/claude/skill/references/handoff-prep.md

@@ -1,122 +1,110 @@
+<a id="prepare-the-current-checkout"></a>
 # Prepare the current checkout
 
-Claude v1 supports the current checkout only; ARC-managed worktree execution is unsupported.
-Do not create or attach worktrees as a fallback. Report unsupported requests before dependent work.
+Claude v1 supports current checkout only, not ARC-managed worktree execution. Never create/attach worktrees as fallback; report unsupported requests before dependent work.
 
+<a id="execution-target-and-git-evidence-gates"></a>
 ## Execution-target and Git evidence gates
 
+<a id="execution-target-request-gate"></a>
 ### Execution-target request gate
 
-Before requesting the user's execution-target choice, Orchestrator verifies and records planned document scope,
-absolute paths and scope coverage, design/plan depth and valid omissions, dependencies and intended execution order.
-The request does not require completed documents or individual approvals; unfinished drafts alone do not block it.
-The set contains required artifacts, not a spec on every path. Resolve scope/dependency decisions needed to identify
-the target; do not require choice evidence before asking for that choice.
-For every supported execution-target option, before obtaining the user's choice, present to the user:
+Before requesting choice, verify/record planned document scope, absolute paths/coverage, design/plan depth/valid omissions, dependencies and order. Completed documents/individual approvals are not yet required; unfinished drafts alone do not block asking. Include required artifacts, not mandatory specs everywhere. Settle scope/dependencies needed to identify the target without requiring choice evidence before asking.
 
-- Planned document list, each document's scope and coverage, repository-relative expected paths, dependencies and order,
-  and pending writing and approval status.
-- Verified absolute workspace, intended repository, current branch or detached HEAD, base HEAD, any validated
-  new-branch candidate and collision status when offered, staged/unstaged/untracked changes, preservation and edit ownership.
+Present each supported option with:
 
-Obtain explicit choice under the Explicit choice rule before preparation.
-Claude v1 offers current checkout/current branch (or detached HEAD) or a task branch in that checkout only.
-Planning approval or silence does not select a branch. Before branch creation present its exact candidate and base.
-Preserve unrelated changes; never stash, reset or clean to prepare.
+- Planned documents, coverage, expected relative paths, dependencies/order and pending drafting/approval.
+- Verified absolute workspace/repository, branch or detached HEAD, base HEAD, validated offered branch candidate/collision, staged/unstaged/untracked state, preservation/ownership.
 
+Obtain explicit choice before preparation.
+
+Claude v1 offers current branch/detached HEAD or a task branch in that checkout. Planning approval/silence chooses neither. Present exact candidate/base before creation. Preserve unrelated work; no preparation stash/reset/clean.
+
+<a id="git-mutation-evidence-gate"></a>
 ### Git mutation evidence gate
 
-Before each preparation Git mutation—branch creation/switch, approved-document staging,
-or commit—read this reference and recheck explicit execution-target choice or verified valid reuse; absolute workspace
-and intended repository; current branch or detached HEAD and HEAD; staged/unstaged/untracked changes, preservation and
-edit ownership; and the exact command, target paths, and approved scope. Confirm no unresolved failure or partial
-completion. Record these facts before the action. Missing or mismatched evidence stops that mutation.
-Initial target preparation does not require the complete approved document set: verify planned scope and target inputs.
-For approved-document staging and commit, also verify the complete approved document set and individual approval
-evidence, approved versions, dependencies, and actual index. Read-only Git checks remain allowed.
-Do not infer execution authority from an external skill's early commit step.
-
-After branch creation/switch verify actual absolute path, branch, HEAD and preserved state before dependent drafting.
-After staging verify index paths and diff before commit; unrelated staged files block the mutation. Stop and inspect
-on failure or partial completion, record actual state and completed steps, and revalidate affected gates after resolution.
-
-Batch-commit all remaining approved planning documents together in one focused docs commit before the first Implementer
-handoff. Stage only those document paths and verify the staged content and scope.
-Verify the resulting SHA, subject, paths, branch, HEAD and remaining state. Already committed approved documents need no
-duplicate commit. Record the actual preparation order and deviations, then complete the handoff gate before the
-next Implementer start. User authorization persists for the unchanged approved target and scope; do not repeatedly ask for the
-same choice.
-
-## New task branch naming
-
-With explicit user approval of the exact candidate and base, create the branch in the current checkout (for example
-`git switch -c <branch>` from the approved base HEAD). Name it `<type>/<short-kebab-case-topic>`: a lowercase prefix for
-the task's main purpose and a short, specific lowercase kebab-case topic without spaces.
+Before every preparation mutation (branch creation/switch, approved-doc staging/commit), read this and record/recheck:
+
+1. Explicit choice or verified valid reuse.
+2. Absolute workspace/intended repository, actual branch or detached HEAD and HEAD.
+3. Staged/unstaged/untracked state, preservation and ownership.
+4. Exact command/paths/approved scope; no unresolved failure or partial completion.
+
+Missing/mismatched evidence blocks mutation. Initial preparation verifies planned scope/inputs without requiring complete approved documents. Document staging/commit also verifies the full set, individual approvals/versions/dependencies and actual index. Read-only Git remains allowed. External skills' early commits grant no authority.
+
+After branch/commit operations verify path/branch/HEAD/preservation/result before dependent action. After staging verify index paths/diff and finalized message. Unrelated staged paths block changes. Revalidate affected evidence after change/failure; never retroactively authorize pre-gate actions.
+
+<a id="new-task-branch"></a>
+<a id="new-task-branch-naming"></a>
+### New task branch naming
+
+Create the explicitly approved candidate from approved base in the current checkout, e.g. `git switch -c <branch>`. Use `<type>/<short-kebab-case-topic>`: lowercase main-purpose prefix and short specific lowercase topic without spaces. Mixed work uses its main purpose.
 
 | Prefix | Purpose |
 |---|---|
-| feat/ | Add a feature |
-| fix/ | Fix a bug |
-| refactor/ | Restructure preserving behavior |
-| docs/ | Change documentation |
-| test/ | Add or change tests |
-| build/ | Build, packaging, dependencies |
-| ci/ | CI configuration |
-| perf/ | Improve performance |
-| style/ | Formatting or style only |
-| chore/ | Operational policy, tools, maintenance |
-| revert/ | Revert a prior change |
-
-Validate the name and check collisions before creation. If the base name exists, never automatically substitute a
-suffix; present a new candidate for explicit approval and use it only after the user approves it.
-Never reuse, delete, or overwrite an existing branch. Distinguish a lookup error from a missing branch;
-a lookup error blocks handoff and goes to git-recovery. Recheck workspace, branch or detached HEAD, base HEAD,
-and candidate before execution. If the target changes or a new collision changes the candidate, present it and obtain
-new explicit approval before creating or switching; without it, block handoff. After success confirm the branch matches
-the candidate, HEAD matches the base, the path is unchanged, and existing changes are preserved.
-
-## Planning document commit
-
-Begin only when all applicable documents are written, individually approved, and the set is complete.
-Verify already committed approved documents by SHA, message, paths, and content and reuse them; batch all remaining
-approved documents into one focused docs commit, staging only those paths and verifying staged paths and diff.
-Finalize the English Conventional Commit message before the first commit; no temporary message then amend.
-Never amend, reset, or recommit past commits to merge them. Skip the commit only when no documents were required or
-produced, recording the depth rationale; uncommitted documents are not absent. Never include implementation files.
-After success verify SHA, message, paths, HEAD, branch, and remaining state; the commit is not push approval.
-
-## Execution-time plan amendment
-
-After the initial approved document batch, execution-time plan updates use
-[planning](planning.md#plan-updates-during-execution), including approved scope revisions. Do not batch these as another
-document commit. This exception does not combine historical document commits or rewrite implementation task contents.
-
-Before mutation, verify the original planning-document commit is an ancestor of HEAD and identify its current replacement.
-Verify unpublished, unshared local linear history with no merge commits; clear ownership and included plan paths; paused
-role writers and a safe boundary for unfinished changes; complete classification, approval and chronology records.
-Preserve unrelated staged, unstaged and untracked changes under the Preservation rule; unexpected dirty state blocks rewrite.
-Secure recoverable pre-rewrite HEAD, original commits and before/after plan contents before mutation.
-
-If the original commit is HEAD, amend the plan paths only; preserve other documents in that commit. With descendant task
-commits, amend the original and reapply descendants in original order preserving task boundaries and implementation contents.
-Create no separate document or intermediate fixup commit. Git changes remain Orchestrator-only.
-
-Unknown publication/sharing status, unclear ownership, merge history, unexpected HEAD/change state or replay conflicts
-require a stop of rewriting and affected dependent work. No automatic conflict resolution, force push or fallback separate
-document commit is permitted. Record actual path, branch/HEAD, index/files and completed steps; Orchestrator resolves the
-issue before resuming and revalidates affected gates. Verify new SHA/HEAD, plan version/content, descendant preservation,
-old-to-new SHA mapping and remaining state under [verification](verification.md#evidence-after-plan-history-rewrite).
-
-## Instruction and Input Provenance
-
-Preparation records distinguish user-provided instructions, discovered instruction files, installed references, and task inputs by source, version or approval, and access state. A missing root AGENTS.md file alone does not imply missing user-provided instructions. Optional read alternatives are allowed only under the pre-authorized conditions in [handoff](handoff.md#instruction-sources-bounded-read-recovery-visual-evidence-and-resumption). This read exception does not apply to Git, generation, or preparation failures, or partial changes. Check resolution evidence and affected gates before resuming.
+| feat/ | Feature |
+| fix/ | Bug fix |
+| refactor/ | Structure, preserving behavior |
+| docs/ | Documentation |
+| test/ | Tests |
+| build/ | Build/packaging/dependencies |
+| ci/ | CI |
+| perf/ | Performance |
+| style/ | Non-behavior formatting/style |
+| chore/ | Policy/tools/maintenance |
+| revert/ | Revert prior change |
+
+Validate name/collision before creation. Never add suffixes automatically; approve new candidates. Never reuse/delete/overwrite existing branches.  Distinguish lookup errors from absence.
+
+Immediately recheck workspace, branch/detached HEAD, base and candidate. Changed target/collision candidate requires fresh explicit approval before creation/switch; otherwise block handoff. Detached HEAD is allowed when resolved and approved. After success verify actual branch equals candidate, HEAD equals base, unchanged absolute checkout and preserved changes. Failures follow Stop and inspect, never automatic checkout/worktree fallback.
+
+<a id="current-checkout"></a>
+### Current checkout
+
+After explicit selection or valid reuse, verify absolute workspace, branch/detached HEAD, HEAD and existing changes/preservation/ownership. Record state/choice. Missing choice, uncertain state or unclear ownership blocks handoff.
+
+<a id="planning-document-commit"></a>
+### Planning document commit
+
+Begin after target preparation and all applicable documents are written/individually approved. Verify full set/evidence/versions before staging/commit. New branches require successful switch, actual branch, unchanged path/preservation. Current checkout requires selected branch/detached HEAD/path/changes.
+
+
+1. Verify already committed approvals by SHA, actual message/paths/content and selected-checkout validity; reuse without recommitting.
+2. Record remaining approved versions/paths. Finalize a specific English Conventional Commit message before the first commit.
+3. Batch all remaining approved documents into one focused docs commit. Staged paths/diff must match exactly; unrelated staging blocks commit. No implementation files.
+4. If all validly committed, verify only. Never duplicate/empty-commit/amend/reset/recommit merely to combine SHAs. Do not use temporary messages followed by routine `git commit --amend`; separate amend needs scope/current HEAD/publication checks.
+5. Failure/staged-content mismatch stops handoff. Inspect branch/HEAD/index/partial completion and resolve before resuming; never commit implementation instead.
+6. Verify SHA/message/paths/content, post-commit HEAD/branch and remaining state in the brief, including selected base and actual order/deviations. Command success alone proves no preparation. Docs commit is neither implementation acceptance nor push approval; no push without separate explicit request.
+
+Skip only when depth rules required no documents and none were created; record why. Uncommitted documents are not absent. This adds neither documents nor gate exceptions. Unchanged authorized target/scope needs no repeated choice.
+
+<a id="execution-time-plan-amendment"></a>
+### Execution-time plan amendment
+
+After initial document batching, use [planning](planning.md#plan-updates-during-execution), including scope revisions. Never batch another document commit or combine historical commits/rewrite implementation contents under this exception.
+
+1. Verify original planning commit ancestry/current replacement, unpublished/unshared local linear history, no merges, clear ownership/plan paths, paused writers/safe unfinished-work boundary and complete classification/approval/chronology. Unexpected dirty state blocks rewrite.
+2. Preserve recoverable old HEAD/commits and before/after plan contents, plus unrelated staged/unstaged/untracked work.
+3. If original commit is HEAD, amend only plan paths, preserving other documents. Otherwise amend original and replay descendants in order with task boundaries/implementation contents intact. No separate docs/intermediate fixup commit. Orchestrator alone mutates Git.
+4. Unknown publication/sharing/ownership, merges, unexpected HEAD/state or replay conflict stops rewrite/affected work. No automatic resolution, force push or fallback docs commit. Record actual path/branch/HEAD/index/files/completed steps.
+5. After resolution revalidate gates. Verify new SHA/HEAD, approved plan content/version, descendants, old→new mappings and remaining state under [verification](verification.md#evidence-after-plan-history-rewrite).
+
+<a id="recovery-prerequisite"></a>
+### Recovery prerequisite
+
+Read [git-recovery](git-recovery.md) before dependent collision/failure/partial-completion/metadata-denial recovery. Stop/preservation rules are mandatory.
+
+<a id="instruction-and-input-provenance"></a>
+## Instruction and input provenance
+
+Distinguish instruction/input sources, versions/approvals and access. Missing root AGENTS.md alone implies no missing user instructions. Optional reads follow only [handoff](handoff.md#instruction-sources-bounded-read-recovery-visual-evidence-and-resumption)'s pre-authorization. This exception never covers Git/generation/preparation failure or partial changes. Verify resolution evidence/gates before resume.
 
 [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.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.
-- [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.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.
+- [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]