@yunhozz/arc 0.2.2 → 0.2.4

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

@@ -1,168 +1,110 @@
+<a id="handoff-preparation-contract"></a>
 # Handoff preparation contract
 
-Orchestrator reads before an execution-target choice request and each preparation Git mutation (branch creation/switch,
-staging, commit). The new managed worktree option's selection target is listed in the Execution-target request gate.
-The [Implementer handoff gate](handoff.md#implementer-handoff-gate), handoff evidence and choice lifetime are in [handoff.md](handoff.md).
+Read before choice requests and preparation Git mutations. Full gates/evidence/lifetime follow [handoff](handoff.md#implementer-handoff-gate).
 
+<a id="workspace-handoff"></a>
 ## Workspace handoff
 
+<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:
-
-- 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.
-
-Obtain explicit choice under the Explicit choice rule before preparation.
-When offering the new managed worktree option, Orchestrator first verifies and then presents its selection target
-(source absolute path, intended repository and Git common directory, source branch or detached HEAD, verified full source HEAD SHA,
-approved branch candidate and collision status, descriptive name, planned document scope and any existing approved document transfer/commit scope). Verification
-validates the approved branch candidate and collision status under New task branch naming rules and checks source state
-(unrelated staged changes; existing approved document HEAD/index/working-tree state) before offering. The app chooses the actual
-destination path: do not ask the user for a destination path or propose one, and do not fetch or substitute a remote
-HEAD or default branch for the base. Read [handoff-worktree.md](handoff-worktree.md) only after the user
-explicitly selects that option and before its creation, branch work, or document transfer.
+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.
 
+Present each supported option with:
+
+- 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.
+
+Before offering managed worktrees, verify/present source absolute path/repository/common directory, source branch/detached HEAD/full SHA, approved candidate/collision, descriptive name, planned documents and existing approved transfer/commit scope. Validate naming/collision and source unrelated staging/approved document HEAD/index/working bytes. The app chooses the path; never ask/propose destinations or substitute/fetch remote/default base. Only after explicit selection read [handoff-worktree](handoff-worktree.md), before creation/branch/transfer.
+
+<a id="git-mutation-evidence-gate"></a>
 ### Git mutation evidence gate
 
-Before each preparation Git mutation—branch creation/switch, worktree creation, 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.
+Before every preparation mutation (branch creation/switch, worktree creation, approved-doc staging/commit), read this and record/recheck:
 
-Before committing, also verify staged paths/content and the final message under Planning document commit.
-After every branch or commit operation, verify actual path, branch, HEAD, preserved changes, and result before the
-next dependent action. After staging, verify the actual index paths and diff before commit. Apply the Preservation
-rule; unrelated staged files stop the mutation.
-Reverify affected evidence after changes or failures; do not retroactively approve an action taken before its gate.
+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.
 
-### New task branch
+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.
 
-With explicit user approval for the execution target, prepare the new task branch in the existing checkout.
-Choose a valid Git branch name in the form `<type>/<short-kebab-case-topic>`. Use a lowercase prefix for the task's
-main purpose and a short, specific lowercase kebab-case topic with no spaces. For mixed tasks, choose the main purpose.
+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.
 
-| Prefix | Purpose |
-|--------|---------|
-| feat/ | Add a feature |
-| fix/ | Fix a bug |
-| refactor/ | Improve code structure while preserving behavior |
-| docs/ | Change documentation |
-| test/ | Add or change tests |
-| build/ | Change build, packaging, or dependencies |
-| ci/ | Change CI configuration |
-| perf/ | Improve performance |
-| style/ | Change formatting or style without behavior changes |
-| chore/ | Change operational policy, tools, or maintenance |
-| revert/ | Revert a prior change |
-
-Validate the name and check for collisions before creation. If the base name exists, never automatically substitute a
-suffix; present a new candidate for explicit approval. Never reuse, delete, or overwrite an existing branch, except
-that reuse of an approved existing branch on the managed worktree path follows the conditions in
-[handoff-worktree.md](handoff-worktree.md) (Exception for this managed path).
-Distinguish a lookup error from a missing branch.
-Recheck the workspace, current branch or detached HEAD, base HEAD, and candidate before execution. If the approval
-target changes, present the new target and obtain explicit user approval. If the candidate changes because of a new
-collision, obtain approval for that candidate before creating or switching; without that approval, block handoff.
-Use the current checkout only after the user explicitly selects it for this handoff. A failure during creation remains
-an operational failure subject to Stop and inspect (SKILL.md) and Recovery prerequisite below.
-
-Create and switch to the approved new branch from the confirmed base HEAD in the current checkout, for example with
-`git switch -c <branch>`. Detached HEAD is acceptable when HEAD is resolved and included in the approval target.
-After success, confirm the actual current branch matches the approved candidate, HEAD matches the recorded base, the
-checkout absolute path is unchanged, and existing changes are preserved. Do not create a worktree or fall back to
-worktree provisioning on failure. Only explicit selection of New managed worktree and task branch permits worktree
-creation.
+<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/ | 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. Only the [managed-path exception](handoff-worktree.md) permits narrowly verified approved-branch reuse. 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
 
-Only after the user explicitly selects the current checkout for this handoff, or valid reuse is verified,
-confirm the absolute workspace, current branch or detached HEAD, HEAD, and existing changes with their preservation and
-edit ownership. Record this state and the choice evidence in the brief. Missing choice, unconfirmed state, or unclear
-ownership blocks handoff.
+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 only after target preparation and the complete applicable set is written and individually approved.
-Verify complete approved document set, approval evidence and versions before staging or commit.
-On the new task branch path, verify the successful switch, actual branch, unchanged checkout path, and preserved
-changes first. On the current checkout path, verify the selected branch or detached HEAD, path, and existing changes.
-On the new worktree path, verify the created app-managed worktree, current-chat attachment, identity/base, approved
-branch and direct target documents (or protected pre-existing/restart document transfer) before any target docs commit.
-At the target, commit only remaining approved documents once; do not automatically make a source document commit.
-Record the selected base SHA and post-commit HEAD.
-Orchestrator verifies each approved spec/plan already committed for this task by SHA, actual message, included paths,
-and content matching the approved version and validity in the selected checkout; reuse valid commits without recommitting
-them.
-
-For approved documents still uncommitted, Orchestrator records the approved versions and paths, finalizes the specific
-English
-Conventional Commit message before the first commit, and stages only those documents for one focused docs commit
-before handoff. Batch all remaining uncommitted approved documents together in that single commit. If all are
-validly committed, verify only; do not create duplicate or empty commits, or amend, reset, or recommit past commits
-merely to combine them into one SHA. Verify both staged paths and staged diff match exactly the approved
-documents; unrelated staged files stop the commit under the Preservation rule. Never include implementation files.
-MUST NOT commit a generic temporary message and routinely repair it with `git commit --amend`. A separately needed amend requires rechecking its approval scope, current HEAD, and publication state.
-
-If the docs commit fails or staged content differs, stop handoff and apply the Stop and inspect rule to the actual
-branch, HEAD, index, and partial completion. Resolve the issue before resuming; do not commit implementation instead.
-After success verify SHA, actual message, included paths/content, post-commit HEAD, final branch, and
-staged/unstaged/untracked state in the brief. A successful command exit alone does not prove complete preparation. This
-commit is not implementation acceptance or push approval; do not push without a separate explicit user request.
-
-Skip this commit only when no planning documents were required and none were produced under the design/plan depth
-rules; record that fact and the applicable depth rationale. Uncommitted documents cannot be treated as absent.
-This does not require new documents or bypass checkout choice or any other handoff-gate condition.
+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.
+For worktrees verify actual app management/current-chat attachment/identity/base/branch and directly written documents or protected legacy/restart transfers before target docs commits. Commit remaining approvals once at target; no automatic source docs commit.
 
-### Execution-time plan amendment
+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.
 
-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.
+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.
 
-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.
+<a id="execution-time-plan-amendment"></a>
+### Execution-time plan amendment
 
-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.
+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.
 
-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).
+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
 
-On branch collisions, Git preparation failures, partial completion, or metadata write denial, read
-[git-recovery.md](git-recovery.md) before dependent recovery. Its stop and preservation rules are mandatory.
+Read [git-recovery](git-recovery.md) before dependent collision/failure/partial-completion/metadata-denial recovery. Stop/preservation rules are mandatory.
 
-## Instruction and Input Provenance
+<a id="instruction-and-input-provenance"></a>
+## 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.
+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.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.
+- [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.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/handoff-worktree.md

@@ -1,35 +1,20 @@
+<a id="managed-worktree-handoff-contract"></a>
 # Managed worktree handoff contract
 
-Orchestrator reads after the user explicitly selects the new managed worktree option, before its creation,
-branch work or document transfer. Apply [handoff-prep.md](handoff-prep.md) and [handoff.md](handoff.md) gates as well.
+After explicit new-managed-worktree selection, Orchestrator reads this before creation, branch work or document transfer. Also apply [handoff-prep](handoff-prep.md) and [handoff](handoff.md).
 
+<a id="workspace-handoff"></a>
 ## Workspace handoff
 
+<a id="new-managed-worktree"></a>
 ### New managed worktree
 
-Before formal drafting and saving, complete actual creation, managed registration, current-chat attachment,
-repository/common directory and base verification, approved branch verification, and source preservation checks below.
-The normal new-document path drafts and saves directly in the verified target. Planned destination paths are not
-preparation evidence. Initial preparation does not authorize Implementer or a document commit.
+Before formal drafting/saving, verify actual creation, managed registration, current-chat attachment, repository/common directory/base, approved branch and source preservation below. Draft/save new documents directly in the verified target. Planned paths prove no preparation; initial preparation authorizes neither Implementer nor document commits.
 
-Only an explicit user choice of this third path authorizes preparation. Its selection target is the one verified under the Execution-target request gate in handoff-prep.md.
-The app determines the actual destination path; do not propose a sibling path or require a user-specified candidate.
-Use the verified source HEAD full SHA as the base; do not substitute remote HEAD or a default branch or fetch
-automatically.
-Recheck approved source state, base SHA, approved branch candidate/collision status, name and approved document scope
-after choice and immediately before the tool call. After selection and before creation, any changes require
-a fresh explicit choice for the updated inputs. This is the pre-creation candidate rule. After successful creation
-and verification, apply Choice lifetime and restart record in handoff.md.
-
-Before calling mcp__codex_app__create_worktree, validate the approved branch candidate and collision state with
-New task branch naming rules in handoff-prep.md. A collision requires a new explicit choice; never automatically
-substitute a suffix.
-Default is the prohibition on reusing an existing branch in handoff-prep.md; only this narrow exception applies.
-Exception for this managed path: an existing approved branch at the same base and not checked out in any worktree
-may be reused; verify both conditions before reuse. An unexpected branch, different base or lookup uncertainty means
-stop.
-
-Create using only the app tool:
+1. Only explicit selection of this third path authorizes preparation. Use the selection target verified under handoff-prep's request gate. The app chooses the actual path; do not propose siblings or require user-specified paths. Use verified full source HEAD SHA as base, never remote HEAD/default branch or automatic fetch.
+2. After choice and immediately before the call, recheck source state, base SHA, approved candidate/collision, name and document scope. Changed pre-creation inputs require fresh explicit choice. After successful creation/verification, handoff lifetime/restart rules apply.
+3. Before `mcp__codex_app__create_worktree`, validate candidate/collision under handoff-prep. Collisions require new explicit choice, never automatic suffixes. Existing-branch reuse is forbidden by default. Only this managed path permits an approved existing branch at the same base and not checked out in any worktree, after both checks. Unexpected branch, different base or uncertain lookup stops work.
+4. Use only the app tool:
 
     mcp__codex_app__create_worktree({
       allowAsync: true,
@@ -37,51 +22,32 @@ Create using only the app tool:
       ref: "<verified-source-head-full-sha>"
     })
 
-The name describes the work without guaranteeing a path or branch. There are no destination path or branch arguments.
-Pass ref explicitly as the full SHA; do not omit it or rely on a remote default. If an operationId is returned,
-use mcp__codex_app__get_worktree_creation_status until completed. Preparing/creating/registering progress is not
-success.
-For registration failure only, retry the returned workspace with mcp__codex_app__attach_worktree. Before completed
-managed registration, current-chat attachment and approved branch verification, perform no formal drafting, saving, document transfer, staging,
-commit or Implementer start. If tools are unavailable, reattachment fails or results mismatch, stop and record actual state.
-Do not fall back to raw Git worktree creation, automatically retry other name/ref/path/branch inputs,
-or perform automatic cleanup, delete, prune or archive. See git-recovery.md before dependent recovery.
+The descriptive name guarantees no path/branch. There are no destination-path/branch arguments. Pass full SHA `ref` explicitly; never omit or rely on remote defaults. For `operationId`, use `mcp__codex_app__get_worktree_creation_status` until completed. Preparing/creating/registering is not success.
+
+Only registration failure permits reattachment of the returned workspace with `mcp__codex_app__attach_worktree`. No formal drafting/saving/transfer/staging/commit/Implementer before completed registration, current-chat attachment and branch verification. Missing tools, failed reattachment or mismatched results stop with actual-state reporting. No raw Git worktree fallback, alternate name/ref/path/branch retries or automatic cleanup/deletion/prune/archive. Read git-recovery before dependent recovery.
+
+Verify creation in order:
+
+1. Verify returned absolute path and app-artifact management/current-chat attachment.
+2. Record initial branch or detached HEAD, approved candidate, final branch and target HEAD equal to approved ref.
+3. Verify linked registration, source/target common-directory identity, registered path and target dirty state. Verify source branch/HEAD/index/files preservation. Approved-target shared metadata additions are authorized. Linked `.git` may be a file; repository identity requires neither identical top-level path nor a `.git` directory.
+4. After registration/attachment/base checks, create/check out the approved branch: `git switch -c <approved-branch> <ref>` if detached, or `git switch <approved-branch>` under the existing-branch exception. No pointer moves, alternate branches, `--force` or `-B`. If the app already returned the approved branch, verify without repeating completed work.
+5. Unexpected branch/HEAD mismatch stops work. Verify final branch/HEAD before formal drafting, saving, transfer, batch docs commit, final Git checks and handoff.
 
-Verify the returned actual absolute worktree path and app-managed current-chat attachment using app artifacts.
-Record initial branch or detached HEAD, approved branch candidate, final branch, and target HEAD equal to approved ref.
-Verify linked-worktree registration and source/target Git common directory identity, registered path,
-target dirty state, and source branch, HEAD, index and files preservation; shared Git metadata additions for the approved target are
-authorized.
-Linked worktree .git may be a file; do not require the same top-level path or a .git directory for repository identity.
-Verify registration, attachment and base before creating/checking out the approved branch. If initially detached,
-use `git switch -c <approved-branch> <ref>`; if the existing approved branch has the same base and is not checked out
-in any worktree, use `git switch <approved-branch>` (the exception above to the default no-reuse rule in
-handoff-prep.md). Do not move a branch pointer, choose another branch or use --force
-or -B.
-If the app initially returns the approved branch, verify it and its base rather than repeating completed work.
-Unexpected branch or mismatched HEAD means stop. Verify final approved branch and HEAD before formal drafting, saving, document transfer,
-the batch docs commit, final Git verification and Implementer handoff.
+The tool copies no uncommitted changes. Transfer rules below apply only to existing approved documents in legacy/restart/explicit-target-change cases, not normal new documents.
 
-The tool does not copy uncommitted changes. These transfer rules apply only to legacy or restart cases with existing approved documents (including an explicitly selected target change), excluding the normal new-document path. For untracked approved documents, source HEAD and index paths must be
-absent and source working-tree bytes must match the latest approved version. For tracked approved documents, source
-index blob and mode must equal source HEAD, while source working-tree bytes must match the latest approved version.
-Approved working-tree revisions may differ from HEAD/index; do not repair or verify them by staging source documents.
-Any mismatch means stop. Unrelated staged changes, required uncommitted implementation/configuration/test changes,
-and unclear ownership block preparation. Clearly unrelated unstaged/untracked changes remain in source.
-Do not automatically stash, commit, reset, clean, or unstage; do not transfer dirty implementation files.
-For those existing approved documents, use Worktree document transfer before target docs preparation.
+- Untracked approved documents must be absent from source HEAD/index, with working-tree bytes matching latest approval.
+- Tracked documents require source index blob/mode equal to HEAD and working-tree bytes equal to latest approval. Approved working revisions may differ from HEAD/index. Do not stage source documents to repair or verify them.
+- Mismatches, unrelated staged changes, required uncommitted implementation/configuration/test changes or unclear ownership block preparation. Clearly unrelated unstaged/untracked changes stay in source.
+- Never automatically stash/commit/reset/clean/unstage or transfer dirty implementation. Transfer existing approved documents below before target document preparation.
 
+<a id="worktree-document-transfer"></a>
 ### Worktree document transfer
 
-Use only for existing approved documents in pre-existing-document or restart/target-change cases.
+Only for existing approved documents in legacy/pre-existing-document, restart, or explicit-target-change cases; not normal new documents:
 
-Verify existing approved commits by SHA, message, paths and approved content valid at base and target; reuse them.
-Copy only uncommitted approved spec/plan documents to the target at the same repository-relative path.
-Do not move, delete, or modify the source documents. If a destination resolves outside the worktree, including through
-an escaping symlink, stop. Before transfer verify target HEAD equals the selected source base SHA.
-Before replacing an existing destination, prove its clean base state with no staged/unstaged changes and index and working-tree bytes matching the base version; then replace with the approved version. A document absent from base must
-also be absent at the destination. For unexpected changes, do not overwrite; stop.
-For identical content, verify approved bytes before reuse. After transfer verify bytes match the approved version.
-The canonical record includes each document approval/version/evidence, source and target absolute paths and the common
-relative path plus content verification. Changed content or approval scope requires approval of the revised version.
-Transfer no other files. Failure or partial transfer blocks all dependent staging, commit and Implementer handoff.
+1. Verify existing approved commit SHA/message/paths/content and validity at base/target; reuse them.
+2. Copy only uncommitted approved spec/plan documents to the same relative paths. Never move/delete/modify source documents. Stop for destinations escaping the worktree, including symlinks. Target HEAD must equal selected source base SHA before transfer.
+3. Before replacing a destination, prove clean base state: no staged/unstaged changes, index/working bytes equal base. Documents absent from base must also be absent at destination. Never overwrite unexpected changes.
+4. Verify approved bytes before reusing identical content; verify approved bytes after transfer.
+5. Record approvals/versions/evidence, absolute source/target paths, common relative paths and content checks. Changed content/approval scope needs revised approval. Transfer nothing else. Failure/partial transfer blocks dependent staging, commits and Implementer handoff.