@yunhozz/arc 0.2.0 → 0.2.2

package/codex/skill/references/planning.md

@@ -4,28 +4,23 @@ Read before design/plan-depth decisions, spec/plan drafting and approval, and th
 
 ## Authorization and scope
 
-An explicit execution request is authorization only for its sufficiently specified scope. Confirm execution intent,
+An explicit execution request authorizes only its sufficiently specified scope. Confirm execution intent,
 expected outcome, constraints, document depth, and verification risk, with no unresolved material behavior, method,
-or risk decision requiring the user. The request itself or a description explicitly referenced by the user must
-supply that scope. Record authorization evidence, scope, acceptance criteria, constraints, and depth in the brief or
-canonical record. Routine execution and check choices may be recorded by Orchestrator; added product behavior or
-material scope cannot be claimed as already approved. A restatement, role handoff, or restart does not create an
-approval requirement for the same scope.
+or risk decision requiring the user. That scope must come from the request or a description the user explicitly references. Record authorization evidence, scope, acceptance criteria, constraints, and depth in the brief or
+canonical record. Orchestrator may record routine execution and check choices; added product behavior or material scope is not already approved. Restating or handing off the same scope, or restarting, requires no new approval.
 
 Silence, ambiguous assent, approval of other work, and unspecified blanket improvement requests are not authorization.
 Planner's new material choices are not automatically approved. Ask for the missing material decision; roles route
 questions to Orchestrator. Required written specs and plans still require their individual approval in the order below.
 
-For material changes to scope, method, or risk, hold affected work and explain the missing decision or evidence and
-remaining work. Target changes, unclear ownership, unexpected state, unresolved failures, or missing required inputs
+Material scope, method, or risk changes hold affected work; explain the missing decision or evidence and remaining work. Target changes, unclear ownership, unexpected state, unresolved failures, or missing required inputs
 also hold affected work under [handoff](handoff.md) and [git-recovery](git-recovery.md). Distinguish new authorization
 needs from execution issues within existing scope: ordinary corrections and reverification do not require duplicate
 approval after failure. Revalidate affected gates after resolution.
 
 ### Probe scope
 
-A probe-only scope completes with findings, evidence, limits, and remaining uncertainty answering the approved question;
-a well-supported infeasibility result can complete it. Probe-only authorization does not authorize product retention
+A probe-only scope completes by answering the approved question with findings, evidence, limits, and remaining uncertainty; well-supported infeasibility can complete it. Probe-only authorization does not authorize product retention
 or subsequent implementation. Record question, method/scope, criteria, and constraints; a sufficiently specific probe
 request can supply that approval. Match checks to probe purpose/risk and do not report probe evidence as product proof.
 
@@ -38,41 +33,53 @@ remains separate.
 
 ## Formal drafting boundary
 
-Initial design proposals and brainstorming may precede execution-target choice. Formal spec or plan drafting includes a
-complete draft before saving, even when returned only in chat. Before formal drafting and saving, Orchestrator supplies
+Initial design proposals and brainstorming may precede execution-target choice. Formal spec or plan drafting includes a complete draft before saving, even when returned only in chat. Before formal drafting and saving, Orchestrator supplies
 and records the actual absolute workspace/repository, branch or detached HEAD, HEAD, changes and ownership,
 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.
+affected drafting or save and is reported to Orchestrator. Planned scope and paths do not prove actual preparation.
 Initial target preparation does not authorize Implementer; the complete handoff gate still applies.
 
 
 ## Planner drafting preparation and consolidated feedback
 
-Before formal drafting, Orchestrator performs a preflight of relevant policy, reference, profile, test, parity and
-manifest surfaces and conflicts. Provide one complete brief with actual absolute workspace/repository, branch or
-detached HEAD, HEAD, change state and ownership, explicit target choice and preparation evidence, approved preceding
-design/spec/plan versions, scope and exclusions, design/plan depth, dependencies and shared contracts, acceptance
-criteria, required QA/focused checks and evidence, hold conditions and open decisions. Resolve missing or conflicting
-required evidence first or hold that stage.
-
-Planner returns a complete proportional draft and self-review for the current approval stage. Orchestrator integrates,
-saves, reviews and obtains approval. Orchestrator checks once with a fixed checklist: scope and evidence; targets,
-ownership and paths; policy surfaces and conflicts; task boundaries, dependencies and acceptance criteria; checks,
-evidence and holds; roles, approval and commit boundaries; draft completeness. Gather all substantive omissions into
-one consolidated follow-up request to Planner. Do not split requests by omission or author the missing plan yourself.
-
-Initial design, required spec approval, and formal plan drafting/approval remain separate ordered stages.
-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.
+1. Before formal drafting, Orchestrator performs a preflight of relevant policy, reference, profile, test, parity
+   and manifest surfaces and conflicts. Apply the Formal drafting boundary above and coordination's instruction
+   provenance, input-state and local-skill rules, including required reference paths, authorized bounded read
+   alternatives and return conditions. Missing required inputs or unresolved conflicts hold dependent drafting;
+   Planner returns them to Orchestrator. Optional read recovery grants no preparation, verification, writing or
+   approval authority.
+
+2. Maintain a compact ledger of original requirements/criteria IDs, approved and open decisions, exclusions and
+   scope deltas; merge intervening user changes into one next-brief delta. Distinguish user-approved decisions,
+   verified source facts with exact paths and lines, assumptions and open decisions.
+
+3. Send one complete brief for the initial call of each stage, using coordination's shared fields and evidence-link
+   rules. Include the prepared workspace, branch or detached HEAD, HEAD and ownership; scope, exclusions, depth,
+   dependencies, shared contracts, acceptance criteria, required QA/focused checks, evidence and holds. Identify
+   preceding approved versions, document/output paths, current behavior and connected source, generated, runtime,
+   installer and documentation surfaces, policy conflicts and resolution direction, open decisions and the exact
+   stage deliverable. For visual work, include approved sources/versions, criteria and unresolved interpretations.
+
+4. Planner returns a complete proportional draft and self-review. Orchestrator integrates, saves, reviews and
+   obtains approval; never authors missing content. Review the complete draft once with this fixed checklist:
+   scope and evidence; targets, ownership and paths; policy surfaces and conflicts; task boundaries, dependencies
+   and acceptance criteria; checks, evidence and holds; roles, approval and commit boundaries; draft completeness.
+   Finish the checklist before sending all substantive omissions in one consolidated follow-up request.
+   Identify each criterion, defect, evidence and expected correction. Follow coordination's changed-fields-only
+   and `unchanged` rules. Do not split requests by omission.
+
+5. After that correction, additional Planner calls require user-approved material scope/evidence changes or
+   concrete unmet checklist items, plus meaningful new input or criterion-state progress. Identify changed input,
+   target criterion, expected artifact and expected progress. Distinguish approved scope changes from ordinary
+   omissions within existing scope; omissions require no renewed scope approval. If the same criterion remains
+   unmet without meaningful new input, evidence or progress, hold the stage and report the criterion, observed
+   evidence and exact unblock input or decision. Do not repeat resolved questions, reword the same request, or
+   count rewording or agent replacement as meaningful input or progress.
+
+Initial design, required spec approval, and formal plan drafting/approval remain separate ordered stages;
+written-spec approval precedes dependent plan drafting. No fixed call cap applies; never accept an incomplete draft
+to reduce calls or add call-count conditions to Planner profiles.
 
 ## Design and planning
 
