@yunhozz/arc 0.1.3 → 0.1.5

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

@@ -1,30 +1,34 @@
 # Git recovery contract
 
-Read on branch collision, Git preparation failure, partial completion, or metadata write denial.
+Read on branch collision, Git preparation failure, partial completion, metadata write denial, or handoff record write denial.
 Use [handoff-prep.md](handoff-prep.md) for approved branch selection, [handoff-worktree.md](handoff-worktree.md) for the
 managed worktree path, and [handoff.md](handoff.md) for the complete restart gate.
 
+## Recovery cases
+
 ### 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
+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
+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
+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.
 
+### Handoff record write denial
+
+If writing the canonical handoff record is denied or unavailable, stop that write, report the path and error to
+Orchestrator, and do not change permissions or bypass the sandbox. Use the inline-record fallback in
+[handoff.md](handoff.md).
+
 ### Existing changes and failures
 
 A branch does not isolate uncommitted changes into a separate directory as a worktree does. Record how existing staged,
@@ -44,15 +48,14 @@ execution-target choice block handoff. Orchestrator resolves the problem and rec
 ### 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.
+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
+Normal worktree preparation after explicit managed-worktree selection is permitted under handoff; moving to an arbitrary
 workspace during recovery remains prohibited. Resolve preparation and revalidate the full gate; a new explicit choice
 follows Choice lifetime and restart record in handoff.md. No automatic cleanup/archive is authorized.
 

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

@@ -2,7 +2,7 @@
 
 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).
