@yunhozz/arc 0.0.0-stage → 0.1.0

package/codex/skill/references/commit.md

@@ -0,0 +1,100 @@
+# Commit contract
+
+Orchestrator reads before accepting an approved top-level plan task and creating its focused commit, and before resuming
+a task whose commit result is unclear.
+
+## Automatic commit after plan-task acceptance
+
+One approved top-level task is the unit of one focused implementation commit. Orchestrator verifies the task's
+acceptance
+criteria, currently required checks (Reviewer timing: SKILL.md Risk-scaled execution), and findings,
+accepts the task by its own judgment, then immediately
+creates its focused local Git commit without additional user commit approval.
+After Orchestrator accepts a task, the next action is the required Git state/scope checks, staging, and focused commit.
+Do not commit before task acceptance or defer the task commit until the plan ends.
+Only Orchestrator accepts the task and executes its focused commit; Coder completion does not replace acceptance.
+Substeps and checkboxes are progress records, not separate commit units. Checkbox completion, Coder reports, and
+passing checks alone do not establish task acceptance: connect criteria's conditions and expected results to actual
+evidence. Existing plan-skip paths have no new plan obligation; their commits follow applicable guidance and user
+requests.
+
+Before committing, Orchestrator verifies the approved plan version, task ID and accepted scope, actual absolute
+workspace,
+repository, branch or detached HEAD, HEAD, staged/unstaged/untracked state and edit ownership. Verify staged paths and
+content match only that task, and verify the finalized commit message. If the same file contains other tasks or user
+changes, prove safe separation before committing. Unrelated staged changes stop the commit under the Preservation
+rule. After committing, verify SHA, actual message, included
+paths and content, post-commit HEAD, actual branch and remaining staged/unstaged/untracked state. Command exit success
+alone does not establish completion. In the accessible canonical record link plan path/version, task ID, acceptance
+evidence and Orchestrator judgment, required checks and findings, commit results and state, hold/no-change/reuse
+reasons,
+and remaining final plan verification.
+
+Hold the task commit for unmet or unresolved criteria, required checks that failed or were not run,
+unresolved findings or evidence gaps without disposition, scope expansion or revised-plan needs, ownership or staged
+scope/content mismatch, unexpected workspace, branch, HEAD or Git state, or Git failure/partial completion. Record the
+reason and required next action. Do not waive unmet criteria or required checks to commit. Explicit disposition follows
+existing policy and the Evidence verdict. After a Git failure inspect actual branch, HEAD, index,
+working tree and partial completion before retrying; if commit creation is unclear, stop rather than retry immediately.
+Orchestrator follows git-recovery and reverifies affected evidence after resolving the failure.
+
+For a no-change task, make no empty commit; record acceptance evidence and no change. On resume, verify the same task's
+existing commit SHA, content and validity, then reuse it; do not duplicate a successful task commit.
+For a missing record,
+inspect the actual result before any retry. Normal accepted task commits retain valid choice reuse under handoff, with
+fresh state and ownership checks. Task acceptance/commit is distinct from final plan acceptance; remaining final
+QA/Reviewer/integration checks still apply with the timing in verification.
+
+For final Reviewer findings on already committed plan work, Orchestrator defines a follow-up task and required
+planning/approvals. Coder leaves corrections uncommitted during rechecks. Orchestrator refreshes the latest committed
+state plus uncommitted diff and changed-file list in the Reviewer artifact/brief. Reuse an independent Reviewer or
+assign another independent Reviewer as needed. Repeat Coder → Reviewer without QA reassignment until findings are
+resolved; Orchestrator then accepts the corrections and creates one focused follow-up commit.
+Final QA findings retain Coder correction and QA recheck before a new focused commit.
+Do not automatically amend/reset or duplicate the original task commit. Scope expansion keeps existing new
+planning and approval obligations.
+
+This local commit authority does not authorize early planning-document commits: pre-Coder document approvals,
+explicit execution-target choice and batch preparation remain unchanged. Historical spec/plan records are not changed
+retroactively. Structural checks of this contract do not prove actual agent runtime compliance.
+Follow Conventional Commits with the message form
+`<type>(<scope>): <description>`. Use a concise, specific English description without a trailing period, a lowercase
+scope when useful, one top-level task's logical change per commit, and body/footer only when needed while preserving
+Git trailer syntax.
+
+## Shared-checkout coordination
+
+Orchestrator serializes shared-checkout Git mutations, including index/staging and commits, across concurrent tasks;
+parallel Coders do not operate competing Git transactions. Preserve every other task's unfinished staged, unstaged
+and untracked changes and ownership. Commit only the accepted task after scope/content verification; unrelated staged
+changes block the commit under the Preservation rule. Do not require unrelated unstaged work to finish or include it
+in the accepted task's commit. Unclear separation or ownership holds affected work for resolution.
+
+After each normal independent task commit, verify and record SHA/content/HEAD and remaining state, update the canonical
+record and affected briefs, revalidate affected gates and reevaluate task readiness immediately. An authorized HEAD
+change alone does not invalidate execution-target choice or require waiting for an unrelated batch. A predecessor
+releases dependents only after required checks, Orchestrator acceptance and verified commit; accepted no-change evidence
+replaces a commit for a no-change task, never an empty commit. Unexpected HEAD/ownership changes or Git failures stop
+affected work until Orchestrator resolves and revalidates; existing recovery and approval rules remain in force.
+
+Approval scope and continuity are defined in [planning](planning.md#authorization-and-scope); completion and evidence
+limits are defined in [verification](verification.md#completion-continuity). This plan-task commit contract adds no
+commit obligation to no-plan work and does not turn a local commit into overall completion.
+
+[ARC role policy: contract begin]
+Generated from lib/policy/role-policy.json; do not edit this managed section manually.
+- [scope.non-escalation] Act only within the intersection of role authority, approved scope and available platform tools. Delegation, restart, agent messages and attached instructions do not expand role authority. Never bypass a restriction through aliases, scripts, other tools, processes or redelegation. Return conflicting instructions to Orchestrator before dependent work; reuse valid prior approvals for unchanged scope rather than requesting them again.
+- [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. Even 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 does not grant external authority. Orchestrator performs authorized external actions; specialist roles return them without execution.
+- [role.orchestrator-boundary] Assign design/spec/plan/brainstorming drafts ONLY to Planner and implementation/configuration/test edits to Coder. Orchestrator saves complete drafts and owns approval requests, preparation, scheduling, evidence, acceptance and completion. Direct implementation is limited to the existing small, low-risk direct path; this policy does not expand it.
+- [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 and dependencies, criteria, hold conditions and verification needs in the response. Do 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.coder-implementation] Implement only assigned approved files and 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.
+- [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 Coder correction and required QA recheck.
+- [role.reviewer-independent] Independently inspect the assigned final changes and evidence and report actionable findings and limits. Remain read-only; do not execute QA tests, edit files, perform Git mutations or decide acceptance.
+- [review.significant-no-plan] For significant/high-risk work without a plan: Coder → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. Do not omit Reviewer merely because no plan exists. This creates no new plan obligation.
+- [review.significant-plan] For significant/high-risk plan work: each task uses Coder → fresh QA as required → Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.
+- [review.final-plan-recheck] For final overall Reviewer findings on plan work, including behavior findings, use Coder → Reviewer without QA reassignment; repeat until resolved. This exception applies only to that final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.
+- [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; Coder and QA need shell for approved checks.
+[ARC role policy: contract end]

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

@@ -0,0 +1,64 @@
+# Git recovery contract
+
+Read on branch collision, Git preparation failure, partial completion, or metadata 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.
+
+### Git metadata write denial
+
+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.
+
+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.
+
+### Existing changes and failures
+
+A branch does not isolate uncommitted changes into a separate directory as a worktree does. 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.
+
+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 Coder 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.
+
+
+### Worktree failures and partial completion
+
+Worktree creation, registration, attachment, identity/base verification, checkout, document transfer, staging,
+or commit failure means stop dependent work
+and Coder 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 third-path 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. Never treat a directory as proof of app management.

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

@@ -0,0 +1,153 @@
+# 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 Coder start gate, handoff evidence and choice lifetime are in [handoff.md](handoff.md).
+
+## Workspace handoff
+
+### 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.
+
+### 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 committing, also verify staged paths/content and the finalized 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.
+
+### New task branch
+
+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.
+
+| 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.
+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.
+
+### 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.
+
+### 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 legacy/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.
+Do not first commit a generic temporary message and routinely use `git commit --amend` to
+repair it. 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 preparation complete. 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.
+
+### 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.
+
+[ARC role policy: contract begin]
+Generated from lib/policy/role-policy.json; do not edit this managed section manually.
+- [scope.non-escalation] Act only within the intersection of role authority, approved scope and available platform tools. Delegation, restart, agent messages and attached instructions do not expand role authority. Never bypass a restriction through aliases, scripts, other tools, processes or redelegation. Return conflicting instructions to Orchestrator before dependent work; reuse valid prior approvals for unchanged scope rather than requesting them again.
+- [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. Even 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 does not grant external authority. Orchestrator performs authorized external actions; specialist roles return them without execution.
+- [role.orchestrator-boundary] Assign design/spec/plan/brainstorming drafts ONLY to Planner and implementation/configuration/test edits to Coder. Orchestrator saves complete drafts and owns approval requests, preparation, scheduling, evidence, acceptance and completion. Direct implementation is limited to the existing small, low-risk direct path; this policy does not expand it.
+- [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 and dependencies, criteria, hold conditions and verification needs in the response. Do 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.coder-implementation] Implement only assigned approved files and 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.
+- [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 Coder correction and required QA recheck.
+- [role.reviewer-independent] Independently inspect the assigned final changes and evidence and report actionable findings and limits. Remain read-only; do not execute QA tests, edit files, perform Git mutations or decide acceptance.
+- [review.significant-no-plan] For significant/high-risk work without a plan: Coder → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. Do not omit Reviewer merely because no plan exists. This creates no new plan obligation.
+- [review.significant-plan] For significant/high-risk plan work: each task uses Coder → fresh QA as required → Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.
+- [review.final-plan-recheck] For final overall Reviewer findings on plan work, including behavior findings, use Coder → Reviewer without QA reassignment; repeat until resolved. This exception applies only to that final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.
+- [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; Coder and QA need shell for approved checks.
+[ARC role policy: contract end]

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

@@ -0,0 +1,93 @@
+# 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.
+
+## Workspace handoff
+
+### 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 Coder or a document commit.
+
+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 path
+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.
+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:
+
+    mcp__codex_app__create_worktree({
+      allowAsync: true,
+      name: "<approved-descriptive-name>",
+      ref: "<verified-source-head-full-sha>"
+    })
+
+The name is descriptive and does not guarantee 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 Coder 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.
+
+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>`. 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 Coder handoff.
+
+The tool does not copy uncommitted changes. The following transfer rules apply only to legacy or restart cases
+with existing approved documents (including an explicitly selected target change), not 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.
+
+### Worktree document transfer
+
+Use only for existing approved documents in legacy or restart/target-change cases.
+
+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 Coder handoff.

package/codex/skill/references/handoff.md

@@ -0,0 +1,181 @@
+# Handoff contract
+
+Orchestrator reads before every Coder first start or restart preparation. Coder trusts the Orchestrator-verified facts
+in the brief under
+the Coder profile and reads this file only for sections the brief explicitly cites. First-start preparation
+(execution-target choice request, preparation Git mutations, planning-document commit) is in
+[handoff-prep.md](handoff-prep.md); the new managed worktree path is in [handoff-worktree.md](handoff-worktree.md).
+
+## Workspace handoff
+
+### Checkout approval
+
+Before every Coder first start and restart, Orchestrator confirms the supplied absolute workspace is accessible and
+belongs
+to the intended Git repository; record its actual absolute path, current branch or detached HEAD, HEAD, and staged,
+unstaged, and untracked changes. Stop if the workspace is inaccessible, is not the intended repository, or HEAD
+cannot be resolved. Do not initialize Git or switch to another repository automatically.
+
+Execution-target choice and actual preparation precede formal drafting and saving of required specs/plans.
+Initial design proposals may precede choice. Initial target preparation does not authorize Coder; all applicable
+approvals, complete documents, verified batch docs commits or valid absence, and final Git verification remain required.
+Record planned document scope/paths and actual preparation separately, followed by actual drafting/save/approval and
+commit results; preserve actual order and evidence gaps. Reuse a valid choice during document drafting and subsequent
+implementation while scope and target remain unchanged. Authorized HEAD and dirty-state changes alone do not invalidate
+choice; verify preservation and ownership. A changed scope or target requires fresh explicit choice before dependent
+drafting or preparation and does not require document completion. Never fall back automatically.
+
+After initial design approval, obtain and record an explicit user choice for the first start under the
+Explicit choice rule: use the current checkout, create a new task branch from the verified base HEAD in that same
+checkout, or create a new managed worktree and task branch (selection target under handoff-prep.md; contract in
+handoff-worktree.md after selection). Without an
+explicit execution-target choice or verified valid reuse under the choice-lifetime rules below, wait and do not start or
+restart Coder.
+
+### Coder handoff gate
+
+Orchestrator may start or restart Coder only after all of these conditions are verified:
+
+1. All applicable design/spec/plan approvals are recorded with approved artifact paths or valid depth-omission reasons.
+   For a Coder Spike probe, record its approved question, method/scope, acceptance criteria, and constraints.
+   The complete current-scope document list, approved versions, plan dependencies/order, and absence of unfinished
+   applicable documents are verified. Future implementation artifacts are not part of the probe scope or approved by it.
+2. The user explicitly selected the execution target initially, or that initial choice remains valid under the restart
+   rules below.
+3. The accessible absolute workspace is the intended Git repository.
+4. Actual branch or detached HEAD, HEAD, staged/unstaged/untracked state, preservation, and edit ownership are known.
+   Unrelated staged files are preserved and block handoff until Orchestrator resolves preparation.
+5. Approved planning-document commits are verified, or no documents were required or produced and the valid depth
+   rationale is recorded.
+6. After any commit or branch operation, final path, branch, HEAD, and change state are rechecked with no unresolved
+   failure or partial completion.
+7. The brief includes these preparation and final-verification facts and evidence.
+
+Before a Orchestrator direct edit, Orchestrator verifies the same conditions, with the approved scope record as the
+applicable approval,
+and records them in the brief.
+
+Any missing or failed condition blocks handoff. Orchestrator may continue read-only investigation and authorized
+preparation
+or recovery, but cannot start Coder early. Reverify affected evidence when approved content, execution target, branch,
+HEAD, or relevant state changes. Coder's conflict reporting is in its profile; Orchestrator
+resolves preparation and passes the gate again before Coder resumes.
+
+### Handoff evidence
+
+For the worktree path the canonical record maps source and target absolute paths, Git common directory, base SHA,
+selected branch, descriptive name, returned actual path, app-managed current-chat attachment, operationId/result,
+registration and preservation checks, and document transfer evidence. Do not automatically recreate, cleanup, or
+archive a worktree.
+
+Include the document-save gate evidence and results from planning.md, execution-target request readiness, and each
+preparation Git mutation's pre-action evidence and post-action result in the same canonical record.
+Record the actual absolute workspace, prior branch or detached HEAD and base HEAD, prior change state and preservation
+and edit scope, checkout approval result and evidence, selected execution path, final branch or detached HEAD,
+creation/switch result if attempted, and post-selection branch/path/HEAD/change checks in the brief. Include the docs
+commit SHA, actual message, included paths, approved-content verification or valid no-document depth rationale,
+final verification, and any failure/partial completion and recovery evidence, plus absolute approved artifact paths.
+Record the Complete planning-document set fields from planning.md, confirming no applicable document awaits
+writing/approval.
+Distinguish reused existing commits from the batch preparation commit, or record valid document absence.
+Record applicable approvals and the initial explicit execution-target choice or verified reuse for each first start or
+restart. Give all five
+roles (Coder, QA, Planner, Reviewer, Scouter) the same actual workspace and selected execution checkout or absolute
+worktree path, preparation
+evidence, and absolute artifact paths. Each
+role stays in the supplied workspace, reports missing, inaccessible, or conflicting paths and unexpected branch state to
+Orchestrator before dependent work, and does not create or switch workspaces or branches.
+
+### Task readiness at every assignment
+
+Before each first start or restart, if an approved plan exists, link its current dependency/readiness record
+(planning.md) in the canonical record and brief. Where plan omission is valid under existing rules, do not create a
+plan or map solely to satisfy this linking duty; record the applicable omission judgment and rationale in the
+canonical record and brief. Plan absence alone does not qualify for omission, and an unapproved required plan
+cannot bypass its approval gate.
+
+Before assignment, apply every readiness condition in
+[planning.md, Dependency and readiness record](planning.md#dependency-and-readiness-record), including predecessor
+checks, Orchestrator acceptance and verified focused commit or accepted no-change evidence. A Coder completion report
+alone is insufficient. Verify the linked record is current and capacity and file ownership permit assignment.
+Readiness supplements the full handoff gate and execution-target restrictions; it never waives them.
+For authorized HEAD or state changes, refresh this record and affected briefs, verify preservation and ownership,
+revalidate affected gates, and reassess readiness under planning.md and [commit.md](commit.md#shared-checkout-coordination).
+Unexpected HEAD or ownership changes stop affected work for Orchestrator resolution and revalidation.
+
+### Choice lifetime and restart record
+
+For the same approved scope, workspace, repository, and execution target, reuse the initial explicit choice only
+when its evidence is accessible and still valid. On every first start and restart, Orchestrator rechecks actual Git
+state
+against the current brief: absolute workspace and repository identity, branch or detached HEAD, HEAD,
+staged/unstaged/untracked changes, preservation and edit ownership, applicable approvals and artifacts,
+planning-document SHA/message/paths/content or valid no-document rationale, and Orchestrator's final state verification
+(Coder handoff gate items 1-7); a reused choice never waives any gate. A restart without document changes reuses
+verified valid planning-document commits without recommitting them and a still-valid initial choice, with fresh
+actual-state checks. Normal authorized HEAD and dirty-state changes, including accepted task commits, docs commits,
+implementation, and approved worktree document transfer, do not by themselves invalidate the choice; record them and
+verify that they match approved work, ownership, and the intended target. A worktree's creation base SHA remains
+evidence; target HEAD need not remain at that base; source preservation and unexpected-state checks still apply.
+Link the approved plan version, task ID and commit SHA/content/validity with current Git state and edit ownership in
+the restart brief under Orchestrator's full handoff gate. Verify/reuse successful task commits without duplication and
+keep planning-document preparation
+evidence distinct; task commits do not require repeating valid document preparation.
+
+If scope, workspace, repository, target, or approved branch candidate changes, obtain a fresh explicit choice before dependent drafting or preparation; reselection does not require document completion. If an invalidating failure means the old target cannot be trusted,
+obtain a fresh explicit choice after Orchestrator resolves preparation. State mismatches and unresolved failures block
+editing until Orchestrator resolves and revalidates the full gate; resolution does not automatically require a new
+choice
+unless it invalidates the old target. Do not fall back automatically; apply the Explicit choice rule.
+
+Keep one canonical initial handoff record accessible to each assigned role, containing the approved scope/version,
+repository/workspace identity, and the Handoff evidence fields above; do not create a separate storage service.
+Orchestrator writes it as a
+Markdown file at `<git-common-dir>/arc/handoff/<plan-or-task-slug>.md` (slug unique to the plan, the dated plan filename
+stem, or a spec/task slug when no plan exists; never overwrite another plan's record; resolve with
+`git rev-parse --path-format=absolute --git-common-dir`; outside the working tree and shared by linked worktrees; not a
+Git mutation, never staged or committed; contains no secrets), gives its absolute path in every brief, and restart
+briefs cite it. If
+the write is denied or unavailable, each Coder brief states why and includes the full record inline, with no delta;
+that inline record satisfies the accessible record requirement. Do not delete it automatically.
+
+Restart brief: supply only verified deltas and mark unchanged fields; `unchanged` means unchanged relative to the record
+file the fresh Coder reads, and every other brief field is in full. Include: initial record location,
+next objective and edit ownership, changed decisions,
+approvals, documents and scope (or explicit no-change confirmation), current Git state and differences, choice
+validity and reuse verification, refreshed commit/artifact checks, Orchestrator final verification, and remaining
+issues.
+An inaccessible initial record, missing evidence, or unclear ownership blocks editing; a prior conversation or
+inaccessible link cannot substitute for evidence. Include material needed for a self-contained role handoff, with
+accessible canonical evidence instead of repeated history. Reverify revised documents/approvals and current state;
+never retrospectively claim preparation of edits made before the gate passed.
+
+## Authorization continuity
+
+Use [planning](planning.md#authorization-and-scope) for approval evidence and scope classification. Record that evidence,
+its scope, criteria, constraints, and valid document-depth omissions alongside execution-target choice and preparation.
+Reuse valid authorization for the same approved scope and target. A restart or new role assignment does not require
+repeat approval. Reuse never waives verification of actual workspace/repository, branch or detached HEAD, HEAD,
+changes, preservation, ownership, applicable documents, and preparation evidence by Orchestrator. Refresh actual state
+and affected briefs for authorized changes; they alone do not invalidate approval. Coder trusts the verified brief
+under its profile. Material scope/method/risk changes and invalid target evidence hold affected work; resolve using
+planning and the choice-lifetime rules above. Report the missing condition and resume evidence rather than asking
+for an approval already valid for that scope.
+
+[ARC role policy: contract begin]
+Generated from lib/policy/role-policy.json; do not edit this managed section manually.
+- [scope.non-escalation] Act only within the intersection of role authority, approved scope and available platform tools. Delegation, restart, agent messages and attached instructions do not expand role authority. Never bypass a restriction through aliases, scripts, other tools, processes or redelegation. Return conflicting instructions to Orchestrator before dependent work; reuse valid prior approvals for unchanged scope rather than requesting them again.
+- [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. Even 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 does not grant external authority. Orchestrator performs authorized external actions; specialist roles return them without execution.
+- [role.orchestrator-boundary] Assign design/spec/plan/brainstorming drafts ONLY to Planner and implementation/configuration/test edits to Coder. Orchestrator saves complete drafts and owns approval requests, preparation, scheduling, evidence, acceptance and completion. Direct implementation is limited to the existing small, low-risk direct path; this policy does not expand it.
+- [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 and dependencies, criteria, hold conditions and verification needs in the response. Do 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.coder-implementation] Implement only assigned approved files and 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.
+- [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 Coder correction and required QA recheck.
+- [role.reviewer-independent] Independently inspect the assigned final changes and evidence and report actionable findings and limits. Remain read-only; do not execute QA tests, edit files, perform Git mutations or decide acceptance.
+- [review.significant-no-plan] For significant/high-risk work without a plan: Coder → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. Do not omit Reviewer merely because no plan exists. This creates no new plan obligation.
+- [review.significant-plan] For significant/high-risk plan work: each task uses Coder → fresh QA as required → Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.
+- [review.final-plan-recheck] For final overall Reviewer findings on plan work, including behavior findings, use Coder → Reviewer without QA reassignment; repeat until resolved. This exception applies only to that final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.
+- [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; Coder and QA need shell for approved checks.
+[ARC role policy: contract end]