@yunhozz/arc 0.2.0 → 0.2.2

package/codex/skill/references/coordination.md

@@ -1,6 +1,6 @@
 # Role assignment and coordination
 
-Orchestrator reads this before the first specialist creation or assignment and related coordination decisions. Also read [limits](limits.md) and installed `../limits.toml` before first creation. Missing, inaccessible or conflicting references stop dependent work; report the exact paths.
+Orchestrator reads this before first creating or assigning a specialist and making related coordination decisions. Also read [limits](limits.md) and installed `../limits.toml` before first creation. Missing, inaccessible or conflicting references stop dependent work; report the exact paths.
 
 ## Ownership
 
@@ -9,11 +9,10 @@ Orchestrator reads this before the first specialist creation or assignment and r
   (save, route, obtain approval; never author), acceptance, verification, and completion.
 - Scouter: read-only material research/analysis and assigned static code/document/data/log exploration. Reports
   evidence, assumptions, unresolved questions, impact, next actions, and workspace/path issues to Orchestrator.
-  Does not edit files or author standalone document files, or decide design/plans, verification, review, or completion.
+  Does not edit files, author standalone documents, or decide design/plans, verification, review, or completion.
 - Planner: returns design/spec/plan drafts.
 - Implementer: edits assigned, approved implementation/configuration/test-code files and assigned dependent docs.
-  Orchestrator does not edit
-  them directly except under the Orchestrator direct path for small tasks.
+  Orchestrator does not edit them directly except under the Orchestrator direct path for small tasks.
 - QA: verifies without edits.
 - Reviewer: independently reviews the final full change.
 - All five roles report directly to Orchestrator at depth 2: Scouter, Planner, Implementer, QA, and Reviewer.
@@ -21,12 +20,12 @@ Orchestrator reads this before the first specialist creation or assignment and r
   Depth-2 roles cannot create agents or delegate tasks to another role. Reviewer remains independent.
 - Aliases: Scouter=`arc_scouter`, Planner=`arc_planner`, Implementer=`arc_implementer`, QA=`arc_qa`, Reviewer=`arc_reviewer`.
 - Across the full tree, obey configured limits for simultaneous subagents, including Scouter; there are no reserved slots.
-  Before first creation, read `references/limits.md` and installed `limits.toml`; maintain its cumulative ledger and reservations.
+  Before first creating a subagent, read `references/limits.md` and installed `limits.toml`; maintain its cumulative ledger and reservations.
   Parallelize independent tasks only; dependent handoffs are sequential and editing scopes cannot overlap.
 - After each read-only role returns (Scouter, Planner, Reviewer), Orchestrator checks `git status` against a pre-spawn
   snapshot for unexpected changes; on any change Orchestrator stops and reports under the Preservation rule.
   Limit: concurrent Implementer edits and ignored or out-of-repo paths are not attributable/detectable.
-  Their read-only status rests on prompt-level guards, not sandbox enforcement.
+  Their read-only status relies on prompt-level guards, not sandbox enforcement.
 
 
 ## Instruction and execution adapter
@@ -56,11 +55,9 @@ Missing/damaged local files stop dependent work: report exact paths to Orchestra
 ARC approval, ownership, TDD exceptions and executor adapters still apply.
 
 Orchestrator integrates role results, routes decisions and required approvals, and owns development acceptance
-and completion. Orchestrator coordinates dependent implementation tasks sequentially and
-starts a fresh Implementer for each top-level task (Role gate); reuse the current Implementer only for corrections, rework,
+and completion. Orchestrator runs dependent implementation tasks sequentially and starts a fresh Implementer for each top-level task (Role gate); reuse the current Implementer only for corrections, rework,
 or rechecks of the same task while the approved scope, workspace, ownership, and relevant assignment context remain valid;
-default to the current Implementer for same-task QA corrections. A QA finding within the current task does not itself create
-a new task. Before sending corrections or rework to a reused Implementer, Orchestrator rechecks workspace, branch/HEAD and change state against the brief.
+default to the current Implementer for same-task QA corrections. A QA finding within the current task does not itself create a new task. Before sending corrections or rework to a reused Implementer, Orchestrator rechecks workspace, branch/HEAD and change state against the brief.
 Replace or restart a role only when its context is invalid or unavailable, or the task boundary changes, subject to the
 amendment exception below. A fresh Implementer for the next task is a restart under handoff (choice reuse and restart brief rules are in handoff).
 After an approved plan or acceptance-criteria amendment, start a fresh Implementer for