+The [Coder handoff gate](handoff.md#coder-handoff-gate), handoff evidence and choice lifetime are in [handoff.md](handoff.md).
 
 ## Workspace handoff
 
@@ -22,14 +22,12 @@ For every supported execution-target option, before obtaining the user's choice,
 
 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,
+(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
+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
@@ -71,7 +69,9 @@ main purpose and a short, specific lowercase kebab-case topic with no spaces. Fo
 | 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.
+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
@@ -89,9 +89,9 @@ 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.
+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
 
@@ -100,12 +100,11 @@ Verify complete approved document set, approval evidence and versions before sta
 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.
+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
+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
@@ -119,10 +118,9 @@ MUST NOT commit a generic temporary message and routinely repair it with `git co
 
 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.
+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.
@@ -139,14 +137,5 @@ Generated from lib/policy/role-policy.json; do not edit this managed section man
 - [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 grants no 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. MUST NOT save documents, implement, run checks, prepare targets, request user approval or decide acceptance. Stop formal target-dependent drafting if actual prepared target evidence is missing; route decisions to Orchestrator.
-- [role.coder-implementation] Edit only assigned, approved files and run focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds.
-- [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. MUST 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. MUST 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 at the 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

@@ -1,8 +1,7 @@
 # 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.
+branch work or document transfer. Apply [handoff-prep.md](handoff-prep.md) and [handoff.md](handoff.md) gates as well.
 
 ## Workspace handoff
 
@@ -27,6 +26,7 @@ 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.
@@ -47,19 +47,18 @@ For registration failure only, retry the returned workspace with mcp__codex_app_
 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.
+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
+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
+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,
@@ -77,16 +76,15 @@ For those existing approved documents, use Worktree document transfer before tar
 
 ### Worktree document transfer
 
-Use only for existing approved documents in legacy or restart/target-change cases.
+Use only for existing approved documents in pre-existing-document 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.
+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.

package/codex/skill/references/handoff.md

@@ -1,8 +1,7 @@
 # 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
+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).
 
@@ -11,8 +10,7 @@ the Coder profile and reads this file only for sections the brief explicitly cit
 ### 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,
+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.
 
@@ -28,9 +26,8 @@ drafting or preparation and does not require document completion. Never fall bac
 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.
+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
 
@@ -51,13 +48,11 @@ Orchestrator may start or restart Coder only after all of these conditions are v
    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.
+Before an Orchestrator direct edit, Orchestrator verifies the same conditions, with the approved scope record as the
+applicable approval, and records them in the brief.
 
 A 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,
+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.
 
@@ -79,12 +74,10 @@ Record the Complete planning-document set fields from planning.md, confirming no
 writing/approval.
 Distinguish reused 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.
+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
 
@@ -107,8 +100,7 @@ Unexpected HEAD or ownership changes stop affected work for Orchestrator resolut
 
 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,
+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
@@ -119,14 +111,12 @@ verify that they match approved work, ownership, and the intended target. A work
 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.
+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.
+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.
@@ -135,8 +125,7 @@ Markdown file at `<git-common-dir>/arc/handoff/<plan-or-task-slug>.md` (slug uni
 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;
+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
@@ -162,18 +151,76 @@ under its profile. Material scope/method/risk changes and invalid target evidenc
 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.
 
+Before any exception judgment, Orchestrator reads [Risk-scaled execution](verification.md#risk-scaled-execution) and [planning](planning.md) for the full risk and plan-depth conditions.
+
+## Common handoff gate
+
+Before every Coder first start/restart, Orchestrator passes the full gate:
+applicable approvals/artifacts or valid omissions, explicit execution-target choice
+or verified reuse, intended accessible repository/workspace, actual Git identity/state, preservation/ownership,
+verified document commits or valid absence, and no unresolved failure/partial completion.
+Missing evidence, mismatches, unclear ownership or unresolved preparation block handoff and require Orchestrator
+resolution and full revalidation. Handoff owns the evidence fields, canonical handoff record, restart brief, choice lifetime
+and reuse. Coder trusts the Orchestrator-verified brief and reports actual conflicts under its self-contained profile;
+never replace its local guards with a requirement to load Orchestrator procedures.
+Depth-2 roles use the supplied workspace and report path/state conflicts; they cannot create/switch workspaces or
+branches. The same conditions apply before an Orchestrator direct edit.
+For a selected worktree, handoff requires common directory, registration, app-managed current-chat attachment,
+approved branch, and source preservation; prepare only through the selected managed-worktree contract.
+
+
+## Coder TDD and constraints
+
+Before feature, bug-fix, or behavior edits, Coder follows local `test-driven-development` unless the explicit
+ARC exception applies; the Coder profile holds Coder's full TDD rules. TDD is waived only when every small,
+low-risk criterion (Risk-scaled execution) and every plan-skip criterion (Orchestrator direct path) holds.
+Before Coder starts,
+Orchestrator records the scope, why every criterion is met, acceptance criteria, and focused verification in the brief.
+An explicit user or task-specific TDD request overrides
+this waiver. For qualifying tasks only, this exception takes precedence over the generic trigger in the local reference;
+do not change that skill. Ordinary multi-step or significant/high-risk work is not eligible. The waiver skips only
+RED-GREEN steps; focused checks and risk-appropriate QA/Reviewer remain, and do not claim TDD was followed.
+If a constraint blocks a required TDD step, Orchestrator records the
+decision in the brief/plan and obtains any required human approval; internal approval is not a substitute.
+Non-behavior documentation/configuration uses only a specifically authorized exception recorded in the brief; do not
+generalize it to behavior work.
+
+
+## Orchestrator direct path for small tasks
+
+Orchestrator may make a task's edits directly, without Planner brainstorming or Coder, only when every small,
+low-risk criterion holds, every plan-skip criterion holds (one local change, no dependent stages, no cross-component shared state,
+lifecycle, or integration-order concerns, and one focused verification path), and no significant-risk trigger applies.
+Spike, architectural, ordinary-behavior, significant/high-risk, unclear-risk work, and edits overlapping files assigned
+to a running Coder are not eligible.
+
+Before editing, Orchestrator records a scope record (not a brainstorming design) with scope and files,
+why every criterion holds, acceptance criteria, and focused verification. Apply authorization in
+[planning](planning.md#authorization-and-scope): an existing sufficiently specific user request can approve
+that scope; no duplicate approval is needed. Otherwise present the scope record to the user and obtain explicit
+approval before editing. Silence, an ambiguous response, or approval of other work is not approval.
+Orchestrator then passes the Coder handoff gate in handoff,
+with the approved scope record as the applicable approval, before the first edit. Orchestrator edits only the approved files,
+preserves others' edits, makes surgical edits in the local style without unrelated refactoring or speculative additions,
+and does not install dependencies without authorization.
+
+Behavior edits follow Coder TDD and constraints; when TDD applies, Orchestrator follows local
+`test-driven-development`.
+After editing, Orchestrator records the changed files, runs the focused checks, connects each acceptance criterion to
+evidence, and preserves unverified scope. Orchestrator is not independent of its own edit; assign QA when the evidence is
+incomplete.
+After a failed focused check or a QA finding, Orchestrator routes the correction to Coder and obtains a recheck.
+
+If scope expands, risk becomes unclear, or a criterion stops holding, Orchestrator stops editing, records the changes
+already made, and reclassifies; further work follows the normal Planner/Coder flow with Coder owning subsequent edits. Do not
+automatically revert, reset, stash, or clean those changes. Like other plan-skip paths, there is no automatic task
+commit; commits follow applicable guidance and user requests.
+
+
 [ARC role policy: contract begin]
 Generated from lib/policy/role-policy.json; do not edit this managed section manually.
-- [scope.non-escalation] Act only where role authority, approved scope and available platform tools all 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 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 grants no 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. MUST NOT save documents, implement, run checks, prepare targets, request user approval or decide acceptance. Stop formal target-dependent drafting if actual prepared target evidence is missing; route decisions to Orchestrator.
 - [role.coder-implementation] Edit only assigned, approved files and run focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds.
-- [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. MUST 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. MUST 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 at the final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.

package/codex/skill/references/limits.md

@@ -30,7 +30,7 @@ Serialize work when a batch does not fit. There are no reserved role slots.
 
 Preserve the ledger through continuation, resume and context compaction; reconcile actual instance
 IDs before dispatch. Ledger loss must never reset counters to zero. If reconstruction is incomplete,
-hold creation and report the unknown budget; use a conservative bound only with sufficient evidence.
+hold creation and report the unknown budget; use a conservative upper bound only when the reconstructed records support it.
 Completion frees confirmed active capacity; it does not restore the total-created budget. Exhaustion holds new
 creation and requires reporting remaining work and budgets. It does not authorize skipping required
 QA or Reviewer, role freshness, approval, ownership, dependency or same-file edit gates.