@yunhozz/arc 0.1.9 → 0.2.0

package/codex/skill/references/handoff.md

@@ -1,7 +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
+Orchestrator reads before every Implementer first start or restart preparation. Implementer trusts the Orchestrator-verified facts
+in the brief under the Implementer 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).
 
@@ -9,13 +9,13 @@ in the brief under the Coder profile and reads this file only for sections the b
 
 ### Checkout approval
 
-Before every Coder first start and restart, Orchestrator confirms the supplied absolute workspace is accessible and
+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.
 
 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
+Initial design proposals may precede choice. Initial target preparation does not authorize Implementer; 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
@@ -27,14 +27,14 @@ After initial design approval, obtain and record an explicit user choice for 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.
+choice-lifetime rules below, wait and do not start or restart Implementer.
 
-### Coder handoff gate
+### Implementer handoff gate
 
-Orchestrator may start or restart Coder only after all of these conditions are verified:
+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 Coder Spike probe, record its approved question, method/scope, acceptance criteria, and constraints.
+   For a 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
@@ -52,9 +52,9 @@ Before an Orchestrator direct edit, Orchestrator verifies the same conditions, w
 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,
-HEAD, or relevant state changes. Coder's conflict reporting is in its profile; Orchestrator
-resolves preparation and passes the gate again before Coder resumes.
+preparation or recovery, but cannot 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.
 
 ### Handoff evidence
 
