@yunhozz/arc 0.2.4 → 0.2.6

package/codex/skill/references/handoff.md

@@ -1,18 +1,18 @@
 <a id="handoff-contract"></a>
 # Handoff contract
 
-Orchestrator reads before every first-start/restart preparation; Implementer trusts verified brief/profile and reads cited sections only. Initial preparation follows [handoff-prep](handoff-prep.md).
+Orchestrator reads this before every first-start or restart preparation; Implementer trusts the verified brief and profile and reads only cited sections. Initial preparation follows [handoff-prep](handoff-prep.md).
 
 <a id="instruction-sources-bounded-read-recovery-visual-evidence-and-resumption"></a>
 ## Instruction sources, bounded read recovery, visual evidence and resumption
 
-Keep shared brief field order, recording source/status within fields. Distinguish user instructions, discovered workspace instructions, installed references and inputs by source/applicability/version or approval/access. Missing root AGENTS.md does not negate user instructions. Missing required skills/references/approved inputs and conflicts hold dependent work.
+Keep shared brief field order, recording source/status within fields. Distinguish user instructions, discovered workspace instructions, installed references and inputs by source/applicability/version or approval/access. A missing root AGENTS.md does not negate user instructions. Missing required skills/references/approved inputs and conflicts hold dependent work.
 
 Optional alternatives need exact locator, material identity, approved version, purpose, method, preconditions, equivalent evidence and return conditions pre-authorized in the brief. Verify alternate locations identify the same material/version. Only side-effect-free reads; no chained search, guessed paths, mutation retries or environment/dependency/permission changes. Return required-input omissions, authority/target/ownership mismatches, partial changes, unknown states and unapproved/ambiguous/failed alternatives immediately. Report first failure/alternative/observations/limits and held dependent/independent work. Orchestrator validates scope/evidence before independent release; unresolved required checks still block acceptance.
 
 Visual briefs include exact approved source/version/approval/access, criterion IDs/properties/method and actual-output identity/revision/basis. Implementer reports differ from fresh QA comparison. Report pass/mismatch/unverified with evidence/limits; return new UI interpretations/substitutions.
 
-Resume briefs preserve valid unchanged-scope approval, completed work, failures/resolution, valid/invalid evidence, holds and next objective. Record changed facts/revalidate gates without repeated completed work. Preserve role/Git/QA/final Reviewer/acceptance/commit boundaries.
+Resume briefs preserve valid approval for unchanged scope, completed work, failures and their resolution, valid and invalid evidence, holds and the next objective. Record changed facts and revalidate gates without repeating completed work. Preserve role/Git/QA/final Reviewer/acceptance/commit boundaries.
 
 <a id="workspace-handoff"></a>
 ## Workspace handoff
@@ -20,9 +20,9 @@ Resume briefs preserve valid unchanged-scope approval, completed work, failures/
 <a id="checkout-approval"></a>
 ### Checkout approval
 
-Before every Implementer start/restart verify supplied absolute workspace accessibility/intended repository. Record actual path, branch/detached HEAD, HEAD and staged/unstaged/untracked state. Inaccessible/wrong repository/unresolved HEAD stops work; no automatic Git initialization/repository switch.
+Before every Implementer start or restart, verify access to the supplied absolute workspace and its intended repository. Record the actual path, branch or detached HEAD, HEAD, and staged, unstaged and untracked state. An inaccessible or wrong repository or unresolved HEAD stops work; do not automatically initialize Git or switch repositories.
 
-Formal spec/plan drafting/saving follows choice/actual preparation; initial design may precede choice. Preparation alone authorizes no Implementer. All approvals/full documents/verified batch or valid absence/final Git checks remain. Separate planned scope/paths, actual preparation and drafting/save/approval/commit, recording chronology/gaps.
+The first required spec/plan draft follows choice and verified source evidence and precedes actual preparation; saving follows verified preparation. Initial design may precede choice. Preparation alone authorizes no Implementer. All approvals/full documents/verified batch or valid absence/final Git checks remain. Separate planned scope/paths, actual preparation and drafting/save/approval/commit, recording chronology/gaps.
 
 After initial design approval record explicit selection: current checkout, new task branch from verified base there, or managed worktree/task branch. Without choice/valid reuse, wait. Reuse through unchanged-scope/target drafting/implementation. Authorized HEAD/dirty changes alone do not invalidate choice; verify preservation/ownership. Changed scope/target requires fresh choice before dependent drafting/preparation without waiting for full documents. Never fall back automatically.
 
@@ -39,7 +39,7 @@ Orchestrator verifies all before start/restart:
 6. Final path/branch/HEAD/state after mutations; no unresolved failure/partial completion.
 7. Brief preparation/final-verification facts/evidence.
 
-Direct edits use approved scope records and the same gates before first edit. Any failure/missing condition blocks handoff, not authorized read-only investigation/preparation/recovery. Revalidate changes to approved content/target/branch/HEAD/state. Implementer reports actual conflicts under its profile; Orchestrator resolves and repasses gates.
+Before the first direct edit, use approved scope records and the same gates. Any failure/missing condition blocks handoff, not authorized read-only investigation/preparation/recovery. Revalidate changes to approved content/target/branch/HEAD/state. Implementer reports actual conflicts under its profile; Orchestrator resolves and repasses gates.
 
 <a id="handoff-evidence"></a>
 ### Handoff evidence
@@ -52,6 +52,7 @@ One canonical record includes:
 - Document SHA/message/paths/approved content; reused versus batch commits or valid absence/depth rationale.
 - Absolute approved artifacts, full set/versions/coverage/dependencies/order and no pending writing/approval.
 - Final verification, failures/partial completion/recovery and each start/restart's approval/choice/reuse.
+- Each plan task ID and current Implementer conversation ID, status, last result and reuse/replacement decision. Before same-task replacement, record the prior ID and status, allowed reason and supporting evidence; hold if the reason is not established. Record the returned ID after a successful initial or replacement call, and reconcile an uncertain call result before another assignment.
 - Worktree source/target paths/common directory/base/branch/name/returned path/app attachment/operationId/registration/source preservation/transfer evidence. No automatic recreation/cleanup/archive.
 
 Give all five roles the same actual workspace/selected checkout, preparation evidence and absolute artifacts. Roles stay there and report missing/inaccessible/conflicting paths/unexpected branches before dependent work, never create/switch workspaces/branches. Tell Implementer others share the repository and unrelated work must be preserved.
@@ -95,7 +96,7 @@ Selected worktrees require common directory, registration, app-managed current-c
 
 Before feature/bug/behavior edits use local `test-driven-development` except explicit ARC exceptions. Full rules live in the profile. Waiver requires all low-risk and plan-skip/direct conditions, recorded scope/justification/criteria/checks before work. User/task-specific TDD overrides it; only qualifying tasks override local generic triggers without changing skills. Ordinary multistep/significant/high-risk work is ineligible.
 
-Waiver skips RED-GREEN only, preserving focused checks/risk-scaled QA/Reviewer; never claim TDD. Blocked required steps need recorded decision/required human approval, not internal substitutes. Non-behavior docs/config use specifically approved exceptions only, never generalize to behavior.
+Waiver skips RED-GREEN only, preserving focused checks/risk-scaled QA/Reviewer; never claim TDD. Follow an applicable higher-priority prohibition on adding or running tests; when precedence and scope are clear, do not report a conflict on that basis or ask permission to violate it. TDD remains applicable to permitted test work. Record unperformed verification and its limits; if precedence or scope is genuinely unclear, or required verification is blocked, hold only affected work and acceptance and report the evidence. Other blocked required steps need recorded decision/required human approval, not internal substitutes. Non-behavior docs/config use specifically approved exceptions only, never generalize to behavior.
 
 <a id="orchestrator-direct-path-for-small-tasks"></a>
 ## Orchestrator direct path for small tasks
