@yunhozz/arc 0.2.3 → 0.2.4

package/codex/skill/references/coordination.md

@@ -1,123 +1,95 @@
+<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
-  (save, route, obtain approval; never author), 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.
-- Aliases: 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.
-- After each read-only role returns (Scouter, Planner, Reviewer), Orchestrator checks `git status` against a pre-spawn
-  snapshot for unexpected changes; on any change Orchestrator stops and reports under the Preservation rule.
-  Limit: concurrent Implementer edits and ignored or out-of-repo paths are not attributable/detectable.
-  Their read-only status relies on prompt-level guards, not sandbox enforcement.
+| 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.
 
+Aliases: 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.
+
+After each read-only role return (Scouter/Planner/Reviewer), compare `git status` with the pre-spawn snapshot. Unexpected changes stop under Preservation rule. Concurrent Implementer edits and ignored/out-of-repository paths cannot be attributed/detected. Read-only is prompt policy, not sandbox enforcement.
+
+<a id="instruction-and-execution-adapter"></a>
 ## Instruction and execution adapter
 
-Native Codex profiles are TOML with the `model_reasoning_effort` field.
-The native `[agents].max_concurrent_threads_per_session` value is an integer, distinct from ARC's ledger limits.
-These 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.
-
-
-### 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.
-
-Orchestrator integrates role results, 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. Task-boundary gates
-follow [Risk-scaled execution](verification.md#risk-scaled-execution).
-
-
-## Token discipline and handoffs
-
-- Only Orchestrator calls agents or assigns specialist tasks. Every `spawn_agent` call must explicitly set a descriptive
-  lowercase snake_case `task_name` in the form `<role>_<short_task>` (for example `planner_scope_review` or `qa_installer_checks`). Do not use arbitrary or random names. `task_name` identifies the run; `agent_type` and its configured profile determine the role and model.
-
-- 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.
-- Every specialist spawn sets `fork_turns="none"`; full-history forks are not allowed. Supply that brief.
-  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.
-- `request_user_input` questions use only `title` and `options` fields, never `question`.
-- 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.
-- Wait for a specialist with `wait_agent` using the maximum supported timeout, repeating only until it completes; a
-  timeout is not a reason to poll or check status in between. Do not poll with `list_agents`, `sleep`, or repeated short
-  waits; use `list_agents` only to resolve an unknown agent name or state. Send each specialist one complete brief per
-  objective and batch related corrections or follow-ups into one message. Do not poll long-running commands with
-  repeated `sleep` or short status checks; use a single blocking wait with the tool's longest yield.
-- 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.
+Codex profiles are TOML with `model_reasoning_effort`. Native `[agents].max_concurrent_threads_per_session` is an integer separate from ARC ledger limits. Local declarations prove no runtime 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.
+
+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.
+
+
 
+<a id="local-superpowers-references"></a>
+### Local Superpowers references
 
+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 creates/assigns specialists. Every `spawn_agent` sets descriptive lowercase snake_case `task_name` as `<role>_<short_task>` (e.g. `planner_scope_review`, `qa_installer_checks`), never random/arbitrary. It identifies the run; `agent_type`/profile determine role/model.
+
+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.
+- Every spawn uses `fork_turns="none"` and the shared brief; full-history forks are forbidden. Reuse relevant valid context with deltas; start fresh for unrelated/bloated context. Implementer/QA freshness follows Role gate.
+- `request_user_input` uses `title`/`options`, never `question`.
+- 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.
+- Wait with maximum supported `wait_agent` timeout until completion; timeouts do not justify polling. Use `list_agents` only to resolve unknown names/state, never sleep/short-wait loops. Batch corrections in one complete brief per objective. Long commands use one wait at maximum yield.
+- 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
 
-`models.toml` beside this skill is the source of truth for role model and reasoning-effort settings.
-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.
+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.
+
+
 
-## 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.codex] Role restrictions are prompt-level contracts, not a filesystem sandbox. No documented role-specific Git hook or generic per-agent tool allowlist is assumed. Existing shell capabilities are retained because static read access after shell reduction has not been verified; Implementer and QA need shell for approved checks.
+- [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.codex] Role restrictions are prompt-level contracts, not a filesystem sandbox. ARC supplies no native observer hook or role-specific Git guard. Existing shell capabilities are retained because static read access after shell reduction has not been verified; Implementer and QA need shell for approved checks.
 [ARC role policy: contract end]

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

@@ -1,66 +1,44 @@
+<a id="git-recovery-contract"></a>
 # Git recovery contract
 
-Read on branch collision, Git preparation failure, partial completion, metadata write denial, or handoff record write denial.
-Use [handoff-prep.md](handoff-prep.md) for approved branch selection, [handoff-worktree.md](handoff-worktree.md) for the
-managed worktree path, and [handoff.md](handoff.md) for the complete restart gate.
+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.
 
-## Recovery cases
+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.
 
-### Git metadata write denial
+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.
 
-If authorized staging, committing, branch creation, or switching is denied while writing `.git/index.lock` or other
-Git metadata, Orchestrator blocks handoff and safely inspects the exact command, workspace, error, failed path,
-actual Git directory, branch, HEAD, index state, and partial completion. Read-only inspection includes lock existence and any
-observable related processes, sandbox restrictions, OS permissions/ACLs, and concurrent Git activity. Record supported
-causes and remaining uncertainty; denial of lock creation alone does not prove a stale lock.
+<a id="branch-collision-and-invalid-names"></a>
+## Branch collisions and invalid names
 
-Apply the Preservation rule: do not delete lock files, use `chmod` or `chown`, bypass the sandbox, or move to another
-workspace. If evidence confirms sandbox denial of an already authorized operation, request through the permission system only (not
-a sandbox bypass) the tool-supported minimum escalation for only the exact single Git command and workspace, never
-broad Git access. Before retrying, recheck branch, HEAD, index, and partial completion; do not repeat work already
-completed. After success verify the commit or branch result and final state, then reevaluate the entire handoff gate.
-Denied escalation or unresolved OS permission/ACL problems keep handoff blocked; report the reason and actual state to Orchestrator/user.
-Choosing the final message in advance prevents unnecessary amend but does not repair required Git write access; only successful
-authorized writes and verified results establish recovery.
+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.
 
-### Handoff record write denial
+<a id="git-metadata-write-denial"></a>
+## Git metadata 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).
+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. Only when evidence confirms that the sandbox denied an already authorized operation, request through the permission system only the supported minimum escalation for that exact single Git command and 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.
 
-### Existing changes and failures
+<a id="handoff-record-write-denial"></a>
+## Handoff record write denial
 
-Unlike a worktree, a branch does not isolate uncommitted changes in a separate directory. Record how existing staged,
-unstaged, and untracked changes relate to the task and their preservation and edit ownership in the brief. Apply the
-Preservation rule and do not automatically commit or delete changes to prepare the checkout. Only the
-approved docs commit on all three paths is an exception to that no-commit rule; preserve all unrelated dirty files.
-If existing changes prevent switching or ownership is unclear, stop handoff until Orchestrator resolves the state and
-scope.
+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.
 
-For an invalid name, branch creation or switching 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, do not automatically delete it, and do not treat preparation as complete. Do not automatically fall back to the current checkout path after an operational failure. Both operational failure and missing
-execution-target choice block handoff. Orchestrator resolves the problem and rechecks preparation before handoff.
+<a id="recovery-cases"></a>
+## Recovery cases
 
+<a id="existing-changes-and-failures"></a>
+### Existing changes and failures
 
+A branch does not isolate uncommitted changes in another directory. Record task relationship/preservation/ownership in the brief. Never automatically commit/delete changes to prepare. Approved docs commits on the three paths are the sole exception; preserve unrelated dirty files. Switching blocks or unclear ownership hold handoff until resolution. Both operational failure and missing target choice block handoff.
+
+<a id="worktree-failures-and-partial-completion"></a>
 ### Worktree failures and partial completion
 
-Worktree creation, registration, attachment, identity/base verification, checkout, document transfer, staging,
-or commit failure means stop dependent work and Implementer handoff. Partial completion includes branch-only creation, partial
-path creation, registration/actual-path mismatch, wrong base or branch, and partial document transfer. Record source and
-target exact command, error, branch, HEAD, Git common directory, registration, index and files, including target dirty
-state and source preservation. Before any authorized retry, inspect actual state and completed work under the Stop and
-inspect rule; do not repeat completed actions.
-Do not automatically fallback, retry another path/branch, delete paths, prune registrations with `git worktree prune`,
-or use `--force` or `-B`; apply the Preservation rule.
-Normal worktree preparation after explicit managed-worktree selection is permitted under handoff; moving to an arbitrary
-workspace during recovery remains prohibited. Resolve preparation and revalidate the full gate; a new explicit choice
-follows Choice lifetime and restart record in handoff.md. No automatic cleanup/archive is authorized.
-
-For managed worktree failures record tool inputs, operationId, result/error, returned actual path, app-managed
-registration and current-chat attachment, initial/final branch, base/ref SHA, source/target HEAD/index/files and
-ownership.
-The completion, attach-retry and no-fallback limits of New managed worktree in handoff-worktree.md apply; after an
-attach retry check completion and current-chat attachment again; if it still fails or results cannot be verified, stop
-and report actual state. A directory alone does not prove app management.
+[Managed-worktree](handoff-worktree.md) creation/registration/attachment/identity/base/checkout/transfer/stage/commit failures stop dependent work/handoff. Branch-only or partial-path creation, registration/path mismatch, wrong base/branch and partial transfer count as partial completion.
+
+Record source/target commands/errors/branch/HEAD/common directory/registration/index/files, target dirty state and source preservation. Include tool inputs/operationId/results/returned path, app management/current-chat attachment, initial/final branch, base/ref SHA and ownership. Inspect actual state/completed work before authorized retry.
+
+No automatic alternate path/branch, deletion, `git worktree prune`, `--force`/`-B`, cleanup or archive. Normal preparation after explicit managed selection is allowed; arbitrary recovery workspace moves are not. Resolve and revalidate the full gate; renewed choice follows handoff lifetime rules. Preserve completion/attach-retry/no-fallback limits. Recheck completion/current-chat attachment after attach retry; failure or unverifiable results stop with actual-state reporting. Directory existence does not prove app management.