@@ -127,7 +134,7 @@ approved obligations separately.
 When a Bounded written spec is required by Orchestrator's recorded plan-depth judgment, record that necessity and scope
 and use the approved short design as its basis. Planner returns a proportional complete spec draft and self-review;
 Orchestrator integrates, saves, self-reviews, and obtains individual written-spec approval before dependent plan
-drafting and execution preparation. This applies that judgment, not a new spec-necessity rule.
+drafting and execution preparation. This applies that judgment without adding a spec-necessity rule.
 
 Design, spec, plan, and brainstorming drafts are authored only by Planner.
 Orchestrator must not substitute an independently authored spec or plan for Planner's complete draft.
@@ -200,11 +207,9 @@ If evidence is missing or mismatched in either gate, stop the affected save and
 
 ### Complete planning-document set
 
-The applicable document set means all specs and plans required for the current approved execution scope, not future
-project work. Orchestrator records scope, design/plan depth, absolute document paths and coverage, approved
+The applicable document set covers all specs and plans required for the current approved execution scope, excluding future project work. Orchestrator records scope, design/plan depth, absolute document paths and coverage, approved
 versions/status, plan dependencies and execution order, skipped stages with rationale, and documents still awaiting writing or approval
-in the shared brief. The set is complete only when every required document is written and individually approved and
-no unresolved scope or dependency decision requires another document. Do not omit required documents from the list.
+in the shared brief. The set is complete only when every required document is written and individually approved, with no unresolved scope or dependency decision requiring another document. Do not omit required documents from the list.
 
 A required plan does not itself require a written spec. Bounded uses Orchestrator's recorded plan-depth judgment to
 determine whether a written spec is required; do not infer one from plan necessity. Spec steps apply only to Architectural and
@@ -219,9 +224,7 @@ Written-spec approval precedes dependent plan drafting. On document-omission pat
 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 Implementer,
-not the initial choice request. No early Implementer work is authorized by approval of only some documents.
+Select and initially prepare the target before formal drafting. Document completion gates staging/commit, not initial preparation. An incomplete set or missing applicable approval blocks document commit and Implementer, but 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
@@ -254,8 +257,7 @@ 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
+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
@@ -265,8 +267,7 @@ follow the document-version approval rules; classify typos, paths, commands and
 
 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.
+This history update does not backdate approval: the latest plan in the original commit does not prove 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
@@ -306,14 +307,18 @@ skill. Missing files stop the stage; report paths without global fallback. Keep
 
 
 