@@ -109,6 +110,58 @@ Record target choice/reuse before first edit; scope approval alone selects no ta
 
 Add no plans/automatic commits to omission paths; follow guidance/user requests.
 
+
+### Fast gate
+
+Select the existing direct path only when all eight conditions are `proven`. Record each as `proven`, `unmet`, or `unverified` with evidence; any `unmet`, `unverified`, missing or ambiguous condition requires full evaluation. Missing required inputs or operational failure also holds dependent work; full evaluation is no bypass.
+
+- **F1**: Scope authorization identifies outcome, scope, criteria and edit boundaries, with no unresolved material behavior, method or risk decision.
+- **F2**: One local, understood, reversible change with understood impact and outcome.
+- **F3**: No dependent stages, cross-component shared state, lifecycle or integration-order concerns.
+- **F4**: Meets [risk-scaled execution](verification.md#risk-scaled-execution) low-risk conditions and no existing direct-path exclusion applies.
+- **F5**: One focused verification path covers criteria and identifies required independent QA/Reviewer.
+- **F6**: Explicit target choice or valid reuse, current workspace and change state, preservation and no active ownership conflict are established.
+- **F7**: Applicable TDD is identified; any waiver or non-behavior exception meets existing conditions and is recorded beforehand. Explicit user/task TDD overrides waiver.
+- **F8**: Applicable instruction source-set and approval, target, criteria and verification evidence are accessible, consistent and unambiguous.
+
+Security/permissions and public-interface changes are never eligible under the existing significant-risk exclusions. File count, LOC and apparent simplicity prove none of F2–F5. This gate does not replace the first direct edit gate, Implementer start/restart gate, target choice, TDD, independent QA and Reviewer, acceptance or commit; existing triggers determine whether each gate applies. The fast path does not add untriggered role, QA/Reviewer, acceptance or commit obligations. Preserve all existing platform restrictions.
+
+### Instruction fingerprint
+
+Record the actual applicable source-set: platform ARC SKILL, these initial reference sections, applicable workspace instructions, and triggered references/skills; record user/platform messages by message and approval reference, not invented file hashes. Record native role profile source/version when assigned; a new role receives actual instructions, profile, needed paths and criteria, not merely a hash. Do not assume disk profile changes updated an active role.
+
+Distinguish user-provided instructions, workspace instructions, installed references and task inputs by source, applicability and access state: available, absent, inaccessible, conflicting or unverified. For every file record source kind, absolute and resolved path, read sections, available revision, SHA-256 of entire file bytes, access state, observation and read-context references. Neither HEAD nor installer manifest substitutes for actual installed-source hash. Use only already identified source paths; do not search or guess. An uncertain source-set makes F8 `unverified`.
+
+Reuse read content only for the same source-set, absolute source locators, resolved paths, hashes, scope and same conversation context with meaning still available. Different absolute locators cannot be reused even if they resolve to the same path. New context, inaccessible record or context loss requires rereading; changed source/hash requires rereading and reassessing affected judgments. Verify the current source-set/hash at a new fast judgment, first-edit or assignment/restart/resumption gate, before acceptance, and on known source changes; reuse observations within the same gate. If hashing fails, do not reuse; follow existing read recovery and hold required inaccessible inputs. When Node is already available, batch identified absolute paths with built-in `node:fs` realpath/readFileSync and `node:crypto` SHA-256; install nothing and print no source content.
+
+
+For identified absolute sources only, when Node is already available, this read-only example prints paths and hashes, not contents:
+
+```sh
+node --input-type=module -e '
+import fs from "node:fs";
+import crypto from "node:crypto";
+const sources = process.argv.slice(1);
+if (!sources.length) throw new Error("No instruction sources");
+for (const source of sources) {
+  const resolvedPath = fs.realpathSync(source);
+  const contentHash = "sha256:" + crypto.createHash("sha256").update(fs.readFileSync(resolvedPath)).digest("hex");
+  process.stdout.write(JSON.stringify({source, resolvedPath, contentHash}) + "\n");
+}
+' -- '/absolute/identified/source-1' '/absolute/identified/source-2'
+```
+A new conversation or lost context requires reread; unchanged HEAD alone does not prove instruction, file or check evidence current.
+
+### Task envelope
+
+Place the compact envelope in the existing canonical handoff record or existing inline scope record, not a new file, store or API. Record task path and outcome; instructions; target; approval; scope and criteria; risk and depth; TDD; verification; refresh. Specifically include task ID/path, source fingerprint/read context, workspace/branch/HEAD/change state/preservation/ownership, scope approval and target choice, edit boundaries/criteria, F1–F8 evidence/risk/depth, TDD or recorded exception, criterion checks/QA/Reviewer/acceptance, and observations/changes/revalidation/holds. Link accessible records; inaccessible references do not replace required content. Embed it in the existing eight specialist brief fields in their fixed order, without a ninth field or full history.
+
+The nine fields are `task`, `instructions`, `target`, `authorization`, `scopeCriteria`, `riskDepth`, `tdd`, `verification`, and `refresh`; task records the task ID/path and selected path `fast-direct` or `full`, and verification includes criteria-specific checks and their evidence.
+
+### Evidence refresh
+
+Evaluate target choice validity separately from evidence validity. Approved HEAD or expected dirty changes do not invalidate target choice by themselves: record current state, preservation and ownership, and assess affected criteria/checks. Revalidate only affected evidence; a related file change after a check leaves that check unverified until repeated as needed. Changed instructions require reassessing linked fast/risk/TDD/authorization judgments. Preserve unaffected evidence and valid approvals. Unclear impact, missing or inaccessible evidence, ownership conflict, failure or partial/unknown state requires existing hold and recovery; workspace/target change or loss of trust follows target-choice rules. For a target change, obtain a new choice where required and state confirmation before dependent edit. Scope/criteria/method/risk changes follow existing approval and fresh-role rules. A failed direct check or QA finding returns to existing Implementer/recheck ownership.
+
 <a id="cooperative-cli-verification-handoff"></a>
 ## Cooperative CLI verification handoff
 
@@ -118,7 +171,7 @@ On scope/docs/approval changes inspect `affectedTaskIds`/dependencies, preserve
 
 [ARC role policy: contract begin]
 Generated from lib/policy/role-policy.json; do not edit this managed section manually.
-- [git.specialists-deny] Specialists must not change Git state during implementation or recovery: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal. Explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection within the assigned scope remains allowed.
+- [git.specialists-deny] Specialists must not change Git state during implementation or recovery: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal. Explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection 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 approved exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git mutations remain forbidden after successful implementation. Implementer and fresh QA handoffs 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. Record 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 state. Missing source/output, inaccessible evidence or unapproved interpretation holds the affected visual claim for Orchestrator. Do not silently substitute or redesign.
 - [review.significant-no-plan] Significant/high-risk work without a plan follows Implementer → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. Do not omit Reviewer because no plan exists. This adds no plan obligation.
 - [review.significant-plan] Significant/high-risk plan work follows Implementer → required fresh QA → Orchestrator acceptance and focused commit for each task. 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 gate. Preserve required checks and necessary finding rechecks.

package/codex/skill/references/limits.md

@@ -1,14 +1,14 @@
 <a id="subagent-limits"></a>
 # Subagent limits
 
-Before first creation, Orchestrator reads this reference and adjacent `../limits.toml` (installed at `skills/arc/limits.toml`). Require `version = 1` and positive safe-integer `max_total_subagents`/`max_concurrent_subagents`. Installation defaults are `100`/`5`. Missing, malformed or unreadable policy blocks creation; report it without assuming defaults. Freeze settings for one ARC session/tree; reinstalling affects new sessions.
+Before the first creation, Orchestrator reads this reference and the adjacent `../limits.toml` (installed at `skills/arc/limits.toml`). Require `version = 1` and positive safe-integer `max_total_subagents`/`max_concurrent_subagents`. Installation defaults are `100`/`5`. Missing, malformed or unreadable policy blocks creation. Report it without assuming defaults. Freeze settings for one ARC session/tree; reinstalling affects new sessions.
 
 <a id="counting-and-reservations"></a>
 ## Counting and reservations
 
 - Track instance IDs, parent IDs, pending reservations, creation outcomes and active/completed state in the session ledger. Exclude Orchestrator, but count every created descendant, including nested/non-ARC agents.
-- Completion never refunds cumulative creation. Same-instance follow-up/resume adds nothing; fresh instances, new-instance retries and replacements increment the total.
-- Waiting, blocked, running and resumable idle instances consume concurrency until confirmed completion/termination. Obey lower actual runtime capacity, including native retention of completed instances. ARC counts do not prove free native slots.
+- Completion never refunds cumulative creation. A follow-up or resume using the same instance adds nothing; fresh instances, new-instance retries and replacements increment the total.
+- Waiting, blocked, running and resumable idle instances consume concurrency until completion or termination is confirmed. Obey lower actual runtime capacity, including native retention of completed instances. ARC counts do not prove free native slots.
 
 Reserve the full proposed parallel batch before dispatch, satisfying both:
 
@@ -20,9 +20,9 @@ Reserve before each call. Confirmed creation becomes a created/active ID. Releas
 <a id="continuation-and-exhaustion"></a>
 ## Continuation and exhaustion
 
-Preserve the ledger across continuation/resume/compaction and reconcile actual IDs before dispatch. Never reset lost counters to zero. Incomplete reconstruction holds creation and reports unknown budget; use a conservative upper bound only when records support it.
+Preserve the ledger across continuation, resume and compaction, and reconcile actual IDs before dispatch. Never reset lost counters to zero. Incomplete reconstruction holds creation and reports unknown budget; use a conservative upper bound only when records support it.
 
-Completion frees confirmed active capacity only. Exhaustion holds creation and reports remaining work/budget; it never waives QA/Reviewer, role freshness, approval, ownership, dependency or same-file edit gates.
+Confirmed completion or termination frees active capacity. Exhaustion holds creation and reports remaining work/budget; it never waives QA/Reviewer, role freshness, approval, ownership, dependency or same-file edit gates.
 
 Cumulative limits and scheduling are prompt policy, not hard runtime controls. Text tests prove package consistency, not live compliance/native support.
 Codex `[agents].max_concurrent_threads_per_session` and Claude `settings.json.env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` constrain their respective sessions.

package/codex/skill/references/planning.md

@@ -1,16 +1,18 @@
 <a id="planning-contract"></a>
 # Planning contract
 
-Read before depth judgments, spec/plan drafting/approval and first saves.
+Read before depth judgments, spec or plan drafting and approval, and first saves.
 
 <a id="authorization-and-scope"></a>
 ## Authorization and scope
 
+Use the [fast gate and envelope](handoff.md#orchestrator-direct-path-for-small-tasks) alongside these existing scope and approval rules; reuse valid approvals and hold changed scope under these rules.
+
 An explicit execution request authorizes only sufficiently specified scope from that request or a description the user explicitly references. Confirm intent/outcome/constraints/document depth/verification risk and no unresolved material behavior/method/risk decision. Record approval evidence, scope, criteria, constraints and depth. Orchestrator may choose routine execution/check details, not unapproved product behavior/material scope. Restating/handoff/restart of unchanged scope needs no new approval.
 
 Silence, ambiguous assent, other-work approval and vague blanket improvements are insufficient. Planner's new material choices are not automatically approved. Request missing decisions through Orchestrator. Required specs/plans retain separate ordered approval.
 
-Material scope/method/risk changes hold affected work with missing decision/evidence/remaining scope reported. Target change, unclear ownership, unexpected state, unresolved failure or missing inputs also hold under [handoff](handoff.md)/[recovery](git-recovery.md). Distinguish new authorization from existing-scope execution issues; routine correction/reverification needs no duplicate approval. Revalidate after resolution.
+Hold affected work for material changes to scope, method or risk, and report the missing decision, evidence and remaining scope. Target change, unclear ownership, unexpected state, unresolved failure or missing inputs also hold under [handoff](handoff.md)/[recovery](git-recovery.md). Distinguish new authorization from existing-scope execution issues; routine correction/reverification needs no duplicate approval. Revalidate after resolution.
 
 <a id="probe-scope"></a>
 ### Probe scope
@@ -22,24 +24,26 @@ If explicitly requested probe+implementation is fully specified, classify the wh
 <a id="formal-drafting-boundary"></a>
 ## Formal drafting boundary
 
-Initial design/brainstorming may precede target choice. Formal spec/plan includes complete pre-save drafts returned only in chat. Before that, Orchestrator records actual absolute workspace/repository, branch/detached HEAD/HEAD, changes/ownership, explicit choice/preparation and in-target absolute document paths. Planner drafts for verified target; Orchestrator saves there. Missing/mismatched evidence stops affected drafting/saving. Planned paths prove no actual preparation. Initial preparation never starts Implementer without full handoff.
+Initial design/brainstorming may precede target choice. Before the first required spec/plan draft, record verified source workspace/repository, branch/HEAD, changes/ownership, explicit choice, approved scope/depth/document set and planned relative paths. Planner returns the complete first draft and self-review in chat before target preparation. Revalidate source and selected target at the focused preparation gate, prepare the chosen target, compare actual target and preservation, then review and save in the verified prepared target. Planned paths prove no preparation. Missing or mismatched evidence holds affected work; preparation alone never starts Implementer.
 
-Small-task direct edits follow only [handoff](handoff.md#orchestrator-direct-path-for-small-tasks), stopping/reclassifying changed scope/risk. Otherwise follow this reference. `brainstorming`/`writing-plans` instruct existing roles, not extra agents; ARC routing/approval overrides alternate executors. Missing required skills block their stage. Integration means save/route/request approval, never author.
+Small-task direct edits follow only [handoff](handoff.md#orchestrator-direct-path-for-small-tasks), stopping/reclassifying changed scope/risk. Otherwise follow this reference. `brainstorming`/`writing-plans` instruct existing roles, not extra agents; ARC routing/approval overrides alternate executors. Missing required skills block their stage. Integration includes saving, reviewing and directly revising the same spec or plan after the complete Planner first draft; design/brainstorming retain their Planner drafting path.
 
-For Korean requests/briefs, Planner uses Korean titles/prose unless another language is requested, preserving identifiers, skill/API names, code, paths, commands and literals. Orchestrator preserves agreed language when saving.
+For Korean requests and briefs, Planner uses Korean titles and prose unless another language is requested, preserving identifiers, skill/API names, code, paths, commands and literals. Orchestrator preserves agreed language when saving.
 
 <a id="planner-drafting-preparation-and-consolidated-feedback"></a>
 ## Planner drafting preparation and consolidated feedback
 
 Planner reports initial/revision progress only to Orchestrator: brief stage/feedback/blocker/next step, never body/excerpts/incremental drafts. Return complete draft/self-review. Raw responses may appear in app/tool surfaces; prompt policy cannot hide them. User updates stay brief/status-based without draft content. At approval present integrated/saved/reviewed Markdown without repeating its body in chat.
 
+Before Planner dispatch, evaluate F1–F8 direct-path eligibility and Bounded plan-omission eligibility independently. Enter each path only when all of that path's existing conditions are proven; if neither path qualifies, use normal full evaluation. Orchestrator can read a few already identified files directly; route material research and broad static exploration to Scouter.
+
 1. Preflight relevant policy/references/profiles/tests/parity/manifest/conflicts. Apply formal-target and coordination provenance/input/local-skill gates, including required paths, approved bounded read alternatives and return conditions. Missing inputs/conflicts hold drafting. Read recovery grants no preparation/check/write/approval authority.
 2. Maintain a compact ledger of original requirements/IDs, approved/open decisions, exclusions and scope deltas. Consolidate intervening user changes into one brief delta. Separate approvals, path/line-verified facts, assumptions and open decisions.
-3. Send one complete stage-specific initial brief: prepared target/HEAD/ownership, scope/exclusions/depth/dependencies/shared contracts/criteria/checks/evidence/holds; preceding approved versions, paths, current behavior and connected source/generated/runtime/installer/docs, policy conflicts/resolution direction and exact deliverable. Visual work includes approved sources/versions/criteria/open interpretations.
-4. Planner returns complete proportional draft/self-review; Orchestrator integrates/saves/reviews/requests approval without authoring missing content. Review once with the fixed checklist: scope/evidence; targets/ownership/paths; policy/conflicts; task boundaries/dependencies/criteria; checks/evidence/holds; roles/approval/commit boundaries; completeness. Finish before one consolidated correction covering every substantive omission with criterion/defect/evidence/expected fix. Use deltas/`unchanged`; never split by omission.
-5. Further calls after correction need approved material scope/evidence changes or concrete unmet checklist items plus meaningful new input/criterion progress. State changed input/target criterion/expected artifact/progress. Existing-scope omissions need no renewed scope approval. Repeated unmet criteria without new input/evidence/progress hold the stage; report criterion/observation/exact unblock decision. Do not repeat resolved questions or count rewording/agent replacement as progress.
+3. Reuse a relevant Planner instance across related stages when role, context and source remain valid. Send one complete stage-specific initial brief. Include verified source/HEAD/ownership, selected target intent and planned paths (or prepared target for later stages), and scope/exclusions/depth/dependencies/shared contracts/criteria/checks/evidence/holds. Include preceding approved versions and paths, current behavior and connected source/generated/runtime/installer/docs, policy conflicts/resolution direction and exact deliverable. Visual work includes approved sources/versions/criteria/open interpretations. Follow-up briefs send changed fields and cite an accessible prior brief for unchanged fields; inaccessible conversations or hashes alone cannot replace required inputs. Reuse evidence only for the same source set, absolute locator, resolved path, content fingerprint, purpose, approval scope and accessible context. When source, target or scope changed, reconfirm affected inputs.
+4. Planner returns the complete proportional first draft and self-review. Orchestrator saves and reviews it against the fixed checklist: scope/evidence; targets/ownership/paths; policy/conflicts; task boundaries/dependencies/criteria; checks/evidence/holds; roles/approval/commit boundaries; completeness. For spec or plan, Orchestrator directly revises the same document, including substantive omissions, before requesting approval. New product decisions outside approved scope require user input first; Orchestrator then revises the document. Missing or failed first drafts stop the stage and do not transfer initial authorship.
+5. For design and brainstorming, finish the checklist before one consolidated correction covering every substantive omission with criterion/defect/evidence/expected fix. Use deltas/`unchanged`; never split by omission. Further calls after correction need approved material scope/evidence changes or concrete unmet checklist items plus meaningful new input/criterion progress. State changed input/target criterion/expected artifact/progress. Existing-scope omissions need no renewed scope approval. Repeated unmet criteria without new input/evidence/progress hold the stage; report criterion/observation/exact unblock decision. Do not repeat resolved questions or count rewording/agent replacement as progress.
 
-Allow initial draft and one consolidated correction. Reformatting/re-expression/save/patch errors belong to Orchestrator, not Planner calls. Separate substantive work uses normal gates. Design/spec/plan stages remain separately ordered; spec approval precedes dependent planning. Add no fixed call cap/profile count condition or incomplete-draft acceptance.
+For design and brainstorming, allow initial draft and one consolidated correction. Orchestrator handles reformatting, re-expression, save and patch errors without Planner calls. Separate substantive work uses normal gates. Design/spec/plan stages remain separately ordered; spec approval precedes dependent planning. Add no fixed call cap/profile count condition or incomplete-draft acceptance.
 
 <a id="design-and-planning"></a>
 <a id="design-path-and-plan-depth"></a>
@@ -53,9 +57,11 @@ Record depth separately from risk. Risk controls checks/review, not design paths
 4. Record dependencies/depth reasons. Planner returns complete plan/assumptions/open decisions/checks/self-review. Orchestrator saves/reviews/obtains approval before Implementer at user path or `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`. Default spec path is `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`.
 5. Every Implementer first start/restart needs applicable approvals/artifacts/brief/findings and full handoff. Non-behavior docs/config omit only inapplicable stages. Direct edits need approved scope record and same first-edit gates.
 
-If Bounded requires written spec, record necessity/scope using approved short design as basis. Planner returns proportional full spec/self-review; Orchestrator saves/reviews/obtains individual approval before dependent plan/preparation. Short design approval never substitutes. This applies recorded judgment, not new spec necessity. Required plans alone imply no written spec.
+If Bounded requires written spec, record necessity/scope using approved short design as basis. Planner returns proportional full spec/self-review; After actual preparation, Orchestrator saves/reviews/obtains individual approval in the prepared target before the dependent plan. Short design approval never substitutes. This applies recorded judgment, not new spec necessity. Required plans alone imply no written spec.
+
+Only Planner authors the first complete spec or plan draft and self-review. Orchestrator reviews and directly revises the same document before approval. Unavailable/failed Planner stops first drafting rather than transferring authorship. Design approval does not transfer initial authorship.
 
-Only Planner drafts. Never substitute Orchestrator-authored specs/plans. Return substantive omissions; unavailable/failed Planner stops work rather than transferring authorship. Design approval does not transfer ownership.
+For initial fast judgment apply the [fast gate](handoff.md#orchestrator-direct-path-for-small-tasks); its sufficient conditions do not change these depth decisions.
 
 <a id="top-level-plan-tasks"></a>
 ## Top-level plan tasks
@@ -85,7 +91,7 @@ Before first Architectural spec, required Bounded spec or plan save, read this a
 | Spec | Approved design scope/evidence, complete Planner draft/self-review, Orchestrator integration/save/review ownership and absolute path. Required Bounded specs also need depth judgment, short design, necessity/scope |
 | Plan | Approved design and required approved spec/version/evidence, depth judgment, plan list/dependencies, complete Planner draft/self-review, ownership and absolute path |
 
-Saving for review does not require prior written-spec approval, but does require valid target choice/actual preparation. Individually approved specs enter the document set before dependent planning. Never call uncommitted files committed. Missing/mismatched evidence stops the affected save.
+Saving for review does not require prior written-spec approval, but does require valid target choice/actual preparation. Individually approved specs enter the document set before dependent planning. Never call uncommitted files committed. Missing or mismatched evidence stops the affected save.
 
 <a id="complete-planning-document-set"></a>
 ## Complete planning-document set
@@ -94,7 +100,7 @@ Include all current-scope required specs/plans, excluding future projects. Recor
 
 A required plan implies no spec. Bounded follows recorded judgment; spec stages cover Architectural/required Bounded only, plan stages required plans only. Add no spec duty to Spike/plan-skip/non-behavior paths.
 
-Order: initial design approval → explicit target → actual preparation/verification → required spec drafting/save/self-review/individual approval → required plans drafting/save/review/individual approval → full set → verify existing commits/batch remaining approvals → final Git → Implementer. Omission skips only inapplicable documents with rationale. Complete documents precede staging/commit/handoff, not initial preparation/choice request. Partial approvals authorize no early implementation.
+Order: initial design approval → explicit target and source snapshot → first required draft/self-review → focused preparation gate → actual preparation/comparison → save/review/individual approval → dependent plans drafting/save/review/individual approval → full set → verify existing commits/batch remaining approvals → final Git → Implementer. Omission skips only inapplicable documents with rationale. Complete documents precede staging/commit/handoff, not initial preparation/choice request. Partial approvals authorize no early implementation.
 
 Defer local `brainstorming`'s early spec commit: save/self-review/approve uncommitted spec, approve all plans, then final batch. Modify no external skill. `writing-plans` implementation commits grant neither planning-document commits nor early Implementer.
 
@@ -102,8 +108,8 @@ Defer local `brainstorming`'s early spec commit: save/self-review/approve uncomm
 |---|---|
 | Spike | Approve question/method/scope/criteria/constraints; no forced unknown-implementation docs. Implementer probes require handoff; read-only Orchestrator/Planner probes without Implementer do not trigger it |
 | Bounded, plan skipped | Approve short design; record omission conditions. Complete approvals, target choice, actual docs or valid absence, then handoff |
-| Bounded, plan required | Approve design/all required plans; approve necessary specs before dependent planning. Prepare target before drafting, complete set before batch/handoff |
-| Architectural | Design → written spec → all `writing-plans` plans. Target before drafting; full set before batch/final checks/handoff |
+| Bounded, plan required | Approve design/all required plans; approve necessary specs before dependent planning. Draft the first required document before target preparation; complete set before batch/handoff |
+| Architectural | Design → written spec → all `writing-plans` plans. First spec draft before target preparation; full set before batch/final checks/handoff |
 | Non-behavior docs/config | Record scope/criteria/inapplicability. Preserve target/Git/docs-or-absence/handoff |
 
 New planning scope requires list/depth/dependency reassessment and approvals before dependent drafting/commit. Approved-body changes need revised approval except mechanical records below. New implementation scope holds execution until docs/approvals/preparation complete. Running Implementer stops before newly dependent edits; inspect actual changes/Git without retrospective preparation claims. Reflect approved versions through original-commit updates below. Unchanged-document restarts follow handoff lifetime.
@@ -113,7 +119,7 @@ New planning scope requires list/depth/dependency reassessment and approvals bef
 
 Mechanical checkboxes/results/evidence/completion preserving the approved contract need no new approval; record classification/reason/actual time. Removing checks, invented success, unsupported acceptance or mixed scope changes are not mechanical.
 
-Goal/task boundary/scope/criteria/method/risk/dependency/check changes require revised approval before affected work. Hold, obtain ordered design/spec/plan approvals and prepare target/ownership/checks/handoff. Other body corrections follow version approval; classify typos/paths/commands/explanations by semantic effect.
+Changes to goals, task boundaries, scope, criteria, method, risk, dependencies or checks require revised approval before affected work. Hold, obtain ordered design/spec/plan approvals and prepare target/ownership/checks/handoff. Other body corrections follow version approval; classify typos/paths/commands/explanations by semantic effect.
 
 Both kinds amend the original planning commit at safe boundaries, never separate docs/fixup commits, including new scope. Preserve implementation commits. Rewriting does not backdate approval; latest content in an old commit proves no earlier authorization.
 
@@ -151,7 +157,7 @@ Generated from lib/policy/role-policy.json; do not edit this managed section man
 - [review.significant-plan] Significant/high-risk plan work follows Implementer → required fresh QA → Orchestrator acceptance and focused commit for each task. 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 gate. Preserve required checks and necessary finding rechecks.
 - [review.final-plan-recheck] Final overall Reviewer findings on plan work, including behavior findings, follow Implementer → Reviewer without QA reassignment until resolved. This exception applies only at the final plan stage. Preserve required QA and QA failure rechecks before the initial final review and outside this exception.
 - [planning.plan-amend] Mechanical plan progress records during approved execution need no new user approval. Changes to goals, scope, criteria, method, risk, dependencies or required verification need revised-version approval and preparation before affected work. In both cases Orchestrator amends the original planning-document commit at a safe boundary, with no separate document or fixup commit. Preserve actual approval chronology, recoverable old/new content, hashes, versions and SHA mappings; never authorize past work retroactively. Rewrite only unpublished, unshared local linear history with clear ownership and no merges. Unknown publication/ownership, unexpected state or replay conflicts stop rewriting; no force push or fallback document commit. Preserve implementation task boundaries and revalidate affected evidence. Follow planning, handoff-prep, commit and verification for the full contract.
-- [planning.planner-brief] Follow planning.md's Planner drafting preparation and consolidated feedback procedure, including preflight, ledger, evidence classification, target preparation, preceding approvals, provenance and reference gates. Allow the initial draft and one consolidated correction. Send one complete stage-specific initial brief. Planner returns a complete proportional draft and self-review. Orchestrator reviews once with the fixed checklist and sends one consolidated correction using changed fields only. Further calls require user-approved material scope/evidence changes or concrete unmet checklist items after correction, plus meaningful new input or criterion-state progress. State changed input, target criterion, expected artifact and expected progress. Hold repeated unmet criteria without new input, evidence or progress; report the criterion, observed evidence and exact unblock input/decision. Do not split omissions, repeat resolved items or count rewording/agent replacement as progress. Do not invoke Planner only for reformatting, re-expression, save errors or patch-application errors; Orchestrator handles these. Evaluate separate substantive work under the normal Planner gate. Preserve separate sequential design/spec/plan approvals. Add no fixed call cap or profile call-count conditions, and never accept an incomplete draft. Keep user progress brief and based on Planner status without relaying draft content. At approval, present the integrated, saved and reviewed Markdown without repeating its body in chat.
+- [planning.planner-brief] Follow planning.md's Planner drafting preparation and review procedure, including preflight, ledger, evidence classification, target preparation, preceding approvals, provenance and reference gates. Before Planner dispatch, evaluate F1–F8 direct-path eligibility and Bounded plan-omission eligibility independently. Enter each path only when all of that path's existing conditions are proven; if neither path qualifies, use normal full evaluation. Send one complete stage-specific initial brief. Reuse the same Planner instance across related stages when its role, context and source remain valid. Follow-up briefs send changed fields and cite an accessible prior brief for unchanged fields. Reuse evidence only for the same source set, absolute locator, resolved path, content fingerprint, purpose and approval scope in an accessible matching context. When source, target or scope changed, reconfirm affected inputs. Planner returns a complete proportional first draft and self-review. Orchestrator reviews and directly revises the same spec or plan when needed. A missing or failed first draft does not transfer initial authorship to Orchestrator. New product decisions outside approved scope require user input before Orchestrator revises the document. For design and brainstorming, allow the initial draft and one consolidated correction. Orchestrator reviews once with the fixed checklist and sends one consolidated correction using changed fields only. Further calls require user-approved material scope/evidence changes or concrete unmet checklist items after correction, plus meaningful new input or criterion-state progress. State changed input, target criterion, expected artifact and expected progress. Repeated unmet criteria without new input, evidence or progress hold the stage; report the criterion, observed evidence and exact unblock input/decision. Do not split omissions, repeat resolved items or count rewording/agent replacement as progress. Do not invoke Planner only for reformatting, re-expression, save errors or patch-application errors; Orchestrator handles these. Evaluate separate substantive work under the normal Planner gate. Preserve separate sequential design/spec/plan approvals. Add no fixed call cap or profile call-count conditions, and never accept an incomplete draft. Keep user progress brief and based on Planner status without relaying draft content. At approval, present the integrated, saved and reviewed Markdown without repeating its body in chat.
 - [platform.codex] Role restrictions are prompt-level contracts, not a filesystem sandbox. ARC supplies no native observer hook or role-specific Git guard. Existing shell capabilities are retained because static read access after shell reduction has not been verified; Implementer and QA need shell for approved checks.
 [ARC role policy: contract end]
 

package/codex/skill/references/scripts/start-server.sh

@@ -114,6 +114,13 @@ umask 077
 SESSION_ID="$$-$(date +%s)"
 
 if [[ -n "$PROJECT_DIR" ]]; then
+  # Make the project dir absolute now: the script cds into its own directory
+  # before starting the server, which would re-root a relative path there.
+  # mkdir -p keeps the existing behavior of creating a missing project dir.
+  if ! PROJECT_DIR="$(mkdir -p -- "$PROJECT_DIR" && CDPATH='' cd -- "$PROJECT_DIR" && pwd)"; then
+    echo "{\"error\": \"Cannot create or enter --project-dir\"}"
+    exit 1
+  fi
   SESSION_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
   # Persist the bound port and key per project so a restart reuses them and an
   # already-open browser tab reconnects to the same URL with a valid cookie.

package/codex/skill/references/superpowers-provenance.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "repository": "https://github.com/obra/superpowers",
-  "revision": "bb92a77741419a4ab5f06e711a283343f1ada0c3",
-  "fetchedAt": "2026-10-17T07:50:01.077Z",
+  "revision": "22f0b463e7a5e579904dd6211a520321035526f7",
+  "fetchedAt": "2026-11-06T16:48:59.704Z",
   "skills": [
     "brainstorming",
     "writing-plans",
@@ -10,12 +10,12 @@
   ],
   "files": {
     "LICENSE": "a37e0e9697144819e1d965176ac4ae5bc3fa02d11e7812036bbcadf6dafe2400",
-    "brainstorming/SKILL.md": "6ee10d1481b8a2580d5336ff66c5c08acc9d4b251b13bbc3bfd31be99c261d43",
+    "brainstorming/SKILL.md": "2c9ca71f94886f9ca9f4aef055f7cafb3e1a9bdf3aeebf8f4cb547c69405d207",
     "brainstorming/builder-check-prompt.md": "36d51a4723d6f0a3ce5811a0ea3b3a8424f07533947e1355f5d8cb8cce40c55e",
     "brainstorming/scripts/frame-template.html": "6a8a4e58bd6a44b904e2e3c57de774481d909204597e1498de53f1b2fecc4c4e",
     "brainstorming/scripts/helper.js": "43c6d69954a46ec34a2a262bcc62a9a7e83e839c739f199cb72646d397c686e3",
     "brainstorming/scripts/server.cjs": "763abf96510e0b892a1141397b31aa82ef900cf87ed34dde94bc8782baf4a7ca",
-    "brainstorming/scripts/start-server.sh": "a4e5ae84275bcaacd2f84345afeabe59cf7b00ba080e123da7cc1fb226f12847",
+    "brainstorming/scripts/start-server.sh": "314dd68dc00e8dd94c7491aca8a5f004c7fddffc161e2b07482f29f48d13659a",
     "brainstorming/scripts/stop-server.sh": "0b5ccbbd57f62d3ed88993f7940b5ee0e5c0fc9b21c550c623da4f6292e47daf",
     "brainstorming/visual-companion.md": "6ffcb038b53254bd31debaa15e12dcd4ff24bd63d690e0b644ac6396701cf2e2",
     "writing-plans/SKILL.md": "a6c67c1900064347c2a329990dd3c555657c51c3ec53b259a08aa01a2c26139a",

package/codex/skill/references/verification.md

@@ -8,14 +8,16 @@ Read before verification design, QA/Reviewer assignment, correction rechecks or
 <a id="visual-evidence-and-adjudication"></a>
 ## Visual evidence and adjudication
 
-Each criterion needs exact approved source/version/approval/access, IDs/properties/method and output-revision linkage. Implementer reporting does not replace fresh QA. Record pass/mismatch/unverified and connect to criterion verdicts; pass needs accessible supporting evidence. Missing linkage is unverified; visible difference is mismatch, separately, without inferring current branch UI. Inaccessible materials/missing interpretation approval hold comparison.
+Each criterion needs the exact approved source, version, approval and access state; IDs, properties and comparison method; and a link between output and revision. Implementer reporting does not replace fresh QA. Record pass/mismatch/unverified and connect to criterion verdicts; pass needs accessible supporting evidence. Missing linkage is unverified; visible difference is mismatch, separately, without inferring current branch UI. Hold comparison when materials are inaccessible or interpretation approval is missing.
 
-Policy/generated/manifest checks prove structure, not role behavior, installed builds, Claude Code CLI compliance or fidelity. Report changes/exclusions/run-omitted checks/criterion evidence-limits/platform availability. Separate baseline failures; independent progress relaxes no checks.
+Policy, generated-file and manifest checks prove structure, not role behavior, installed builds, Claude Code CLI compliance or fidelity. Report changes, exclusions, checks run and omitted, criterion evidence and limits, and platform availability. Report baseline failures separately; independent progress does not relax checks.
 
 <a id="risk-scaled-execution"></a>
 ## Risk-scaled execution
 
-Edits belong to Implementer except the [small direct path](handoff.md#orchestrator-direct-path-for-small-tasks). Orchestrator determines behavior/risk/minimum meaningful checks.
+The [fast gate](handoff.md#orchestrator-direct-path-for-small-tasks) references this risk definition; refresh affected evidence when inputs change and preserve independent verification boundaries.
+
+Edits belong to Implementer except the [small direct path](handoff.md#orchestrator-direct-path-for-small-tasks). Orchestrator determines behavior, risk and minimum meaningful checks.
 
 | Risk | Minimum flow |
 |---|---|
@@ -34,7 +36,7 @@ Ordinary/significant tasks need fresh QA before acceptance. Low risk requires na
 
 Record which risk/instruction/approved obligations each check satisfies. Do not automatically assign QA/Reviewer for clear low-risk scope with sufficient evidence and no requirement. Metadata counts alone prove no significance; one permission/loss rule may. Vague file deletion is not low-risk evidence; reclassify installer/manifest impacts. Confirm cleanup targets unused, required materials intact, ignore patterns scoped and diff approved before focused-check-only acceptance.
 
-Separate environment/code failure and report exact limits/gaps. Use Planner/Scouter only for unresolved planning/discovery. Reviewer covers substantial correctness/factual/security/data/interface risks. Orchestrator assigns support as needed. Claim only verified outputs. Read cited `references/test-driven-development.md`, preserving exceptions.
+Distinguish environment failures from code failures and report exact limits and gaps. Use Planner/Scouter only for unresolved planning/discovery. Reviewer covers substantial correctness/factual/security/data/interface risks. Orchestrator assigns support as needed. Claim only verified outputs. Read cited `references/test-driven-development.md`, preserving exceptions.
 
 <a id="final-plan-reviewer-correction-loop"></a>
 ### Final plan Reviewer correction loop

package/codex/skill/runtime/bootstrap.mjs

@@ -6,7 +6,7 @@ import {observeCooperativeTarget,validateObservedTarget,validateWorkflowId,workf
 import {saveDurableState} from './store.mjs';
 export const COOPERATIVE_RUNTIME_MODULES=Object.freeze([
  'cli.mjs','command.mjs','bootstrap.mjs','cooperative-schema.mjs','cooperative.mjs','evaluate.mjs',
- 'scope.mjs','store.mjs','git-evidence.mjs','assignment.mjs','verification.mjs','acceptance.mjs','external.mjs','schema.mjs','operations.mjs','gate.mjs','adapters/codex.mjs','adapters/claude.mjs','capabilities.mjs','identity.mjs','git-query.mjs'
+ 'scope.mjs','store.mjs','git-evidence.mjs','assignment.mjs','verification.mjs','acceptance.mjs','external.mjs','schema.mjs','operations.mjs','gate.mjs','adapters/codex.mjs','adapters/claude.mjs','capabilities.mjs','identity.mjs','git-query.mjs','target-preparation.mjs'
 ]);
 export const cooperativeCoverage=()=>({enforcement:'cooperative',provenance:'operator-attested',nativeVerified:false});
 export function commandResult({workflowId,state,input,decision='allow',ruleId='cooperative.recorded',persisted=false,...extra}){
@@ -16,7 +16,7 @@ export async function cooperativeVersions(){
  const hash=bytes=>'sha256:'+crypto.createHash('sha256').update(bytes).digest('hex');
  let policy;try{policy=await fs.readFile(new URL('../policy/role-policy.json',import.meta.url));}catch(error){if(error.code!=='ENOENT')throw error;policy=await fs.readFile(new URL('./role-policy.json',import.meta.url));}
  const runtime=await Promise.all(COOPERATIVE_RUNTIME_MODULES.map(file=>fs.readFile(new URL(file,import.meta.url))));
- return {policy:'1',runtime:'cooperative-4',policyHash:hash(policy),runtimeHash:hash(Buffer.concat(runtime))};
+ return {policy:'1',runtime:'cooperative-6',policyHash:hash(policy),runtimeHash:hash(Buffer.concat(runtime))};
 }
 export async function initializeCooperativeWorkflow({cwd,workflowId,input,observe=observeCooperativeTarget,storage={}}){
  validateWorkflowId(workflowId);validateCooperativeCommand({command:'init',input});

package/codex/skill/runtime/cooperative-schema.mjs

@@ -2,6 +2,8 @@ import {ROLES} from './operations.mjs';
 import {assertSecretFree} from './external.mjs';
 import {object,text,validatePlannerLedger} from './schema.mjs';
 import {absolute,validateWorkflowId} from './scope.mjs';
+import path from 'node:path';
+import {validateTargetPreparationRecord} from './target-preparation.mjs';
 const fail=message=>{throw Error('Cooperative schema: '+message);};
 const hash=value=>typeof value==='string'&&/^sha256:[a-f0-9]{64}$/.test(value);
 const revision=value=>Number.isSafeInteger(value)&&value>=0;
@@ -9,6 +11,24 @@ const actor=value=>object(value)&&text(value.id)&&Object.keys(value).every(k=>['
 const statement=value=>object(value)&&text(value.messageRef)&&object(value.data);
 function fields(value,allowed){if(!object(value)||Object.keys(value).some(k=>!allowed.includes(k)))fail('unexpected input field');}
 function json(value){try{const encoded=JSON.stringify(value);if(encoded===undefined)fail('JSON input');}catch{fail('JSON input');}}
+const exact=(value,keys)=>object(value)&&Object.keys(value).length===keys.length&&keys.every(key=>Object.hasOwn(value,key));
+const oid=value=>typeof value==='string'&&/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value);
+const time=value=>typeof value==='string'&&Number.isFinite(Date.parse(value))&&/(?:Z|[+-]\d\d:\d\d)$/.test(value);
+const unique=value=>Array.isArray(value)&&new Set(value).size===value.length;
+const gitPath=value=>text(value)&&!/[\\\x00\r\n:]/.test(value)&&!value.startsWith('/')&&!value.split('/').some(part=>!part||part==='.'||part==='..');
+const ref=value=>text(value)&&/^refs\/[A-Za-z0-9][A-Za-z0-9._\/-]*$/.test(value)&&!value.includes('..')&&!value.includes('//')&&!value.endsWith('/')&&!value.endsWith('.')&&!value.endsWith('.lock');
+const approval=value=>exact(value,['ref','version','hash','approvedAt'])&&text(value.ref)&&Number.isSafeInteger(value.version)&&value.version>0&&hash(value.hash)&&time(value.approvedAt);
+const document=value=>exact(value,['version','hash','content'])&&Number.isSafeInteger(value.version)&&value.version>0&&hash(value.hash)&&typeof value.content==='string'&&Buffer.byteLength(value.content)<=1024*1024;
+export function validatePlanAmendArguments(a){
+ if(!exact(a,['classification','reason','changedAt','affectedTaskIds','plan','history','approvals','writers','ownership','publication','remotes','recovery'])||!['contract','mechanical'].includes(a.classification)||!text(a.reason)||!time(a.changedAt)||!unique(a.affectedTaskIds)||!a.affectedTaskIds.length||!a.affectedTaskIds.every(text))fail('plan-amend request');
+ if(!exact(a.plan,['path','gitPath','old','new'])||!absolute(a.plan.path)||!gitPath(a.plan.gitPath)||!document(a.plan.old)||!document(a.plan.new)||a.plan.new.version<=a.plan.old.version)fail('plan-amend document');
+ if(!exact(a.history,['base','planCommit','head','branch'])||![a.history.base,a.history.planCommit,a.history.head].every(oid)||!text(a.history.branch)||/[\x00\r\n]/.test(a.history.branch))fail('plan-amend history');
+ if(!exact(a.approvals,['original','amendment'])||!approval(a.approvals.original)||!(a.classification==='mechanical'&&a.approvals.amendment===null||approval(a.approvals.amendment)))fail('plan-amend approvals');
+ if(!Array.isArray(a.writers)||!a.writers.length||a.writers.some(w=>!exact(w,['assignmentId','stoppedAt','evidenceRef'])||!text(w.assignmentId)||!time(w.stoppedAt)||!text(w.evidenceRef))||!unique(a.writers.map(w=>w.assignmentId)))fail('plan-amend writers');
+ if(!['exclusive','shared','unknown'].includes(a.ownership)||!['unpublished','published','unknown'].includes(a.publication)||!Array.isArray(a.remotes)||a.remotes.some(r=>!exact(r,['name','identity','complete','refs','observedAt','evidenceRef'])||!text(r.name)||!hash(r.identity)||r.complete!==true||!time(r.observedAt)||!text(r.evidenceRef)||!Array.isArray(r.refs)||r.refs.some(x=>!exact(x,['name','oid'])||!ref(x.name)||!oid(x.oid))||!unique(r.refs.map(x=>x.name)))||!unique(a.remotes.map(r=>r.name)))fail('plan-amend remote snapshot');
+ if(!exact(a.recovery,['ref','oid'])||!ref(a.recovery.ref)||!a.recovery.ref.startsWith('refs/arc/recovery/')||!oid(a.recovery.oid)||path.normalize(a.plan.path)!==a.plan.path)fail('plan-amend recovery');
+ return a;
+}
 export function validateCooperativeCommand(command){
  assertSecretFree(command);fields(command,['command','input']);const {input,command:name}=command;
  if(!['init','record','status','reconcile','prepare','result'].includes(name))fail('command');
@@ -25,7 +45,7 @@ export function validateCooperativeCommand(command){
  if(name==='record'){
   fields(input.evidence,['kind','messageRef','data']);
   if(input.evidence?.data?.affectedTaskIds!==undefined&&(!Array.isArray(input.evidence.data.affectedTaskIds)||!input.evidence.data.affectedTaskIds.every(text)||new Set(input.evidence.data.affectedTaskIds).size!==input.evidence.data.affectedTaskIds.length))fail('affected task IDs');
-  if(!statement(input.evidence)||!['note','approval','external-approval','document','scope','check','finding','review','acceptance-evidence','planner-stage','planner-evidence','planner-result','planner-review'].includes(input.evidence.kind))fail('evidence');
+  if(!statement(input.evidence)||!['note','approval','external-approval','document','scope','check','finding','review','acceptance-evidence','planner-stage','planner-evidence','planner-result','planner-review','target-preparation'].includes(input.evidence.kind))fail('evidence');
  }
  if(resultStatement){
   fields(input.result,['status','messageRef','data','notExecutedEvidence']);
@@ -33,6 +53,7 @@ export function validateCooperativeCommand(command){
   if(input.result.status==='cancelled'&&(!object(input.result.notExecutedEvidence)||!text(input.result.notExecutedEvidence.messageRef)))fail('cancel requires not-executed evidence');
  }
  if((name==='prepare'||name==='result'&&!resultStatement)&&!text(input.operation))fail('operation');
+ if(name==='prepare'&&input.operation==='plan-amend')validatePlanAmendArguments(input.arguments);
  return command;
 }
 export function validateCooperativeState(state){
@@ -44,13 +65,23 @@ export function validateCooperativeState(state){
  for(const key of ['actors','selections','assignments','identities','leases','scopes','approvals','documents','tasks','requests','intents','results','checks','findings','acceptances','commits','audit','unresolved','records','targetHistory'])if(!Array.isArray(state[key]))fail(key);
  if(state.tasks.some(t=>!object(t)||!text(t.id)||!Array.isArray(t.paths)||!Array.isArray(t.criteria)||!Array.isArray(t.requiredChecks)||!Array.isArray(t.dependencies))||new Set(state.tasks.map(t=>t.id)).size!==state.tasks.length)fail('task contracts');
  if(state.commitObservations!==undefined&&(!Array.isArray(state.commitObservations)||state.commitObservations.some(o=>!object(o)||o.source!=='local-git'||!text(o.intentId)||!revision(o.revision))))fail('commit observations');
+ if(state.planAmendObservations!==undefined&&(!Array.isArray(state.planAmendObservations)||state.planAmendObservations.some(o=>!object(o)||o.source!=='local-git'||!text(o.intentId)||!revision(o.revision))))fail('plan-amend observations');
+ if(state.planAmendments!==undefined&&(!Array.isArray(state.planAmendments)||state.planAmendments.some(a=>!object(a)||a.source!=='operator-attested'||a.observationSource!=='local-git'||!text(a.intentId)||!absolute(a.path)||!hash(a.oldHash)||!hash(a.newHash)||!oid(a.oldCommit)||!oid(a.newCommit)||!Array.isArray(a.mapping)||!a.mapping.length)))fail('plan-amend connections');
  if(!revision(state.scopeVersion)||!revision(state.targetVersion))fail('scope/target version');
  if(state.actors.some(a=>!actor(a.actor)||a.source!=='operator-attested')||state.selections.some(s=>s.source!=='operator-attested'||!text(s.messageRef)))fail('attestations');
  for(const key of ['scopes','approvals','documents','checks','findings','acceptances','commits'])if(state[key].some(entry=>!object(entry)||entry.source!=='operator-attested'))fail('attestation source');
  if(state.records.some(r=>!actor(r.actor)||r.source!=='operator-attested'||!text(r.kind)||!statement(r)))fail('records');
  if(state.requests.some(r=>!text(r.requestId)||!hash(r.requestFingerprint)||!object(r.decision))||new Set(state.requests.map(r=>r.requestId)).size!==state.requests.length)fail('request replay');
  if(state.intents.some(i=>!text(i.requestId)||!['prepared','succeeded','failed','unknown','mismatch','cancelled'].includes(i.status)||!hash(i.fingerprint))||new Set(state.intents.map(i=>i.requestId)).size!==state.intents.length)fail('intents');
+ for(const intent of state.intents.filter(i=>i.operation==='plan-amend')){validatePlanAmendArguments(intent.arguments);if(!object(intent.target)||!object(intent.versions)||!object(intent.observation)||intent.source!=='operator-attested'||intent.checkpoint!==undefined&&!object(intent.checkpoint))fail('plan-amend intent');}
  if(state.results.some(r=>!text(r.requestId)||!['succeeded','failed','unknown','mismatch','cancelled'].includes(r.status)||r.source!=='operator-attested'||!object(r.data)))fail('results');
  if(state.plannerLedger!==undefined){validatePlannerLedger(state.plannerLedger);if(state.plannerLedger.stages.some(stage=>stage.workflowId!==state.workflowId||!Array.isArray(stage.artifacts)))fail('Planner workflow binding or artifacts');}
+ for(const key of ['targetIntents','targetCheckpoints','targetTransitions','targetDocuments'])if(state[key]!==undefined&&!Array.isArray(state[key]))fail(key);
+ const preparationIntents=state.targetIntents??[],checkpoints=state.targetCheckpoints??[],transitions=state.targetTransitions??[],documents=state.targetDocuments??[];
+ if(new Set(preparationIntents.map(i=>i.id)).size!==preparationIntents.length)fail('target intent identity');
+ for(const intent of preparationIntents){try{validateTargetPreparationRecord('intent',intent);}catch{fail('target intent');}const approved=state.records.find(r=>r.kind==='approval'&&r.messageRef===intent.approvalRef&&r.source==='operator-attested'&&r.actor?.role==='orchestrator'&&r.scopeVersion===intent.scopeVersion&&r.targetVersion===intent.sourceTargetVersion)?.data?.targetPreparation;if(intent.source!=='operator-attested'||intent.workflowId!==state.workflowId||!revision(intent.scopeVersion)||!hash(intent.sourceFingerprint)||!object(intent.sourceSnapshot)||!approved||['depth','selectionRef','kind','candidate','base','workflowId','firstStageId','sourceTargetVersion'].some(k=>approved[k]!==intent[k])||JSON.stringify(approved.sourceTarget)!==JSON.stringify(intent.sourceTarget)||JSON.stringify(approved.documents)!==JSON.stringify(intent.documents))fail('target intent provenance');}
+ for(const checkpoint of checkpoints){try{validateTargetPreparationRecord('checkpoint',{type:'checkpoint',...checkpoint});}catch{fail('target checkpoint');}if(checkpoint.source!=='operator-attested'||!text(checkpoint.messageRef)||!preparationIntents.some(i=>i.id===checkpoint.intentId&&i.firstStageId===checkpoint.stageId)||!state.records.some(r=>r.kind==='target-preparation'&&r.messageRef===checkpoint.messageRef&&r.source==='operator-attested'))fail('target checkpoint provenance');}
+ for(const transition of transitions){const request=transition.validation?.request;try{validateTargetPreparationRecord('transition',request);}catch{fail('target transition');}if(!object(transition.target)||!text(transition.messageRef)||!Number.isSafeInteger(transition.targetVersion)||transition.targetVersion!==transition.sourceTargetVersion+1||request.intentId!==transition.intentId||request.checkpointRef!==transition.checkpointRef||!preparationIntents.some(i=>i.id===transition.intentId)||!checkpoints.some(c=>c.intentId===transition.intentId&&c.messageRef===transition.checkpointRef)||!state.records.some(r=>r.kind==='target-preparation'&&r.messageRef===transition.messageRef&&r.source==='operator-attested'))fail('target transition provenance');}
+ for(const document of documents){try{validateTargetPreparationRecord('destination',document);}catch{fail('target document');}if(document.sourceLink!=='operator-attested'||document.verification?.status!=='verified'||document.verification?.source!=='local-bytes'||!text(document.messageRef)||!transitions.some(t=>t.intentId===document.intentId&&t.messageRef===document.transitionRef&&t.targetVersion===document.targetVersion)||!state.records.some(r=>r.kind==='target-preparation'&&r.messageRef===document.messageRef&&r.source==='operator-attested'))fail('target document provenance');}
  assertSecretFree(state);json(state);return state;
 }