@@ -74,7 +74,7 @@ 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
+restart. Give all five roles (Implementer, 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.
@@ -89,7 +89,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 Coder completion report
+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.
 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,
@@ -103,7 +103,7 @@ when its evidence is accessible and still valid. On every first start and restar
 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
+(Implementer 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
@@ -125,11 +125,11 @@ 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 Implementer 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,
+file the fresh Implementer 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
@@ -146,7 +146,7 @@ its scope, criteria, constraints, and valid document-depth omissions alongside e
 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
+and affected briefs for authorized changes; they alone do not invalidate approval. Implementer 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.
@@ -155,13 +155,13 @@ Before any exception judgment, Orchestrator reads [Risk-scaled execution](verifi
 
 ## Common handoff gate
 
-Before every Coder first start/restart, Orchestrator passes the full gate:
+Before every Implementer 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;
+and reuse. Implementer 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.
@@ -169,12 +169,12 @@ For a selected worktree, handoff requires common directory, registration, app-ma
 approved branch, and source preservation; prepare only through the selected managed-worktree contract.
 
 
-## Coder TDD and constraints
+## Implementer 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,
+Before feature, bug-fix, or behavior edits, Implementer follows local `test-driven-development` unless the explicit
+ARC exception applies; the Implementer profile holds Implementer'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,
+Before Implementer 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;
@@ -188,41 +188,133 @@ 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,
+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.
 Spike, architectural, ordinary-behavior, significant/high-risk, unclear-risk work, and edits overlapping files assigned
-to a running Coder are not eligible.
+to a running Implementer 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,
+Orchestrator then passes the Implementer 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
+Behavior edits follow Implementer 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.
+After a failed focused check or a QA finding, Orchestrator routes the correction to Implementer 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
+already made, and reclassifies; further work follows the normal Planner/Implementer flow with Implementer 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.
 
 
+## Cooperative CLI verification handoff
+
+For the supported spec+plan path, the verification handoff includes the registered task contract, exact check descriptor,
+task/final scope, `status.changeFingerprints`, independent actor attestations, intent ID, result messageRef and verdict.
+An externally authorized role performs each check/review after `prepare`, and records the actual result through `result`.
+CLI records do not authenticate identities or prove actual agent policy compliance.
+
+When scope, documents or approvals change, inspect `affectedTaskIds` and the dependency chain, preserve earlier approval and
+result records, and hand off new approvals and contracts for affected tasks. Do not reuse an old passing check for a different fingerprint.
+Link failed findings to the assigned Implementer's resolution evidence and QA rechecks for that change version. Only final overall Reviewer
+findings use Implementer→Reviewer revalidation. Do not add Reviewer as a prerequisite for individual task acceptance or commits.
+Follow [verification.md](verification.md#verification-lifecycle-in-the-cooperative-cli) for detailed fields and hold conditions.
+An unsupported no-plan/omission path does not imply a policy violation or a requirement to write documents.
+
 [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.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.
-- [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.
+- [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.
+- [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]
+
+## Initial Implementer assignment through the cooperative CLI
+
+In approved plan mode, Orchestrator performs the following sequence. All mutation commands pass JSON through stdin with
+`node "$ARC_RUNTIME_ENTRY" <command> --cwd "$ARC_CHECKOUT" --workflow "$ARC_WORKFLOW_ID" --input -`.
+Resolve `ARC_RUNTIME_ENTRY` from the actual ARC skill directory selected by the installation resolver:
+`<target-home>/skills/arc/runtime/cli.mjs`. Use the loaded skill's location, including a custom target home;
+do not guess the default home or use a package, checkout or cache entry. Pass the resolved path, checkout and
+workflow ID as separate argv values when using a process API. In a shell, assign values safely and double-quote
+these variables; never interpolate paths into executable shell text or use `eval`.
+Query `status` without `--input`.
+
+The entry preserves the cooperative state path in the selected checkout's Git common directory. Installing or
+updating the entry does not migrate state or renew approvals. Runtime/hash, target, actor and revision checks still
+apply: runtime drift holds existing evidence; obtain the required current evidence and approval through the
+existing recovery procedure. A new workflow cannot retroactively validate earlier execution.
+
+1. Prepare the docs-only commit of the approved spec and plan, and verify the exact document set, objects and current files.
+   Perform `init`, approval `record` and `prepare` only after this commit verification, even when user approval preceded the document commit.
+2. After document commit verification, pass `mode: "plan"`, `actor: {id: "operator"}` and `selection: {messageRef, contentHash}` to `init` at the final target HEAD.
+3. Use `record` to persist the user approval attestation already confirmed. The input is
+   `{requestId, expectedRevision, actor, evidence: {kind: "approval", messageRef, data: {approvalVersion, documentVersion, documents}}}`.
+   `documents` contains exactly the spec and plan, each with `{kind, path, gitPath, contentHash, approvalRef, commit}`.
+   `contentHash` is `sha256:<hex>`, and `approvalRef` must match the approval `messageRef`.
+   On HEAD drift, record a fresh target observation and renewed approval instead of reconnecting an earlier intent.
+4. Pass `{requestId, expectedRevision, actor, operation: "assign-agent", taskId, arguments: {role: "implementer", paths, operations: ["edit"], documents, approvalRef, approvalVersion, documentVersion, correlation}}` to `prepare`.
+   Absolute `paths` must be inside the checkout. Confirm `allow`, `persisted: true` and the persisted intent.
+5. Invoke the native assignment with the task, scope and correlation from the persisted intent.
+6. Pass `{requestId, expectedRevision, actor, intentId, result: {status, messageRef, data: {correlation, taskId, agentId}}}` to `result`.
+   `intentId` is the prepare requestId. Distinguish success as `succeeded`, failure as `failed`, uncertain execution as `unknown` and a response mismatch as `mismatch`.
+   Success requires the returned agent ID. `unknown`/`mismatch` causes a hold; stop duplicate assignments and investigate the actual result.
+
+Approval and assignment results on this path are `operator-attested`. They do not authenticate native identities or verify platform events.
+The CLI cannot block direct calls outside it, and a new workflow cannot legitimize omitted past execution. Existing trusted adapter provenance requirements remain in force.
+
+
+## External operations and recovery in the cooperative CLI
+
+The three phases support state, documents and assignment; scope, verification, acceptance and focused commits; and external approval, results and audit recovery.
+Use `status.support` to inspect all nine areas and their limits. The supported mode is `plan` with spec+plan; no-plan and omission are unsupported. The CLI does not execute native/provider calls or push, merge, deploy or publish.
+User approvals and execution results confirmed by the operator are `operator-attested`, with `nativeVerified: false` and
+`remoteVerified: false`. Blocking direct calls outside the CLI and independent remote verification are not provided.
+
+Orchestrator records an explicit approval it has already confirmed through `record` with
+`evidence: {kind: "external-approval", messageRef, data: {operation, scope, descriptor}}`.
+`scope` is an array of unique absolute paths within the checkout. Local commit approval does not authorize external operations.
+Include the exact action, scope and target in the approval, and record every descriptor field below.
+
+| operation | descriptor fields |
+|---|---|
+| push | repository, destination, refspec, sourceOid, expectedRemoteOid |
+| merge | repository, changeRef, targetRef, expectedTargetOid |
+| deploy | service, project, environment, artifactId, destination |
+| publish | service, namespace, name, version, artifactHash, destination |
+
+Git OIDs are full 40/64-character lowercase hex values; artifactHash is `sha256:<64-hex>`. Without a remote observation,
+an OID is an expected value asserted by the user, not verified remote state. destination must be an identifier without secrets.
+Do not submit URL userinfo, query or fragment components, or authentication information such as passwords, tokens or credentials.
+The CLI rejects recognized credential inputs before persistence, but cannot determine whether every arbitrary string contains a secret.
+
+Pass `{requestId, expectedRevision, actor: {id, role: "orchestrator"}, operation,
+arguments: {approvalRef, scope, descriptor}}` to `prepare`. approvalRef matches the external approval messageRef.
+An intent is persisted only when the exact approval, scope/target versions and runtime version match and no effect is unresolved.
+After confirming `allow` and `persisted: true`, Orchestrator performs the external operation within its separately approved scope.
+This CLI does not expand that execution authority.
+
+`result`/`reconcile` accepts `{requestId, expectedRevision, actor, intentId,
+result: {status, messageRef, data: {operation, scope, descriptor}}}`. intentId is the prepare requestId.
+Target mismatches, unknown outcomes and stale results cause a hold while preserving earlier attestations. After an interruption,
+use `status` to inspect the intent, `state.requests`, `state.audit` and `state.results`, and investigate whether the effect occurred.
+Reconcile the investigation result against the same intent rather than preparing again or reusing the same approval to execute again.
+Cancellation additionally requires a `notExecutedEvidence: {messageRef}` attestation that the operation was not executed.
+The approval remains consumed after cancellation. Do not resolve version drift through automatic updates, migration or renewed permission.
+Report the cause of the hold to Orchestrator.
+
+Even succeeded results are operator attestations, not independent remote verification. `audit` retains the
+request→decision→intent→result→resolution linkage, but is a locally editable record rather than tamper-proof security evidence.
+Do not retry while the actual external outcome is uncertain.

package/codex/skill/references/planning.md

@@ -44,7 +44,7 @@ and records the actual absolute workspace/repository, branch or detached HEAD, H
 explicit choice and preparation evidence, and absolute document paths inside that target. Planner drafts for that
 verified workspace; Orchestrator saves directly in the selected target. Missing or mismatched evidence stops the
 affected drafting or save and is reported to Orchestrator. Planned scope and paths do not establish actual preparation.
-Initial target preparation does not authorize Coder; the complete handoff gate still applies.
+Initial target preparation does not authorize Implementer; the complete handoff gate still applies.
 
 
 ## Planner drafting preparation and consolidated feedback
@@ -66,6 +66,14 @@ Initial design, required spec approval, and formal plan drafting/approval remain
 Allow additional Planner calls for substantive omissions or user-approved scope/evidence changes. There is no fixed
 call cap; never accept an incomplete draft to minimize calls. Do not add call-count conditions to Planner profiles.
 
+The complete initial brief identifies original user requirements, criteria IDs, approved decisions and open decisions;
+current behavior and connected source, generated, runtime, installer and documentation surfaces; conflicting rules and
+resolution direction; exact current-stage deliverable and absolute output path. Keep the shared brief's fixed field order
+in [coordination](coordination.md). Link accessible evidence and needed ranges instead of full dialogue or raw logs.
+Consolidated feedback contains changed fields only and marks remaining fields `unchanged` relative to the received brief.
+Do not call Planner again for already resolved questions. Missing target preparation or required decisions holds formal
+drafting; initial design proposals may still precede target selection. Written-spec approval precedes dependent plan drafting.
+
 ## Design and planning
 
 `brainstorming` and `writing-plans` are instructions for existing roles, not extra agents. This ARC controls
@@ -92,12 +100,12 @@ approved obligations separately.
    (SKILL.md Role gate);
    the direct path uses only a scope record.
 2. Spike: apply Probe scope above; distinguish probe-only authorization from a sufficiently specified combined scope.
-   Bounded: approve a short design before Coder or an Orchestrator direct edit (Planner's design
-   before Coder; a direct edit uses only an approved scope record). Architectural: approve
+   Bounded: approve a short design before Implementer or an Orchestrator direct edit (Planner's design
+   before Implementer; a direct edit uses only an approved scope record). Architectural: approve
    design, then Planner returns complete spec draft and self-review findings; Orchestrator integrates, saves,
    self-reviews, and obtains written-spec approval
    before implementation planning. Planner is read-only and cannot request approval.
-3. After approved design/spec and before Coder, Orchestrator assesses plan depth separately from file count, LOC,
+3. After approved design/spec and before Implementer, Orchestrator assesses plan depth separately from file count, LOC,
    or bounded
    scope. Architectural work always uses local `writing-plans` and requires written plan approval, regardless of
    locality, risk, or size. For bounded work, skip planning only for one local change with no dependent stages,
@@ -109,8 +117,8 @@ approved obligations separately.
    returning its complete proportional draft, assumptions/open decisions, verification requirements, and self-review.
    Orchestrator integrates, saves to the user's path or `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`,
    self-reviews,
-   then obtains plan approval before Coder.
-5. Every Coder first start and restart requires all applicable design/spec/plan approvals and passing
+   then obtains plan approval before Implementer.
+5. Every Implementer first start and restart requires all applicable design/spec/plan approvals and passing
    the Common handoff gate in SKILL.md and handoff.md, with approved artifacts, brief, and relevant findings.
    Non-behavior
    configuration/documentation may skip inapplicable design/planning stages, but still requires the handoff gate.
@@ -141,12 +149,12 @@ These requirements apply to required plans; existing plan-omission paths gain no
 
 ### Dependency and readiness record
 
-After plan approval and before the first Coder assignment, Orchestrator records all top-level task IDs in the
+After plan approval and before the first Implementer assignment, Orchestrator records all top-level task IDs in the
 accessible canonical handoff record, linked to the approved plan version. For each task record explicit and implicit
 predecessors, required inputs, outputs and shared contracts, owned files, conflicting shared resources, required
 checks/QA path, ready/held status and reasons. Record the initial ready batch and capacity/serialization reasons.
 Analyze shared APIs, contracts, generated artifacts and resources even when tasks edit different files. Unresolved
-shared contracts or insufficient dependency information block the affected tasks; same-file concurrent Coder edits
+shared contracts or insufficient dependency information block the affected tasks; same-file concurrent Implementer edits
 are blocked even for different lines. Do not infer independence from file separation or plan listing order.
 
 A task is ready only when all applicable approvals and execution preparation are complete, required inputs/contracts
@@ -154,7 +162,7 @@ are available and settled, predecessors have required evidence and Orchestrator
 commits (or accepted no-change records), ownership/resources do not conflict, its required check/QA path is available,
 and a subagent slot exists under both the configured ARC full-tree cap shared by all roles and any lower actual runtime
 limit (see [limits](limits.md)). Report runtime limits; ARC's cap is not a claim of runtime capability. Start all ready
-independent tasks with fresh Coders concurrently within capacity; record each hold or serialization reason instead of
+independent tasks with fresh Implementers concurrently within capacity; record each hold or serialization reason instead of
 silently following list order. Preserve existing risk gates, risk-scaled QA/Reviewer timing and execution-target
 restrictions.
 
@@ -206,24 +214,24 @@ Bounded plan-skip, or non-behavior documentation/configuration paths; preserve e
 Normal order: initial design approval → execution-target choice → target preparation and verification →
 formal spec drafting (when required), saving and self-review → written-spec approval → formal plan drafting
 (when required), saving and self-review → individual plan approvals → complete applicable set → existing-commit
-verification and one batch docs commit of remaining approved documents → final Git verification → Coder handoff.
+verification and one batch docs commit of remaining approved documents → final Git verification → Implementer handoff.
 Written-spec approval precedes dependent plan drafting. On document-omission paths skip only the inapplicable document
-steps; preserve target choice, preparation, state/ownership checks and Coder gates.
+steps; preserve target choice, preparation, state/ownership checks and Implementer gates.
 
 While documents are being written, reviewed, or approved, do not stage documents or commit planning documents.
 Selection and initial target preparation happen before formal drafting; document completion is a staging/commit gate,
-not an initial preparation gate. An incomplete set or missing applicable approval blocks document commit and Coder,
-not the initial choice request. No early Coder work is authorized by approval of only some documents.
+not an initial preparation gate. An incomplete set or missing applicable approval blocks document commit and Implementer,
+not the initial choice request. No early Implementer work is authorized by approval of only some documents.
 
 This ARC explicitly defers the local `brainstorming` instruction to commit the spec before written-spec review:
 save and self-review the spec, obtain written-spec approval without committing it, then write and obtain approval for
 all applicable plans. Commit the spec only in the final batch preparation. Do not modify external skills.
 `writing-plans` implementation-step commit instructions
-are not permission for document commits during planning or for starting Coder.
+are not permission for document commits during planning or for starting Implementer.
 
 | Path | Applicable approvals and preparation |
 |------|--------------------------------------|
-| Spike probe | Approve the feasibility question, probe method/scope, acceptance criteria, and constraints. Do not force specs/plans for still-unknown implementation; no new spec obligation is added by this gate. If Coder executes the probe, pass the Common handoff gate after probe approval. Read-only Orchestrator/Planner investigation without Coder does not trigger that gate. |
+| Spike probe | Approve the feasibility question, probe method/scope, acceptance criteria, and constraints. Do not force specs/plans for still-unknown implementation; no new spec obligation is added by this gate. If Implementer executes the probe, pass the Common handoff gate after probe approval. Read-only Orchestrator/Planner investigation without Implementer does not trigger that gate. |
 | Bounded, plan skipped | Approve the short design and record the existing plan-skip criteria/rationale; this gate adds no new spec obligation. Complete applicable approvals, select the target, prepare any actual approved documents, or record valid document absence, then pass the Common handoff gate. |
 | Bounded, plan required | Approve the short design and every required plan; write a spec only when Orchestrator's recorded plan-depth judgment requires it, then obtain its individual written-spec approval before dependent plan drafting. Select and prepare the target before formal drafting; complete all applicable artifacts before one docs batch and the Common handoff gate. |
 | Architectural | Approve design, then written spec, then every required plan using `writing-plans`; select and prepare the target before formal drafting; complete the document set before batch preparation, final verification, and the Common handoff gate. |
@@ -235,16 +243,47 @@ Document omission skips only document obligations, never explicit
 execution-target choice, Git state/ownership checks, or handoff evidence.
 
 If planning reveals new scope, reassess the list, depth, and dependencies and obtain additional required approvals
-before dependent drafting or commit. Changed approved documents require approval of the revised version. If implementation reveals new
-scope, stop affected execution until that scope's documents, approvals, and preparation are complete. Do not amend old
-commits to retroactively include it. An already-running Coder must stop before edits dependent on new plans; inspect
+before dependent drafting or commit. Changed approved document bodies require approval of the revised version, except
+mechanical execution records defined below. If implementation reveals new scope, stop affected execution until that
+scope's documents, approvals, and preparation are complete. Then reflect the approved plan version in its original
+planning-document commit under the update contract below; never retroactively authorize work before actual approval.
+An already-running Implementer must stop before edits dependent on new plans; inspect
 current changes/Git state and do not retroactively claim preparation. A restart without document changes follows Choice
 lifetime and restart record in [handoff.md](handoff.md).
 
+## Plan updates during execution
+
+Mechanical execution records may be recorded without new user approval: checkbox completion, actual results, evidence
+links and task completion state that preserve the approved execution contract. Record their classification, reason and
+actual recording time in the canonical handoff record. Required checks' removal, invented success, unsupported acceptance
+or scope changes mixed with a completion mark are not mechanical records.
+
+Changes to goals, task scope or boundaries, acceptance criteria, method, risk, dependencies or required verification
+require revised-version approval before affected work. Hold affected execution, obtain necessary design/spec/plan approvals
+in order, and complete target, ownership, checks and handoff preparation before resuming. Other approved body corrections
+follow the document-version approval rules; classify typos, paths, commands and explanations by their semantic effect.
+
+Both mechanical records and approved contract revisions amend the original planning-document commit at a safe checkpoint.
+Make no separate document commit or fixup commit, including for newly approved scope. Preserve implementation task commits.
+This history update does not make actual approval time retroactive: the latest plan in the original commit is not evidence
+that its contents were approved from the outset. Never use rewritten history to justify work started before approval.
+
+In the canonical handoff record preserve plan absolute/Git paths; before and after content hashes and versions; prior and
+revised approval references and actual times; change reason and classification; affected tasks and hold/preparation/resume
+evidence. For mechanical records explain why no new approval is needed and record the time. Preserve recoverable document
+contents, not hashes alone, and each old-to-new SHA mapping for the original document commit and descendant task commits.
+Do not overwrite earlier approval references or the contents they approved.
+
+Orchestrator alone performs the safe rewrite in [handoff-prep](handoff-prep.md#execution-time-plan-amendment) and
+[commit](commit.md#execution-time-plan-document-updates). Shared/published or unknown history, merges, unclear ownership,
+unexpected HEAD/dirty state and replay conflicts stop affected work. No force push or fallback document commit.
+After rewriting, connect evidence to the new state under [verification](verification.md#evidence-after-plan-history-rewrite).
+This contract adds no Git automation, runtime enforcement, authority or exemption from required checks/QA/Reviewer gates.
+
 ### Evidence refresh and limits
 
 Missing or mismatched evidence, unfinished approvals, unclear ownership, or unresolved failure blocks the affected
-save, execution-target request, Git mutation, or Coder handoff: stop and report to Orchestrator.
+save, execution-target request, Git mutation, or Implementer handoff: stop and report to Orchestrator.
 Orchestrator resolves the issue and reverifies affected evidence before resumption. Reverify evidence when scope,
 approved versions, paths, target, or relevant Git state changes. Preserve unrelated changes under handoff rules;
 read-only investigation remains allowed.
@@ -253,6 +292,7 @@ Do not retroactively treat an early save or commit as satisfying these gates or
 order and any evidence gap. Structural checks prove only the repository's written policy contract, not consuming-agent
 runtime compliance. Without execution records for role returns, approvals, saves, and Git actions, leave runtime
 compliance unverified. Do not add runtime infrastructure or modify external skills for these checks.
+The narrow exception below applies only to the explicitly approved cooperative CLI path within this repository.
 
 ### Managed worktree preparation
 
@@ -269,8 +309,26 @@ skill. Missing files stop the stage; report paths without global fallback. Keep
 [ARC role policy: contract begin]
 Generated from lib/policy/role-policy.json; do not edit this managed section manually.
 - [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.
-- [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.
+- [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.
+- [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.
+- [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.
+- [planning.planner-brief] Before formal drafting, Orchestrator supplies one complete stage-specific brief with original requirements and criteria IDs, approved/open decisions, verified target and ownership, document paths and preceding approved versions, current behavior and connected source/generated/runtime/installer/documentation surfaces, policy conflicts, depth, dependencies, checks, holds and exact deliverable. Preserve shared brief field order. Review the complete draft once and consolidate substantive feedback as changed fields with other fields marked unchanged. Preserve sequential design, spec and plan approvals; no fixed call cap or incomplete drafts, and no calls for already resolved questions.
+- [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]
+
+## Approved cooperative execution path within the repository
+
+The approved installed workflow entry connects document commits to the initial Implementer assignment in plan mode.
+Resolve `<target-home>/skills/arc/runtime/cli.mjs` from the actual loaded ARC skill location selected by the installation
+resolver, including custom homes. Invoke `node` with that path and command options as separate arguments; for shell
+calls use `node "$ARC_RUNTIME_ENTRY" <command> --cwd "$ARC_CHECKOUT" --workflow "$ARC_WORKFLOW_ID" --input -`
+with safely assigned, quoted values. See [handoff](handoff.md) for invocation and continuity requirements.
+An entry update does not migrate existing state or renew approvals; runtime/target drift still requires current evidence.
+Its scope is decisions and records within the repository's cooperative path. It adds no authority to install native hooks/providers/installers or block direct tool calls.
+`no-plan`/omission is unsupported by this CLI, and this boundary remains in Phases 2 and 3. This does not imply an omission policy violation or a new obligation to write documents.
+
+Orchestrator records the SHA-256 values of the user-approved spec and plan, their shared docs-only commit, document version and approval version.
+The CLI verifies the exact changed paths in actual Git objects and the current document bytes before persisting an assignment intent.
+A new workflow or late document commit cannot prove earlier execution was compliant. Earlier agent history and execution outside this path remain unverified.
+Approval attestations and native returns are `operator-attested`; an agent ID is not an authenticated identity.