+## Instruction and Input Provenance
+
+Give the Planner the exact paths and access state for required skills and references, distinguish user-provided instructions from discovered files, and identify approved input versions and open questions. Criteria that use visual materials must link the approved source, version, access state, criterion IDs, and comparison method. Missing required inputs and unapproved interpretations hold dependent parts of the draft. Optional read alternatives must meet the pre-authorized conditions in [handoff](handoff.md#instruction-sources-bounded-read-recovery-visual-evidence-and-resumption). The Planner remains draft-only during recovery.
+
 [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: 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.significant-no-plan] For significant/high-risk work without a plan: Implementer → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. MUST NOT omit Reviewer because no plan exists. This creates no new plan obligation.
+- [review.significant-plan] For significant/high-risk plan work: each task uses Implementer → fresh QA as required → Orchestrator acceptance and focused commit. Reviewer reviews the final full change once after all tasks are accepted and required QA is complete. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.
 - [review.final-plan-recheck] For final overall Reviewer findings on plan work, including behavior findings, use Implementer → Reviewer without QA reassignment; repeat until resolved. This exception applies only at the final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.
 - [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.
+- [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. 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. Additional Planner 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 and report the criterion, observed evidence and exact unblock input or decision. Do not split omissions, repeat resolved items, or count rewording or agent replacement as progress. Preserve separate sequential design/spec/plan approvals; no fixed call cap, Planner-profile call-count conditions or incomplete draft acceptance.
 - [platform.codex] Role restrictions are prompt-level contracts, not a filesystem sandbox. No documented role-specific Git hook or generic per-agent tool allowlist is assumed. Existing shell capabilities are retained because static read access after shell reduction has not been verified; Implementer and QA need shell for approved checks.
 [ARC role policy: contract end]
 

package/codex/skill/references/verification.md

@@ -7,6 +7,12 @@ Visual companion design discussion is distinct from QA UI acceptance.
 
 For Orchestrator, **Evidence verdict**: each criterion is proven, unmet, or unverified; passing runs, reports, or disposition never turn unverified into proven; reports keep unverified scope visible.
 
+## Visual Evidence and Adjudication
+
+Each visual criterion requires the exact location, version, approval, and access state of the approved visual source; criterion IDs, properties, and comparison method; and evidence linking the actual output to its revision. An Implementer report does not replace fresh QA's direct comparison. Record results as pass, mismatch, or unverified and connect them to the existing proven/unmet/unverified criterion verdicts. Use pass only when accessible evidence meets the visual criterion; keep unsupported claims unverified. Missing output-to-revision linkage is unverified; a visible difference is a mismatch. Record these separately; do not infer the current branch UI state. Hold the comparison if the approved source or actual output is inaccessible or interpretation approval is missing.
+
+Static policy, generated-file, and manifest checks are structural evidence. They do not prove actual role behavior, an installed build, Claude Code CLI runtime compliance, or visual fidelity. Reports include actual changes, exclusion rationale, checks run and omitted, each criterion's evidence and limits, and platform availability. Keep baseline failures separate; progress on independent work does not relax required checks or acceptance criteria.
+
 ## Risk-scaled execution
 
 Orchestrator assigns edits exclusively to Implementer except under the Orchestrator direct path in [handoff](handoff.md#orchestrator-direct-path-for-small-tasks), and determines affected
@@ -75,8 +81,7 @@ satisfies. For small, low-risk work with clear scope and acceptance evidence and
 Orchestrator's focused checks suffice; do not call QA or Reviewer automatically. Significant/high-risk work requires
 independent review of the full change at the final relevant state after the required QA/focused checks and any QA recheck.
 
-Many known metadata files are not significant solely because there are many, and a one-file permission or data-loss
-rule may be. A vague request to delete unnecessary files does not establish low risk; reclassify when installer,
+Metadata file count alone does not imply significant risk; a one-file permission or data-loss rule may. A vague request to delete unnecessary files does not establish low risk; reclassify when installer,
 manifest, or other contracts are affected. For a verified ignore-pattern or metadata cleanup, confirm the targets are
 unused, required project materials are unaffected, ignore patterns cover only intended paths, and the diff matches the
 approved scope; Orchestrator's focused checks then suffice without automatically calling QA or Reviewer.
@@ -110,7 +115,7 @@ Structural checks establish written-contract alignment, not live agent complianc
 
 Task-local acceptance is distinct from overall final plan verification and acceptance. Orchestrator connects each task's
 acceptance criteria to actual evidence, currently required checks and findings before accepting it; checkbox
-completion, a Implementer report or passing commands alone do not establish acceptance.
+completion, an Implementer report or passing commands alone do not establish acceptance.
 
 Task acceptance and its focused commit require only the task's risk-scaled evidence: a FRESH QA instance per task that
 needs QA (default to the current QA for post-fix rechecks of the same task while the approved scope, workspace,
@@ -120,7 +125,7 @@ do not delay its acceptance/commit solely for later final plan verification. Cur
 be deferred to final verification to accept early. State the scope and timing of final-only integration criteria in
 the plan; with a plan, the required final whole-change review is final plan verification.
 
-A task commit record does not mark unperformed final verification complete. Orchestrator still decides final plan
+A task commit record does not prove unperformed final verification complete. Orchestrator still decides final plan
 acceptance using final QA/Reviewer/integration evidence and findings, preserving unverified scope and explicit dispositions.
 Valid evidence may cover both task and plan requirements only under the existing scope/state/independence/freshness/flow
 rules. For final Reviewer findings on already committed plan work, Orchestrator defines a follow-up task and required
@@ -154,8 +159,7 @@ unmet, or unverified. Passing a check alone does not prove a criterion: evidence
 expected result to actual observations. Preserve partial confirmation and out-of-scope, missing-check, or environment
 blocked gaps as unverified; omit no criteria. PASS, if used, means only run status and cannot replace criterion
 verdicts.
-Structural checks prove structural criteria only; they do not prove actual behavior, installation, or live agent runtime
-compliance.
+Structural checks prove only structural criteria, not actual behavior, installation, or live agent runtime compliance.
 
 For QA execution failure or an unmet criterion within the current task, Orchestrator defaults to the current Implementer
 for correction and the current QA for a post-fix recheck, subject to the context, task-boundary and amendment rules in
@@ -176,7 +180,7 @@ issues may require both QA verification and Reviewer source review.
 
 Orchestrator accepts using criterion verdicts, findings, recheck evidence, and remaining gaps, rather than an overall
 run result.
-Explicit disposition does not convert unverified to proven; completion reports preserve remaining unverified scope.
+Explicit disposition does not turn unverified into proven; completion reports preserve remaining unverified scope.
 For low-risk work without QA, Orchestrator's focused checks likewise connect each criterion to evidence.
 
 
@@ -188,8 +192,8 @@ Read brief-cited `references/superpowers/test-driven-development/SKILL.md`; reta
 Once applicable authorization, document-depth, execution-target, and handoff conditions hold for the approved scope,
 continue through execution, correction, reverification, required QA and Reviewer, findings disposition, Orchestrator
 acceptance, and the result report. Apply risk-scaled timing above; this adds no per-task Reviewer or new QA obligation.
-A role completion report, probe findings, or passing commands are not overall completion when approved work remains.
-Remaining approved execution is not an optional suggestion waiting for a user response. A probe-only scope
+Role reports, probe findings, or passing commands do not establish overall completion while approved work remains.
+Do not present remaining approved execution as an optional suggestion awaiting a user response. A probe-only scope
 ends at its approved question's evidence and limits; a combined scope continues under planning's scope rules.
 Document omission changes neither verification risk nor acceptance responsibility. Hold only affected work for an
 actual unmet condition and report what is needed to resume. Structural evidence does not prove live agent compliance.
@@ -225,7 +229,7 @@ This is an operator verdict record; it does not replace semantic proof of a crit
 Failures, unknown, mismatch and unverified outcomes are not passing evidence. Preserve previous results and failure records.
 
 A failed check/review leaves an open finding. Link a separate finding to an existing check/review through `record` with
-`data: {action: "open", id, checkId, message}`. After a Implementer fix, record
+`data: {action: "open", id, checkId, message}`. After an Implementer fix, record
 `data: {action: "resolve", id, actor: {id, role: "implementer"}, changeFingerprint}` and the fix evidence messageRef.
 The actor must be the Implementer assigned to that task, or a relevant task for an overall finding. This marks the finding resolved;
 it becomes closed only when a subsequent prepare includes it in `findingIds` and revalidation passes for the same change version.
@@ -277,8 +281,8 @@ A changed runtimeHash follows the existing stale/hold rules; the stored version
 [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: 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.significant-no-plan] For significant/high-risk work without a plan: Implementer → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. MUST NOT omit Reviewer because no plan exists. This creates no new plan obligation.
+- [review.significant-plan] For significant/high-risk plan work: each task uses Implementer → fresh QA as required → Orchestrator acceptance and focused commit. Reviewer reviews the final full change once after all tasks are accepted and required QA is complete. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.
 - [review.final-plan-recheck] For final overall Reviewer findings on plan work, including behavior findings, use Implementer → Reviewer without QA reassignment; repeat until resolved. This exception applies only at the final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.
 - [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.
 - [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.

package/codex/skill/references/visual-companion.md

@@ -13,9 +13,15 @@ acceptance. If declined, continue in text and do not offer again unless the user
 question whether to use the companion. Orchestrator owns its guide, server/browser, workspace paths, live-session
 checks, complete keyed URL, screens, session state, feedback/events, stale-screen clearing when returning to text, and
 cleanup. Check the server before showing a screen; after the user's reply, treat terminal text as primary and events as
-supplemental. A UI topic or accepted companion alone does not route every question through a browser.
+supplemental. A UI topic or companion acceptance alone does not route every question through a browser.
 
 
 Upstream guide/scripts: `<installed ARC>/references/superpowers/brainstorming/visual-companion.md` and adjacent `scripts/`.
 ARC guide: `references/visual-companion.md`; Orchestrator briefs absolute paths and retains approval/server/browser
 ownership. Missing files stop dependent work. MUST NOT use a global fallback.
+
+## Follow-up Verification of Approved Visual Sources
+
+Each visual criterion requires the exact location, version, approval, and access state of the approved visual source; criterion IDs, properties, and comparison method; and evidence linking the actual output to its revision. An Implementer report does not replace fresh QA's direct comparison. Record results as pass, mismatch, or unverified and connect them to the existing proven/unmet/unverified criterion verdicts. Use pass only when accessible evidence meets the visual criterion; keep unsupported claims unverified. Missing output-to-revision linkage is unverified; a visible difference is a mismatch. Record these separately; do not infer the current branch UI state. Hold the comparison if the approved source or actual output is inaccessible or interpretation approval is missing.
+
+Static policy, generated-file, and manifest checks are structural evidence. They do not prove actual role behavior, an installed build, Claude Code CLI runtime compliance, or visual fidelity. Reports include actual changes, exclusion rationale, checks run and omitted, each criterion's evidence and limits, and platform availability. Keep baseline failures separate; progress on independent work does not relax required checks or acceptance criteria.

package/lib/installer/manifest.mjs

@@ -25,7 +25,7 @@ export function verifyPayload({packageRoot,safeFs}){
   for(const item of FIXED)select(item,false);for(const item of ROOTS)select(item,true);
   for(const platform of ['codex','claude'])if(!referenceTrees[platform])throw Error('Required superpowers reference tree is missing');
   for(const name of listed.keys())if(!files.has(name))throw Error(`Manifest entry is missing: ${name}`);
-  const required=['claude/skill/hooks/role-git-guard.mjs','claude/skill/hooks/git-policy.json','lib/policy/claude-hook.mjs','lib/policy/role-policy.json','lib/policy/render.mjs','scripts/update-role-policy.mjs','lib/limits.mjs','lib/installer/limits.mjs','lib/installer/runtime-config.mjs','README.md','install.command','package.json','bin/arc.mjs','lib/cli/root.mjs','lib/tui/app.mjs','lib/tui/terminal.mjs','lib/tui/render.mjs','lib/tui/setup.mjs','lib/tui/workflow.mjs','lib/management/operations.mjs','lib/management/status.mjs','lib/management/update.mjs','lib/management/workflow.mjs','lib/cli/postinstall.mjs','scripts/postinstall.mjs','lib/cli/upgrade.mjs','bin/arc-upgrade.mjs','lib/installer/shell-completion.mjs','lib/installer/manifest.mjs','lib/installer/targets.mjs','lib/installer/global-config.mjs','lib/installer/plan.mjs','lib/safe-fs/index.mjs','lib/safe-fs/native.mjs','lib/models/index.mjs','lib/models/config.mjs','lib/models/profiles.mjs','vendor/toml/LICENSE','vendor/toml/package.json','vendor/toml/provenance.json','vendor/toml/dist/index.js','prebuilds/index.json'];
+  const required=['claude/skill/hooks/role-git-guard.mjs','claude/skill/hooks/git-policy.json','lib/policy/claude-hook.mjs','lib/policy/role-policy.json','lib/policy/render.mjs','scripts/update-role-policy.mjs','lib/limits.mjs','lib/installer/limits.mjs','lib/installer/runtime-config.mjs','README.md','install.command','package.json','bin/arc.mjs','lib/cli/root.mjs','lib/tui/app.mjs','lib/tui/terminal.mjs','lib/tui/render.mjs','lib/tui/setup.mjs','lib/management/operations.mjs','lib/management/status.mjs','lib/management/update.mjs','lib/management/workflow.mjs','lib/cli/postinstall.mjs','scripts/postinstall.mjs','lib/cli/upgrade.mjs','bin/arc-upgrade.mjs','lib/installer/shell-completion.mjs','lib/installer/manifest.mjs','lib/installer/targets.mjs','lib/installer/global-config.mjs','lib/installer/plan.mjs','lib/safe-fs/index.mjs','lib/safe-fs/native.mjs','lib/models/index.mjs','lib/models/config.mjs','lib/models/profiles.mjs','vendor/toml/LICENSE','vendor/toml/package.json','vendor/toml/provenance.json','vendor/toml/dist/index.js','prebuilds/index.json'];
   required.push('lib/installer/runtime-assets.mjs',...RUNTIME_MODULE_PATHS);
   for(const platform of ['codex','claude'])required.push(`${platform}/skill/runtime/role-policy.json`,...RUNTIME_MODULE_PATHS.map(name=>`${platform}/skill/runtime/${name.slice('lib/runtime/'.length)}`));
   for(const tuple of ['darwin-arm64','darwin-x64','linux-arm64-gnu','linux-x64-gnu'])required.push(`prebuilds/${tuple}/arc_safe_fs.node`);

package/lib/management/operations.mjs

@@ -9,6 +9,8 @@ import {buildPresetPlan,switchPresetTargets} from '../installer/preset.mjs';
 import {buildUninstallPlan,uninstallTargets} from '../installer/uninstall.mjs';
 import {installTargets} from '../installer/install.mjs';
 import {attachShellCompletionCleanup} from '../installer/shell-completion.mjs';
+import {inspectGlobalArc} from '../npm/context.mjs';
+import {uninstallGlobal,sameGlobalArc} from '../npm/uninstall.mjs';
 import {acquireExternalSkills} from '../installer/acquisition.mjs';
 /** @typedef {{packageRoot:string,userHome:string,cwd:string,env:object,safeFs:object,signal?:AbortSignal,acquisition?:Function}} ManagementContext */
 /** @typedef {{kind:string,plans:object[],options:object}} PreparedOperation */
@@ -25,7 +27,8 @@ export async function prepareOperation(context,options,{selections=[]}={}){
  if(options.kind==='install')attachShellCompletionCleanup(plans,context);
  // Uninstall plans initially share the completion snapshot; its executor assigns one owner.
  if(options.kind!=='uninstall')validatePlanSet(plans);
- return{kind:options.kind,plans,options:{...options}};
+ const globalArc=options.kind==='uninstall'?await(context.inspectGlobalArc??inspectGlobalArc)({env:context.env,cwd:context.cwd,runNpm:context.runNpm}):undefined;
+ return{kind:options.kind,plans,options:{...options},...(globalArc?{globalArc}:{})};
 }
 export function operationResult(result,successStatuses=['installed']){return{...result,code:result.interrupted?130:result.results.every(item=>successStatuses.includes(item.status)&&!item.error)?0:1,exitSession:false};}
 export function acquisitionFor(context){return context.acquisition??(async()=>{const work=fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()),'arc-acquire-'));let acquired;try{acquired=await acquireExternalSkills({work,safeFs:context.safeFs,signal:context.signal});}catch(error){if(!error.residualPaths?.length)try{fs.rmdirSync(work);}catch(cleanup){throw Object.assign(new AggregateError([error,cleanup],'Cannot clean private acquisition work'),{code:'ARC_ACQUISITION_CLEANUP',residualPaths:[work]});}throw error;}return{...acquired,dispose:async()=>{await acquired.dispose();fs.rmdirSync(work);}};});}
@@ -34,6 +37,16 @@ export async function executeOperation(context,prepared){
  const options={safeFs:context.safeFs,signal:context.signal,hooks:context.hooks};
  if(prepared.kind==='install')return operationResult(await installTargets(prepared.plans,{...options,acquisition:acquisitionFor(context)}));
  if(prepared.kind==='preset')return operationResult(await switchPresetTargets(prepared.plans,options),['updated','unchanged']);
- if(prepared.kind==='uninstall')return operationResult(await uninstallTargets(prepared.plans,options),['uninstalled']);
+ if(prepared.kind==='uninstall'){
+  let result;
+  try{
+   const current=await(context.inspectGlobalArc??inspectGlobalArc)({context:prepared.globalArc,env:context.env,cwd:context.cwd,runNpm:context.runNpm});
+   if(!sameGlobalArc(prepared.globalArc,current))throw Error('Global ARC installation changed; prepare uninstall again');
+   result=operationResult(await uninstallTargets(prepared.plans,options),['uninstalled']);
+   if(result.code!==0||context.signal?.aborted)return{...result,code:context.signal?.aborted?130:result.code,cli:{status:'skipped'}};
+   const cli=await(context.uninstallGlobal??uninstallGlobal)({context:prepared.globalArc,env:context.env,cwd:context.cwd,signal:context.signal,runNpm:context.runNpm});
+   return{...result,code:cli.code??(cli.packageStatus==='failed'?1:0),interrupted:result.interrupted||Boolean(cli.interrupted),exitSession:Boolean(cli.started),cli:{...cli,status:cli.packageStatus},stdout:cli.stdout,stderr:cli.stderr};
+  }catch(error){return{...(result??{results:[],interrupted:false}),code:context.signal?.aborted?130:1,exitSession:false,cli:{status:'skipped'},error};}
+ }
  throw Object.assign(Error('Unknown prepared operation'),{code:'ARC_CLI_INPUT'});
 }

package/lib/management/update.mjs

@@ -15,7 +15,7 @@ export function report(result,output,error){
  for(const item of result.results){output.write(item.platform+': '+item.status+'; rollback: '+item.rollback+'\n');for(const filename of item.residualPaths??[])output.write('Residual path: '+filename+'\n');if(item.error)error.write('Error: '+item.error.message+'\n');}
  if(result.interrupted)return 130;
  if(result.results.every(item=>item.status==='installed'&&!item.error)){output.write('ARC version '+result.version+' harness upgraded! Previous harness version: not recorded.\n');return 0;}
- error.write('Harness update did not complete. Run arc again and choose Update Harness, or run npx --yes @yunhozz/arc@latest and choose Update Harness.\n');return 1;
+ error.write('Harness update did not complete. Run arc again and choose Install / Update to retry the harness update.\n');return 1;
 }
 export function failure(cause,error){error.write('Error: '+cause.message+'\n');return ['ARC_CANCELLED','ARC_NPM_CANCELLED'].includes(cause.code)?130:['ARC_CLI_INPUT','ARC_TARGET_CONFIGURATION','ARC_UNSUPPORTED_RUNTIME','ARC_NATIVE_UNAVAILABLE'].includes(cause.code)?2:1;}
 export async function runChild(request,io={},deps={}){
@@ -36,23 +36,32 @@ export async function prepareUpdate(context){
  const root=context.packageRoot??packageRoot,pkg=identity(root),api=await runtime(context),cwd=fs.realpathSync(context.cwd??process.cwd()),env=context.env??process.env;
  const state=api.collectInstalledState({safeFs:api.safeFs,userHome:context.userHome??os.homedir(),env,cwd});
  if(!state.targets.length)throw configurationError('No installed ARC harness found. Run npx --yes @yunhozz/arc to install it first');
- let plans,version;
- if(!context.upgradeInstalledTargets){const[{verifyPayload},{buildUpgradePlans}]=await Promise.all([import('../installer/manifest.mjs'),import('../installer/upgrade.mjs')]);const payload=verifyPayload({packageRoot:root,safeFs:api.safeFs});plans=buildUpgradePlans({payload,state,safeFs:api.safeFs});version=JSON.parse(payload.files.get('package.json')).version;}
- return{kind:'update',root,pkg,cwd,env,state,plans,version};
+ const npmContext=await api.inspectNpmContext({packageRoot:root,entryPath:path.join(root,'bin/arc.mjs'),env,cwd});
+ if(!['global','npx'].includes(npmContext.kind))throw configurationError('Run arc from a verified global ARC installation or npx');
+ let latestVersion=null,latestError;
+ try{const latest=await api.resolveLatest({context:npmContext,env,cwd,signal:context.signal});if(!/^\d+\.\d+\.\d+$/.test(latest.version))throw Error('Invalid latest ARC version');latestVersion=latest.version;}catch(error){if(['ARC_CANCELLED','ARC_NPM_CANCELLED'].includes(error.code))throw error;latestError=error;}
+ return{kind:'update',root,pkg,cwd,env,state,npmContext,currentVersion:pkg.version,latestVersion,canUpgrade:latestVersion!==null&&newer(latestVersion,pkg.version),latestError};
 }
+function newer(left,right){const a=left.split('.').map(BigInt),b=right.split('.').map(BigInt);for(let i=0;i<3;i++){if(a[i]!==b[i])return a[i]>b[i];}return false;}
+
 export async function executeUpdate(context,prepared){
  let packageStarted=false;const messages=[];try{
   const api=await runtime(context),{root,pkg,cwd,env,state}=prepared;
+  if(!prepared.canUpgrade||typeof prepared.latestVersion!=='string'||!/^\d+\.\d+\.\d+$/.test(prepared.latestVersion)||!newer(prepared.latestVersion,prepared.currentVersion))throw configurationError('No newer ARC version is available');
+  if(identity(root).version!==pkg.version||pkg.version!==prepared.currentVersion)throw configurationError('ARC package changed after checking its version');
   const{assertPlanSnapshot}=await import('../installer/transaction.mjs');for(const entry of state.targets)assertPlanSnapshot(entry,{safeFs:api.safeFs});
+  const currentState=api.collectInstalledState({safeFs:api.safeFs,userHome:context.userHome??os.homedir(),env,cwd});if(currentState.stateToken!==state.stateToken)throw configurationError('Installed ARC settings changed; check the version again');
   const npmContext=await api.inspectNpmContext({packageRoot:root,entryPath:path.join(root,'bin/arc.mjs'),env,cwd});
-  if(!['global','npx'].includes(npmContext.kind))throw configurationError('Run arc from a verified global ARC installation or npx --yes @yunhozz/arc@latest, then choose Update Harness');
+  if(!['global','npx'].includes(npmContext.kind)||['kind','packageRoot','entryPath','npmCli','prefix'].some(key=>npmContext[key]!==prepared.npmContext[key]))throw configurationError('ARC npm context changed; check the version again');
+  const expectedVersion=prepared.latestVersion;
   if(npmContext.kind==='npx'){
-   let result;if(prepared.plans){const[{installTargets},{acquisitionFor,operationResult}]=await Promise.all([import('../installer/install.mjs'),import('./operations.mjs')]);result=operationResult({version:prepared.version,...await installTargets(prepared.plans,{safeFs:api.safeFs,signal:context.signal,acquisition:acquisitionFor({...context,safeFs:api.safeFs})})});}else{const{operationResult}=await import('./operations.mjs');result=operationResult(await api.upgradeInstalledTargets({packageRoot:root,state,safeFs:api.safeFs,signal:context.signal}));}return result;
+   const child=await api.runNpxUpgrade({context:npmContext,expectedVersion,expectedStateToken:state.stateToken,env,cwd,signal:context.signal});
+   return{...child,code:child.code===0&&!child.signal?0:child.code===130?130:1,exitSession:false,results:[],messages};
   }
-  const latest=await api.resolveLatest({context:npmContext,env,cwd,signal:context.signal});packageStarted=true;
-  const replaced=await api.upgradeGlobal({context:npmContext,expectedVersion:latest.version,env,cwd,signal:context.signal});if(replaced.packageStatus!=='updated')throw replaced.error??Error('CLI replacement failed');
-  messages.push('CLI: updated to '+latest.version+' (previous '+pkg.version+').\n');
-  const child=await api.runUpgradeChild({entryPath:path.join(npmContext.packageRoot,'bin/arc-upgrade.mjs'),request:{protocol:1,expectedVersion:latest.version,invocationCwd:cwd,expectedStateToken:state.stateToken},env,cwd,signal:context.signal});
+  packageStarted=true;
+  const replaced=await api.upgradeGlobal({context:npmContext,expectedVersion,env,cwd,signal:context.signal});if(replaced.packageStatus!=='updated')throw replaced.error??Error('CLI replacement failed');
+  messages.push('CLI: updated to '+expectedVersion+' (previous '+pkg.version+').\n');
+  const child=await api.runUpgradeChild({entryPath:path.join(npmContext.packageRoot,'bin/arc-upgrade.mjs'),request:{protocol:1,expectedVersion,invocationCwd:cwd,expectedStateToken:state.stateToken},env,cwd,signal:context.signal});
   return{...child,code:child.code===0&&!child.signal?0:child.code===130?130:1,exitSession:true,results:[],messages};
  }catch(error){return{code:['ARC_CANCELLED','ARC_NPM_CANCELLED'].includes(error.code)?130:['ARC_CLI_INPUT','ARC_TARGET_CONFIGURATION','ARC_UNSUPPORTED_RUNTIME','ARC_NATIVE_UNAVAILABLE'].includes(error.code)?2:1,exitSession:packageStarted,results:[],error,messages};}
 }

package/lib/npm/context.mjs

@@ -34,3 +34,25 @@ export async function inspectNpmContext({packageRoot,entryPath,env=process.env,c
   return unsupported('ARC is not in a verified global or npm exec installation');
  }catch{return unsupported('Cannot verify npm installation context');}
 }
+
+// Global absence is a filesystem fact. Identity and context failures must throw,
+// because treating them as absence could allow harness removal before validation.
+export async function inspectGlobalArc({context,env=process.env,cwd=process.cwd(),runNpm=defaultRunNpm}={}){
+ const fail=message=>Object.assign(Error(message),{code:'ARC_TARGET_CONFIGURATION'}),npmCli=npmExecutable(env);
+ if(context?.npmCli&&context.npmCli!==npmCli)throw fail('Global ARC npm context changed');
+ async function query(args){const result=await runNpm(npmCli,args,{env,cwd});if(result.code!==0||result.signal)throw fail('Cannot verify global npm context');const value=result.stdout.trim();if(!path.isAbsolute(value)||value.includes('\n'))throw fail('Invalid global npm context path');return path.resolve(value);}
+ const queriedPrefix=await query(['prefix','--global']),queriedRoot=await query(['root','--global']);
+ let prefix;try{prefix=realDirectory(queriedPrefix);}catch(error){if(error.code!=='ENOENT')throw error;prefix=queriedPrefix;}
+ if(![path.join(queriedPrefix,'lib/node_modules'),path.join(queriedPrefix,'node_modules')].includes(queriedRoot))throw fail('Unverified global npm root');
+ const root=path.join(prefix,path.relative(queriedPrefix,queriedRoot)),packageRoot=path.join(root,'@yunhozz/arc');
+ for(const relative of [path.relative(prefix,root),'@yunhozz','arc']){
+  // Check each component, including lib/node_modules, without following links.
+  const base=relative==='@yunhozz'?root:relative==='arc'?path.join(root,'@yunhozz'):prefix;
+  let current=base;for(const part of relative.split(path.sep)){current=path.join(current,part);let stat;try{stat=fs.lstatSync(current);}catch(error){if(error.code==='ENOENT')return{kind:'absent'};throw error;}if(stat.isSymbolicLink()||!stat.isDirectory())throw fail('Global ARC directory identity is invalid or symlinked');}
+ }
+ const filename=path.join(packageRoot,'package.json');if(!fs.lstatSync(filename).isFile()||fs.lstatSync(filename).isSymbolicLink())throw fail('Invalid global ARC package identity');
+ let pkg;try{pkg=JSON.parse(fs.readFileSync(filename,'utf8'));}catch{throw fail('Invalid global ARC package identity');}
+ if(pkg.name!=='@yunhozz/arc'||!/^\d+\.\d+\.\d+$/.test(pkg.version))throw fail('Invalid global ARC package identity');
+ const{createHash}=await import('node:crypto'),stat=fs.lstatSync(packageRoot),packageToken=createHash('sha256').update(fs.readFileSync(filename)).update(String(stat.dev)+':'+String(stat.ino)).digest('hex');
+ return{kind:'global',npmCli,prefix,packageRoot,version:pkg.version,packageToken};
+}

package/lib/npm/uninstall.mjs

@@ -0,0 +1,17 @@
+import {inspectGlobalArc} from './context.mjs';
+import {runNpm as defaultRunNpm} from './process.mjs';
+export function sameGlobalArc(left,right){return['kind','npmCli','prefix','packageRoot','version','packageToken'].every(key=>left?.[key]===right?.[key]);}
+export async function uninstallGlobal({context,env=process.env,cwd=process.cwd(),signal,runNpm=defaultRunNpm}){
+ let started=false,result;
+ try{
+  const current=await inspectGlobalArc({context,env,cwd,runNpm});
+  if(!sameGlobalArc(context,current))throw Object.assign(Error('Global ARC installation changed; prepare uninstall again'),{code:'ARC_TARGET_CONFIGURATION'});
+  if(signal?.aborted)throw Object.assign(Error('Uninstall interrupted'),{code:'ARC_NPM_CANCELLED'});
+  if(current.kind==='absent')return{packageStatus:'absent',code:0,started:false,stdout:'',stderr:''};
+  started=true;
+  result=await runNpm(current.npmCli,['uninstall','--global','@yunhozz/arc','--prefix',current.prefix,'--ignore-scripts'],{env,cwd,signal});
+  if(result.code!==0||result.signal)throw Error('Global CLI removal failed; the package may have changed');
+  if((await inspectGlobalArc({context:current,env,cwd,runNpm})).kind!=='absent')throw Error('Global ARC remains after npm uninstall');
+  return{...result,packageStatus:'removed',started};
+ }catch(error){const interrupted=['ARC_CANCELLED','ARC_NPM_CANCELLED'].includes(error.code)||Boolean(signal?.aborted);return{...result,packageStatus:'failed',code:interrupted?130:result?.code||1,interrupted,started,error};}
+}

package/lib/npm/upgrade.mjs

@@ -27,3 +27,28 @@ export async function runUpgradeChild({entryPath,request,env,cwd,signal}){
   child.stdin.end(JSON.stringify(request));
  });
 }
+// Resolve the npm-exec payload from its own bin, then use only that payload's
+// verified management runtime. The global-only private child is not reused.
+export async function runNpxUpgrade({context,expectedVersion,expectedStateToken,env,cwd,signal,runNpm=defaultRunNpm}){
+ if(context.kind!=='npx'||!validVersion(expectedVersion)||typeof expectedStateToken!=='string'||!/^[a-f0-9]{64}$/.test(expectedStateToken))throw Error('Invalid pinned npx upgrade request');
+ if(signal?.aborted)throw cancelled();
+ const bootstrap=`import fs from 'node:fs';import path from 'node:path';import os from 'node:os';import {pathToFileURL} from 'node:url';
+ try{
+  const expectedVersion=${JSON.stringify(expectedVersion)},expectedStateToken=${JSON.stringify(expectedStateToken)},cwd=${JSON.stringify(cwd)};
+  const bin=process.env.PATH.split(path.delimiter).map(p=>path.join(p,'arc')).find(p=>fs.existsSync(p));
+  if(!bin)throw Error('Cannot locate pinned ARC payload');
+  const entry=fs.realpathSync(bin),root=path.dirname(path.dirname(entry)),pkg=JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8'));
+  if(pkg.name!=='@yunhozz/arc'||pkg.version!==expectedVersion||entry!==path.join(root,'bin/arc.mjs'))throw Error('Pinned ARC package identity mismatch');
+  const management=await import(pathToFileURL(path.join(root,'lib/management/update.mjs')));
+  if(typeof management.runtime!=='function'||typeof management.report!=='function')throw Error('Pinned ARC management runtime is unavailable');
+  const api=await management.runtime({});
+  if(typeof api.inspectNpmContext!=='function'||typeof api.collectInstalledState!=='function'||typeof api.upgradeInstalledTargets!=='function')throw Error('Pinned ARC management API is unavailable');
+  const context=await api.inspectNpmContext({packageRoot:root,entryPath:entry,env:process.env,cwd});
+  if(context.kind!=='npx'||context.packageRoot!==root)throw Error('Cannot verify pinned npm exec context');
+  const state=api.collectInstalledState({safeFs:api.safeFs,userHome:os.homedir(),env:process.env,cwd});
+  if(state.stateToken!==expectedStateToken||!state.targets.length)throw Error('Installed ARC settings changed before pinned upgrade');
+  const controller=new AbortController(),abort=()=>controller.abort();process.once('SIGINT',abort);process.once('SIGTERM',abort);
+  try{process.exitCode=management.report(await api.upgradeInstalledTargets({packageRoot:root,state,safeFs:api.safeFs,signal:controller.signal}),process.stdout,process.stderr);}finally{process.removeListener('SIGINT',abort);process.removeListener('SIGTERM',abort);}
+ }catch(error){console.error('Error: '+error.message);process.exitCode=2;}`;
+ return runNpm(context.npmCli,['exec','--yes','--package','@yunhozz/arc@'+expectedVersion,'--',process.execPath,'--input-type=module','-e',bootstrap],{env,cwd,signal});
+}