@@ -71,18 +68,13 @@ follow [Risk-scaled execution](verification.md#risk-scaled-execution).
 ## Token discipline and handoffs
 
 - Only Orchestrator calls agents or assigns specialist tasks. Every `spawn_agent` call must explicitly set a descriptive
-  lowercase snake_case `task_name` in the form
-  `<role>_<short_task>` (for example `planner_scope_review` or `qa_installer_checks`). Do not use arbitrary or random
-  names. `task_name` identifies the run; `agent_type` and its configured profile determine the role and model.
+  lowercase snake_case `task_name` in the form `<role>_<short_task>` (for example `planner_scope_review` or `qa_installer_checks`). Do not use arbitrary or random names. `task_name` identifies the run; `agent_type` and its configured profile determine the role and model.
 
-- Keep one shared brief with fixed field order: Goal; Criteria (IDs); Exact scope/ownership (absolute workspace,
+- Keep one shared brief in this fixed field order: Goal; Criteria (IDs); Exact scope/ownership (absolute workspace,
   branch or detached HEAD and HEAD, handoff record path, when one exists, files);
   Constraints/decisions; Evidence (paths/lines, commands, artifact links); Prior findings; Exact next objective (one
-  bounded objective); Return format (conclusion, evidence locations, unresolved points, next step). On follow-ups
-  send only changed fields and mark the rest `unchanged` (relative to a brief the recipient received);
-  restart briefs follow handoff; a fresh specialist gets every other field in full. Send only the
-  self-contained subset needed by the next role and links to accessible artifacts; omit full history, repeated
-  instructions, and raw logs. No findings may be brief; requested deliverables such as complete plan drafts remain
+  bounded objective); Return format (conclusion, evidence locations, unresolved points, next step). On follow-ups send only changed fields and mark the rest `unchanged` (relative to a brief the recipient received);
+  restart briefs follow handoff; a fresh specialist gets every other field in full. Send only the self-contained subset the next role needs and links to accessible artifacts; omit full history, repeated instructions, and raw logs. No findings may be brief; requested deliverables such as complete plan drafts remain
   complete. Cite paths/lines/pages/commands/links instead of logs; investigate gaps only.
 - Every specialist spawn sets `fork_turns="none"`; full-history forks are not allowed. Supply that brief.
   Reuse an existing specialist for related follow-up with only changed facts/objective when its context
@@ -90,28 +82,18 @@ follow [Risk-scaled execution](verification.md#risk-scaled-execution).
 - `request_user_input` questions use only `title` and `options` fields, never `question`.
 - In Implementer briefs, cite the plan/spec path with the task section's line range and include only the needed excerpts,
   acceptance criteria, and constraints; do not ask Implementer to read whole plans or specs.
-- Before formal Planner drafting, complete the stage brief using
-  [planning](planning.md#planner-drafting-preparation-and-consolidated-feedback): original requirements/criteria IDs,
-  approved and open decisions, actual target/ownership, preceding approved versions and document paths, current behavior
-  and connected policy/source/generated/runtime/installer/documentation surfaces, depth, dependencies, checks, holds and
-  exact stage deliverable. Preserve the shared brief field order. Review completeness and conflicts together; send one
-  consolidated feedback request with changed fields and `unchanged` for the rest. Preserve separate sequential design,
-  spec and plan approvals; no fixed call cap, incomplete draft acceptance or extra calls for resolved questions.
-- Before optional calls, name the unresolved question and expected artifact. Skip calls whose questions are resolved
-  by available evidence or direct inspection.
+- Follow [Planner drafting preparation and consolidated feedback](planning.md#planner-drafting-preparation-and-consolidated-feedback).
+  Complete the initial brief and whole-draft checklist before sending consolidated corrections. Gate further calls
+  on documented changes or criterion progress; hold repetition without progress.
+- Before optional calls, name the unresolved question and expected artifact. Skip calls for questions resolved by available evidence or direct inspection.
 - Wait for a specialist with `wait_agent` using the maximum supported timeout, repeating only until it completes; a
   timeout is not a reason to poll or check status in between. Do not poll with `list_agents`, `sleep`, or repeated short
   waits; use `list_agents` only to resolve an unknown agent name or state. Send each specialist one complete brief per
   objective and batch related corrections or follow-ups into one message. Do not poll long-running commands with
   repeated `sleep` or short status checks; use a single blocking wait with the tool's longest yield.
 - Read only the needed ranges of files and outputs (for example `rg -n`, `sed -n`, `head`/`tail`) and cap long command
-  output. Do not re-read files or outputs already in context unless they changed. A mandatory reference already read in
-  this context and unchanged need not be re-read, and this skill file, once read in this context and unchanged,
-  is not re-read on follow-up turns;
-  this does not shorten any triggered mandatory reference read.
-- When a plan completes or before starting another plan in a session with long history, Orchestrator records the
-  canonical
-  handoff state in the handoff record file and recommends that the user continue in a new session.
+  output. Do not re-read files or outputs already in context unless they changed. A mandatory reference already read in this context and unchanged need not be re-read, and this skill file, once read in this context and unchanged, is not re-read on follow-up turns; this does not shorten any triggered mandatory reference read.
+- When a plan completes or before starting another plan in a session with long history, Orchestrator records the canonical handoff state in the handoff record file and recommends that the user continue in a new session.
 - Before handoff, post one short update with role/objective/expected output; after return, combine findings and next
   stage concisely. Do not expose hidden reasoning or raw prompts.
 
@@ -119,20 +101,23 @@ follow [Risk-scaled execution](verification.md#risk-scaled-execution).
 ## Models
 
 `models.toml` beside this skill is the source of truth for role model and reasoning-effort settings.
-Orchestrator uses the current conversation model. Use configured role settings without substitution or effort
-reduction; report unavailable settings.
+Orchestrator uses the current conversation model. Use configured role settings without substitution or effort reduction; report unavailable settings.
 Local declarations do not prove runtime provider support, account access, alias resolution, actual model or effort
 application, concurrency or depth enforcement.
 New sessions reload profiles; running agents retain their current settings and parent relationships. Configuration
 changes do not automatically reparent running agents or prove runtime parent behavior.
 
+## Instruction and Input Provenance
+
+Each role brief records the source, applicability, version or approval, and access state of user-provided instructions, discovered workspace instruction files, installed role references, and task inputs. Use only policy-authorized recovery for optional reads, and report the initial failure and dependent or independent work. If required material is missing, return it to the Orchestrator without inventing an interpretation or authority. Follow [handoff](handoff.md#instruction-sources-bounded-read-recovery-visual-evidence-and-resumption) for the full fields.
+
 [ARC role policy: contract begin]
 Generated from lib/policy/role-policy.json; do not edit this managed section manually.
-- [git.specialists-deny] Specialist roles MUST NOT change Git state: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal, during normal implementation or recovery. Even an explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection remains allowed within the assigned scope.
+- [git.specialists-deny] Specialist roles MUST NOT change Git state: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal, during normal implementation or recovery. An explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection remains allowed within the assigned scope.
 - [role.scouter-read-only] Research assigned static sources and report findings, evidence and limits. Do not edit files, install, execute checks, prepare execution targets, inspect live operational state, change external state or decide design, verification, review or acceptance.
-- [role.planner-draft-only] Return design/spec/plan drafts 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.implementer-implementation] Edit only assigned, approved files and run focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds.
-- [role.qa-verification] Run approved checks and report commands, observations, reproduction, evidence and limits. Create only essential temporary data/logs/reports in the brief-authorized location and lifetime. Do not edit product source, tests, fixtures or configuration to pass checks, deploy or accept work. Persistent product-state checks require explicit scope and cleanup ownership. Return failures for Implementer correction and required QA recheck.
+- [role.planner-draft-only] Return design/spec/plan drafts with dependencies, criteria, hold conditions and verification needs in the response. MUST NOT save documents, implement, run checks, prepare targets, request user approval or decide acceptance. Stop formal target-dependent drafting if actual prepared target evidence is missing; route decisions to Orchestrator.
+- [role.implementer-implementation] Edit only assigned, approved files and run focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds. Include the exact approved visual source, version, approval and access state, criterion IDs, required properties and comparison method, and actual-output identity, revision and comparison basis in Implementer and fresh QA handoffs. Record each visual result as pass, mismatch or unverified with accessible evidence and limits. Implementer self-report does not replace fresh QA and its actual comparison. A missing output-to-revision link is unverified; record a visible difference separately as mismatch, without inferring current branch UI status. Hold the affected visual claim for Orchestrator if source/output is missing, evidence is inaccessible or an interpretation is unapproved; do not silently substitute or redesign.
+- [role.qa-verification] Run approved checks and report commands, observations, reproduction, evidence and limits. Create only essential temporary data/logs/reports in the brief-authorized location and lifetime. Do not edit product source, tests, fixtures or configuration to pass checks, deploy or accept work. Persistent product-state checks require explicit scope and cleanup ownership. Return failures for Implementer correction and required QA recheck. Include the exact approved visual source, version, approval and access state, criterion IDs, required properties and comparison method, and actual-output identity, revision and comparison basis in Implementer and fresh QA handoffs. Record each visual result as pass, mismatch or unverified with accessible evidence and limits. Implementer self-report does not replace fresh QA and its actual comparison. A missing output-to-revision link is unverified; record a visible difference separately as mismatch, without inferring current branch UI status. Hold the affected visual claim for Orchestrator if source/output is missing, evidence is inaccessible or an interpretation is unapproved; do not silently substitute or redesign.
 - [role.reviewer-independent] Independently inspect the assigned final changes and evidence and report actionable findings and limits. Remain read-only. MUST NOT execute QA tests, edit files, perform Git mutations or decide acceptance.
 - [platform.codex] Role restrictions are prompt-level contracts, not a filesystem sandbox. No documented role-specific Git hook or generic per-agent tool allowlist is assumed. Existing shell capabilities are retained because static read access after shell reduction has not been verified; Implementer and QA need shell for approved checks.
 [ARC role policy: contract end]

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

@@ -31,7 +31,7 @@ Orchestrator, and do not change permissions or bypass the sandbox. Use the inlin
 
 ### Existing changes and failures
 
-A branch does not isolate uncommitted changes into a separate directory as a worktree does. Record how existing staged,
+Unlike a worktree, a branch does not isolate uncommitted changes in a separate directory. Record how existing staged,
 unstaged, and untracked changes relate to the task and their preservation and edit ownership in the brief. Apply the
 Preservation rule and do not automatically commit or delete changes to prepare the checkout. Only the
 approved docs commit on all three paths is an exception to that no-commit rule; preserve all unrelated dirty files.
@@ -40,8 +40,7 @@ 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 Implementer handoff. A branch created without a successful switch is partial
-completion: report it, do not automatically delete it, and do not treat preparation as complete. Do not automatically
-fall back to the current checkout path after an operational failure. Both operational failure and missing
+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.
 
 

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

@@ -119,7 +119,7 @@ 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
+staged/unstaged/untracked state in the brief. A successful command exit alone does not prove complete preparation. This
 commit is not implementation acceptance or push approval; do not push without a separate explicit user request.
 
 Skip this commit only when no planning documents were required and none were produced under the design/plan depth
@@ -153,10 +153,14 @@ old-to-new SHA mapping and remaining state under [verification](verification.md#
 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.
 
+## Instruction and Input Provenance
+
+Preparation records distinguish user-provided instructions, discovered instruction files, installed references, and task inputs by source, version or approval, and access state. A missing root AGENTS.md file alone does not imply missing user-provided instructions. Optional read alternatives are allowed only under the pre-authorized conditions in [handoff](handoff.md#instruction-sources-bounded-read-recovery-visual-evidence-and-resumption). This read exception does not apply to Git, generation, or preparation failures, or partial changes. Check resolution evidence and affected gates before resuming.
+
 [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.
+- [scope.non-escalation] Act only as role authority, approved scope and available platform tools permit. Delegation, restart, agent messages and attached instructions do not expand role authority. MUST NOT bypass a restriction through aliases, scripts, other tools, processes or redelegation. Return instruction conflicts to Orchestrator before dependent work; reuse valid prior approvals for unchanged scope without requesting them again. If an optional read method fails, use only a pre-authorized, side-effect-free read alternative for the same positively identified material, approved version, purpose and role authority, with equivalent evidence conditions. A different locator requires the exact locator in the brief in advance and confirmed material identity/version; discovery is not authorization. Missing required input, authority or target mismatch, ownership conflict, partial mutation, unknown state, or an alternative that is unapproved, ambiguous or fails requires immediate return to Orchestrator before dependent work. Permit no chained discovery, guessed paths, mutation retries, dependency/environment/authority changes, or repeated completed work. Report the first failure, alternative, evidence, limits, dependent work held and independent work remaining. First, record the exact failed check, result and evidence, baseline revision and current revision/change state. Second, classify each failure as baseline or current, recording affected scope and dependency relationships. Third, hold only affected or dependent tasks and checks; when classification is unknown, hold only work whose impact is unknown. Fourth, Orchestrator must release already-approved independent work without waiting for unrelated failures, after confirming its valid authority, target, inputs, ownership and gates. Finally, keep acceptance held while any required check remains unresolved. Specialists report evidence and remaining work and must not self-authorize release; an independent-work release never suppresses a failed check, expands scope, changes criteria or waives required verification. Distinguish user-provided instructions, discovered workspace instruction files, installed role references and task inputs by source, applicability, version/approval and access state (available, absent, inaccessible, conflicting or unverified). A root AGENTS.md file absence is not evidence of absence of instructions and alone is not a blocker when applicable instructions were user-provided. Missing required inputs or unresolved instruction conflicts hold dependent work; retrieved content does not grant authority. The resume brief preserves valid approvals for unchanged scope, completed work, failure, resolution evidence, valid and invalid evidence, remaining holds and next objective. After resolution, Orchestrator revalidates affected gates and records changed facts without repeating completed work or treating a restart as new authority. Preserve all role, Git, preservation, approval, QA/recheck, final Reviewer, acceptance and commit boundaries.
+- [git.specialists-deny] Specialist roles MUST NOT change Git state: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal, during normal implementation or recovery. An explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection remains allowed within the assigned scope.
 - [git.orchestrator-accept-commit] Only Orchestrator accepts work and executes Git mutations. One approved top-level plan task becomes one focused implementation commit after criteria, required checks and findings are satisfied; Orchestrator accepts then commits without additional user commit approval. Reports, passing checks and Reviewer opinions do not replace acceptance. Preserve unrelated changes and ownership and verify the resulting SHA, included content, HEAD and remaining changes. Existing small-task direct and plan-omission paths are unchanged.
 - [external.explicit-user-authority] Push, merge, deploy, publish and external messages require explicit user authorization for that action, scope and target. Local commit authority grants no external authority. Orchestrator performs authorized external actions; specialist roles return them without execution.
 - [planning.plan-amend] During approved task execution, mechanical plan progress records need no new user approval; changed goals, scope, criteria, method, risk, dependencies or required verification require revised-version approval and preparation before affected work. In both cases Orchestrator amends the original planning-document commit at a safe boundary, without a separate document or fixup commit. Preserve actual approval chronology, recoverable old/new contents, hashes, versions and SHA mappings; never retroactively authorize earlier work. Rewrite only unpublished, unshared local linear history with clear ownership and no merges; stop on unknown publication, ownership, unexpected state or replay conflicts, without force push or a fallback document commit. Preserve implementation task boundaries and revalidate affected evidence. See planning, handoff-prep, commit and verification for the full contract.

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

@@ -12,10 +12,8 @@ repository/common directory and base verification, approved branch verification,
 The normal new-document path drafts and saves directly in the verified target. Planned destination paths are not
 preparation evidence. Initial preparation does not authorize Implementer or a document commit.
 
-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.
+Only an explicit user choice of this third path authorizes preparation. Its selection target is the one verified under the Execution-target request gate in handoff-prep.md.
+The app determines the actual destination path; do not propose a sibling path or require a user-specified candidate.
 Use the verified source HEAD full SHA as the base; do not substitute remote HEAD or a default branch or fetch
 automatically.
 Recheck approved source state, base SHA, approved branch candidate/collision status, name and approved document scope
@@ -39,7 +37,7 @@ Create using only the app tool:
       ref: "<verified-source-head-full-sha>"
     })
 
-The name describes the work; it guarantees neither a path nor a branch. There are no destination path or branch arguments.
+The name describes the work without guaranteeing a path or branch. There are no destination path or branch arguments.
 Pass ref explicitly as the full SHA; do not omit it or rely on a remote default. If an operationId is returned,
 use mcp__codex_app__get_worktree_creation_status until completed. Preparing/creating/registering progress is not
 success.
@@ -64,8 +62,7 @@ If the app initially returns the approved branch, verify it and its base rather
 Unexpected branch or mismatched HEAD means stop. Verify final approved branch and HEAD before formal drafting, saving, document transfer,
 the batch docs commit, final Git verification and Implementer handoff.
 
-The tool 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
+The tool does not copy uncommitted changes. These transfer rules apply only to legacy or restart cases with existing approved documents (including an explicitly selected target change), excluding the normal new-document path. For untracked approved documents, source HEAD and index paths must be
 absent and source working-tree bytes must match the latest approved version. For tracked approved documents, source
 index blob and mode must equal source HEAD, while source working-tree bytes must match the latest approved version.
 Approved working-tree revisions may differ from HEAD/index; do not repair or verify them by staging source documents.
@@ -82,8 +79,7 @@ Verify existing approved commits by SHA, message, paths and approved content val
 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
+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

package/codex/skill/references/handoff.md

@@ -5,12 +5,21 @@ in the brief under the Implementer profile and reads this file only for sections
 (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).
 
+## Instruction Sources, Bounded Read Recovery, Visual Evidence, and Resumption
+
+Keep the existing brief field order and record provenance and status within each field. Distinguish four sources: user-provided instructions, discovered workspace instruction files, installed role references, and task inputs. Record each source, applicability, version or approval, and access state. A missing root AGENTS.md file does not imply missing instructions; applicable user-provided instructions remain valid. Missing required skills, references, or approved inputs and conflicting instructions hold dependent work.
+
+An optional read alternative is allowed only when the brief specifies its exact locator, material identity, approved version, purpose, method, preconditions, equivalent evidence, and return conditions in advance. Any alternate locator must be explicit and verified as the same material and version. Only pre-authorized, side-effect-free reads are allowed. Do not chain searches, guess paths, retry mutations, or change the environment, dependencies, or permissions. Immediately return missing required inputs, permission/target/ownership mismatches, partial changes, unknown state, and unauthorized, ambiguous, or failed alternatives to the Orchestrator. Report the initial failure, any alternative used, observed evidence and limits, and the dependent and independent work placed on hold. Orchestrator checks scope and valid evidence before deciding whether independent work may resume; unresolved required check failures continue to block acceptance.
+
+A visual brief records the exact approved visual source, version, approval and access state, criterion IDs, required properties and comparison method, actual-output identity, revision, and comparison basis. An Implementer report is separate from a fresh QA comparison. Report each result as pass, mismatch, or unverified with evidence locations and limitations. Return new UI interpretations or unapproved substitutions for visual sources to the Orchestrator.
+
+The resume brief preserves valid approvals for unchanged scope, completed work, failures, resolution evidence, valid and invalid evidence, remaining holds, and the next objective. The Orchestrator records changed facts and revalidates affected gates using resolution evidence. Do not repeat completed work. Preserve role, Git, QA revalidation, final Reviewer, acceptance, and commit boundaries.
+
 ## Workspace handoff
 
 ### Checkout approval
 
-Before every Implementer 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,
+Before every Implementer 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.
 
@@ -34,7 +43,7 @@ choice-lifetime rules below, wait and do not start or restart Implementer.
 Orchestrator may start or restart Implementer 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 Implementer Spike probe, record its approved question, method/scope, acceptance criteria, and constraints.
+   For an Implementer 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
@@ -51,8 +60,7 @@ Orchestrator may start or restart Implementer only after all of these conditions
 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 Implementer early. Reverify affected evidence when approved content, execution target, branch,
+Any missing or failed condition blocks handoff. Orchestrator may continue read-only investigation and authorized preparation or recovery, but must not start Implementer early. Reverify affected evidence when approved content, execution target, branch,
 HEAD, or relevant state changes. Implementer's conflict reporting is in its profile; Orchestrator
 resolves preparation and passes the gate again before Implementer resumes.
 
@@ -89,8 +97,7 @@ 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 Implementer completion report
-alone is insufficient. Verify the linked record is current and capacity and file ownership permit assignment.
+checks, Orchestrator acceptance and verified focused commit or accepted no-change evidence. An Implementer 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).
@@ -120,8 +127,7 @@ choice unless it invalidates the old target. Do not fall back automatically; app
 
 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
+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
@@ -134,8 +140,7 @@ 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
+An inaccessible initial record, missing evidence, or unclear ownership blocks editing; prior conversation or inaccessible links cannot replace 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.
 
@@ -188,6 +193,8 @@ generalize it to behavior work.
 
 ## Orchestrator direct path for small tasks
 
+This path does not waive explicit execution-target choice: before the first edit, record the user's choice or verified valid reuse. Approval of the edit scope alone does not select the execution target.
+
 Orchestrator may make a task's edits directly, without Planner brainstorming or Implementer, 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.
@@ -233,10 +240,10 @@ An unsupported no-plan/omission path does not imply a policy violation or a requ
 
 [ARC role policy: contract begin]
 Generated from lib/policy/role-policy.json; do not edit this managed section manually.
-- [git.specialists-deny] Specialist roles MUST NOT change Git state: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal, during normal implementation or recovery. Even an explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection remains allowed within the assigned scope.
-- [role.implementer-implementation] Edit only assigned, approved files and run focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds.
-- [review.significant-no-plan] For significant/high-risk work without a plan: Implementer → 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 Implementer → 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.
+- [git.specialists-deny] Specialist roles MUST NOT change Git state: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal, during normal implementation or recovery. An explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection remains allowed within the assigned scope.
+- [role.implementer-implementation] Edit only assigned, approved files and run focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds. Include the exact approved visual source, version, approval and access state, criterion IDs, required properties and comparison method, and actual-output identity, revision and comparison basis in Implementer and fresh QA handoffs. Record each visual result as pass, mismatch or unverified with accessible evidence and limits. Implementer self-report does not replace fresh QA and its actual comparison. A missing output-to-revision link is unverified; record a visible difference separately as mismatch, without inferring current branch UI status. Hold the affected visual claim for Orchestrator if source/output is missing, evidence is inaccessible or an interpretation is unapproved; do not silently substitute or redesign.
+- [review.significant-no-plan] For significant/high-risk work without a plan: Implementer → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. MUST NOT omit Reviewer because no plan exists. This creates no new plan obligation.
+- [review.significant-plan] For significant/high-risk plan work: each task uses Implementer → fresh QA as required → Orchestrator acceptance and focused commit. Reviewer reviews the final full change once after all tasks are accepted and required QA is complete. 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 Implementer → 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; Implementer and QA need shell for approved checks.
 [ARC role policy: contract end]

package/codex/skill/references/limits.md

@@ -11,9 +11,8 @@ Freeze these settings for one ARC coordination session/tree; reinstalling affect
 
 Maintain a session ledger of instance IDs, parent IDs, pending reservations, creation outcomes,
 and active/completed state. The Orchestrator itself is excluded. All created descendants,
-including nested or non-ARC agents, count toward the total. A completed agent never refunds
-the cumulative budget. Follow-up/resume of the same instance does not increment total;
-a fresh instance, retry that creates a new instance, or replacement does increment it.
+including nested or non-ARC agents, count toward the total. Completed agents never refund the cumulative budget. Follow-up/resume of the same instance does not increment total;
+a fresh instance, retry creating a new instance, or replacement increments it.
 Waiting, blocked, running and idle resumable instances consume concurrency until their
 completion/termination is confirmed. Obey any lower actual runtime capacity, including
 native retention of completed instances; ARC counts do not prove that a native slot is free.
@@ -22,7 +21,7 @@ Before any parallel dispatch, reserve the entire proposed batch in the ledger:
 created + pending reservations + proposed <= max_total_subagents, and
 active + pending reservations + proposed <= max_concurrent_subagents and available runtime capacity.
 Record a reservation before each creation call. Confirmed creation converts it into a created,
-active ID. Release a reservation only when failure proves that no instance was created.
+active ID. Release a reservation only when failure proves no instance was created.
 An uncertain result retains its reservation and capacity until reconciled. MUST NOT retry blindly.
 Serialize work when a batch does not fit. There are no reserved role slots.