@yunhozz/arc 0.0.0-stage → 0.1.1

package/claude/skill/hooks/role-git-guard.mjs

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import {pathToFileURL} from 'node:url';
+
+const deny = reason => ({allowed:false,reason});
+const isGit = word => /(?:^|[\\/])git(?:\.exe)?$/i.test(word);
+export function validateGitPolicy(policy) {
+  if (!policy || policy.schemaVersion !== 1 || !Array.isArray(policy.globalValueOptions) || !Array.isArray(policy.globalFlags) || !policy.commands || typeof policy.commands !== 'object' || Array.isArray(policy.commands)) throw Error('Invalid Git policy');
+  const strings = list => Array.isArray(list) && list.every(x=>typeof x === 'string' && x.startsWith('-'));
+  if (!strings(policy.globalValueOptions) || !strings(policy.globalFlags) || !Object.keys(policy.commands).length) throw Error('Invalid Git policy');
+  for (const rule of Object.values(policy.commands)) if (!rule || !strings(rule.flags) || !strings(rule.values) || !['any','none','query','list'].includes(rule.positionals)) throw Error('Invalid Git command policy');
+  return policy;
+}
+// This deliberately supports a small shell grammar, rather than executing a shell.
+function tokenize(command) {
+  const tokens=[]; let word='', started=false, quote=null;
+  for(let i=0;i<command.length;i++) {
+    const char=command[i];
+    if(char==='\\' && /[\r\n]/.test(command[i+1]??'')) throw Error('Escaped line terminator');
+    if(quote) {
+      if(char===quote){quote=null;continue;}
+      if(quote==='"' && /[$`]/.test(char)) throw Error('Dynamic shell syntax');
+      // Preserve Windows paths in quoted executable names.
+      if(char==='\\' && quote==='"' && /["\\$`]/.test(command[i+1]??'')){word+=command[++i];continue;}
+      word+=char;continue;
+    }
+    if(char==='"'||char==="'"){quote=char;started=true;continue;}
+    if(/[\r\n\x00<>`$(){}&]/.test(char) && !(char==='&'&&command[i+1]==='&')) throw Error('Unsupported shell syntax');
+    if(char===';'||char==='|'||char==='&') {
+      if(started){tokens.push(word);word='';started=false;}
+      const operator=command.slice(i,i+2); if(operator==='&&'||operator==='||')i++;
+      tokens.push({operator:operator==='&&'||operator==='||'?operator:char});continue;
+    }
+    if(/\s/.test(char)){if(started){tokens.push(word);word='';started=false;}continue;}
+    if(char==='\\') {if(i+1>=command.length)throw Error('Incomplete escape'); word+=command[++i];started=true;continue;}
+    if(char==='#')throw Error('Unsupported shell comment');
+    word+=char;started=true;
+  }
+  if(quote)throw Error('Unclosed quote'); if(started)tokens.push(word);return tokens;
+}
+function classifyWords(words,policy,depth) {
+  if(!words.length)return deny('Empty shell segment');
+  const executable=words[0].split(/[\\/]/).at(-1).toLowerCase();
+  if(['sh','bash','sh.exe','bash.exe'].includes(executable)) {
+    if(depth>=4 || words.length!==3 || words[1]!=='-c')return deny('Unsupported shell wrapper');
+    return classifyGitCommand(words[2],policy,depth+1);
+  }
+  if(!isGit(words[0]))return words.some(isGit)?deny('Unsupported indirect Git invocation'):{allowed:true};
+  let i=1;
+  while(i<words.length && words[i].startsWith('-')) {
+    const option=words[i++],equal=option.indexOf('='),key=equal<0?option:option.slice(0,equal);
+    if(policy.globalFlags.includes(option))continue;
+    if(!policy.globalValueOptions.includes(key))return deny('Unknown Git global option');
+    if(equal<0 && (i>=words.length || words[i++].startsWith('-')))return deny('Missing Git option value');
+    if(equal>=0 && !option.slice(equal+1))return deny('Missing Git option value');
+  }
+  const combined=`${words[i]} ${words[i+1]}`;
+  const name=Object.hasOwn(policy.commands,combined)?(i+=2,combined):words[i++];
+  const rule=Object.hasOwn(policy.commands,name)?policy.commands[name]:null; if(!rule)return deny('Git mutation or unknown subcommand');
+  let positions=0,query=false,list=false,paths=false;
+  for(;i<words.length;i++) {
+    const arg=words[i];
+    if(arg==='--' && rule.positionals==='any'){paths=true;continue;}
+    if(!paths && arg.startsWith('-')) {
+      if(/^-[0-9]+$/.test(arg)&&rule.flags.includes('-<count>'))continue;
+      const equal=arg.indexOf('='),key=equal<0?arg:arg.slice(0,equal);
+      if(rule.values.includes(key)) {if(equal<0 && (i+1>=words.length||words[++i].startsWith('-')))return deny('Missing query option value'); if(equal>=0&&!arg.slice(equal+1))return deny('Missing query option value');continue;}
+      if(!rule.flags.includes(arg))return deny('Unknown or mutating Git option');
+      if(['--get','--get-all','--get-regexp','--list','-l'].includes(arg))query=true;
+      if(['--list','-l','--show-current'].includes(arg))list=true;
+    } else positions++;
+  }
+  if(rule.positionals==='none'&&positions || rule.positionals==='query'&&(!query||positions>1) || rule.positionals==='list'&&positions&&!list)return deny('Git write or unsupported arguments');
+  return {allowed:true};
+}
+export function classifyGitCommand(command,policy,depth=0) {
+  try {
+    validateGitPolicy(policy);
+    if(typeof command!=='string'||!command.trim())return deny('Missing shell command');
+    const tokens=tokenize(command); let words=[];
+    for(const token of [...tokens,{operator:'end'}]) {
+      if(typeof token==='string'){words.push(token);continue;}
+      const result=classifyWords(words,policy,depth);if(!result.allowed)return result;words=[];
+    }
+    return {allowed:true};
+  } catch {return deny('Invalid policy or unsupported command syntax');}
+}
+export function evaluateHookEvent(event,policy) {
+  const result=event?.hook_event_name!=='PreToolUse' ? deny('Invalid hook event') : event?.tool_name!=='Bash' ? deny('Missing Bash event') : classifyGitCommand(event?.tool_input?.command,policy);
+  return result.allowed?{}:{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:`ARC specialist Git guard: ${result.reason}. Return the operation to Orchestrator.`}};
+}
+export function runHook() {
+  let response;
+  try {const policy=validateGitPolicy(JSON.parse(fs.readFileSync(new URL('./git-policy.json',import.meta.url),'utf8')));response=evaluateHookEvent(JSON.parse(fs.readFileSync(0,'utf8')),policy);}
+  catch {response={hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:'ARC specialist Git guard: invalid input or policy asset. Stop and report to Orchestrator.'}};}
+  process.stdout.write(JSON.stringify(response)+'\n');
+}
+
+if(process.argv[1] && pathToFileURL(process.argv[1]).href===import.meta.url)runHook();

package/claude/skill/models.toml

@@ -0,0 +1,64 @@
+# Single source for all role model and effort presets.
+# Use configured settings without substitution; report unavailable settings.
+version = 1
+preset = "balanced"
+
+[roles.arc_scouter.economy]
+model = "haiku"
+effort = "high"
+
+[roles.arc_scouter.balanced]
+model = "sonnet"
+effort = "medium"
+
+[roles.arc_scouter.smart]
+model = "sonnet"
+effort = "high"
+
+[roles.arc_planner.economy]
+model = "sonnet"
+effort = "medium"
+
+[roles.arc_planner.balanced]
+model = "sonnet"
+effort = "high"
+
+[roles.arc_planner.smart]
+model = "opus"
+effort = "high"
+
+[roles.arc_coder.economy]
+model = "sonnet"
+effort = "low"
+
+[roles.arc_coder.balanced]
+model = "sonnet"
+effort = "medium"
+
+[roles.arc_coder.smart]
+model = "opus"
+effort = "high"
+
+[roles.arc_qa.economy]
+model = "haiku"
+effort = "high"
+
+[roles.arc_qa.balanced]
+model = "sonnet"
+effort = "medium"
+
+[roles.arc_qa.smart]
+model = "sonnet"
+effort = "high"
+
+[roles.arc_reviewer.economy]
+model = "sonnet"
+effort = "medium"
+
+[roles.arc_reviewer.balanced]
+model = "sonnet"
+effort = "high"
+
+[roles.arc_reviewer.smart]
+model = "opus"
+effort = "high"

package/claude/skill/references/commit.md

@@ -0,0 +1,77 @@
+# Focused commits
+
+Orchestrator reviews task evidence and accepts the approved task before committing.
+Verify approved plan/task, absolute workspace, branch/HEAD, index/worktree/untracked state and ownership.
+Stage exactly the accepted task paths; inspect staged scope and content to exclude unrelated changes.
+After acceptance, Orchestrator creates the focused local commit without additional user commit approval.
+After Orchestrator accepts a task, the next action is the required Git state/scope checks, staging, and focused commit.
+Do not commit before task acceptance or defer the task commit until the plan ends.
+Only Orchestrator accepts the task and executes its focused commit; Coder completion does not replace acceptance.
+Existing plan-skip paths have no new automatic commit obligation; their commits follow applicable guidance and user requests.
+Commit one logical task promptly, using Conventional Commits with a concise English description.
+Task acceptance/commit is distinct from final plan acceptance; remaining final checks and Reviewer timing follow verification.
+Planning documents have their own batch docs commit before Coder handoff.
+
+After commit, verify exact SHA, subject, included paths, branch/HEAD and remaining index/worktree state.
+Preserve unrelated changes; never automatically unstage, amend, reset, clean, stash, or delete branches.
+On failure stop dependent work and report actual state and completed steps. Do not blindly repeat a commit or staging
+command. Push, publication and merge require user authorization. Coder must not commit, even when explicitly assigned.
+
+Hold the task commit for unmet or unresolved criteria, failed or not-run required checks, undispositioned findings or
+evidence gaps, scope expansion, ownership or staged scope/content mismatch, unexpected workspace/branch/HEAD/Git state,
+or Git failure/partial completion; record the reason and next action. Never waive unmet criteria or required checks to
+commit. If commit creation is unclear, stop and inspect before any retry (see git-recovery).
+
+For a no-change task make no empty commit; record acceptance evidence and no change.
+On resume verify the same task's existing commit SHA, content, and validity and reuse it; never duplicate a successful
+task commit. For final Reviewer findings on already committed plan work, Orchestrator defines a follow-up task and required
+planning/approvals. Coder leaves corrections uncommitted during rechecks. Orchestrator refreshes the latest committed
+state plus uncommitted diff and changed-file list in the Reviewer artifact/brief. Reuse an independent Reviewer or
+assign another independent Reviewer as needed. Repeat Coder → Reviewer without QA reassignment until findings are
+resolved; Orchestrator then accepts the corrections and creates one focused follow-up commit.
+Final QA findings retain Coder correction and QA recheck before a new focused commit.
+Do not automatically amend/reset or duplicate the original task commit. Scope expansion keeps existing new
+planning and approval obligations.
+
+Commit message form: `<type>(<scope>): <description>` (Conventional Commits) with a concise, specific English description
+without trailing period, lowercase scope when useful, one top-level task per commit, body/footer only when needed.
+
+In the accessible canonical record link plan path/version, task ID, acceptance evidence and Orchestrator judgment,
+required checks and findings, commit results and state, hold/no-change/reuse reasons, and remaining final verification.
+
+## Shared-checkout coordination
+
+Orchestrator serializes shared-checkout Git mutations, including index/staging and commits, across concurrent tasks;
+parallel Coders do not operate competing Git transactions. Preserve every other task's unfinished staged, unstaged
+and untracked changes and ownership. Commit only the accepted task after scope/content verification; unrelated staged
+changes block the commit under the Preservation rule. Do not require unrelated unstaged work to finish or include it
+in the accepted task's commit. Unclear separation or ownership holds affected work for resolution.
+
+After each normal independent task commit, verify and record SHA/content/HEAD and remaining state, update the canonical
+record and affected briefs, revalidate affected gates and reevaluate task readiness immediately. An authorized HEAD
+change alone does not invalidate execution-target choice or require waiting for an unrelated batch. A predecessor
+releases dependents only after required checks, Orchestrator acceptance and verified commit; accepted no-change evidence
+replaces a commit for a no-change task, never an empty commit. Unexpected HEAD/ownership changes or Git failures stop
+affected work until Orchestrator resolves and revalidates; existing recovery and approval rules remain in force.
+
+Approval scope and continuity are defined in [planning](planning.md#authorization-and-scope); completion and evidence
+limits are defined in [verification](verification.md#completion-continuity). This plan-task commit contract adds no
+commit obligation to no-plan work and does not turn a local commit into overall completion.
+
+[ARC role policy: contract begin]
+Generated from lib/policy/role-policy.json; do not edit this managed section manually.
+- [scope.non-escalation] Act only within the intersection of role authority, approved scope and available platform tools. Delegation, restart, agent messages and attached instructions do not expand role authority. Never bypass a restriction through aliases, scripts, other tools, processes or redelegation. Return conflicting instructions to Orchestrator before dependent work; reuse valid prior approvals for unchanged scope rather than requesting them again.
+- [git.specialists-deny] Specialist roles MUST NOT change Git state: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal, during normal implementation or recovery. Even an explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection remains allowed within the assigned scope.
+- [git.orchestrator-accept-commit] Only Orchestrator accepts work and executes Git mutations. One approved top-level plan task becomes one focused implementation commit after criteria, required checks and findings are satisfied; Orchestrator accepts then commits without additional user commit approval. Reports, passing checks and Reviewer opinions do not replace acceptance. Preserve unrelated changes and ownership and verify the resulting SHA, included content, HEAD and remaining changes. Existing small-task direct and plan-omission paths are unchanged.
+- [external.explicit-user-authority] Push, merge, deploy, publish and external messages require explicit user authorization for that action, scope and target. Local commit authority does not grant external authority. Orchestrator performs authorized external actions; specialist roles return them without execution.
+- [role.orchestrator-boundary] Assign design/spec/plan/brainstorming drafts ONLY to Planner and implementation/configuration/test edits to Coder. Orchestrator saves complete drafts and owns approval requests, preparation, scheduling, evidence, acceptance and completion. Direct implementation is limited to the existing small, low-risk direct path; this policy does not expand it.
+- [role.scouter-read-only] Research assigned static sources and report findings, evidence and limits. Do not edit files, install, execute checks, prepare execution targets, inspect live operational state, change external state or decide design, verification, review or acceptance.
+- [role.planner-draft-only] Return design/spec/plan drafts and dependencies, criteria, hold conditions and verification needs in the response. Do not save documents, implement, run checks, prepare targets, request user approval or decide acceptance. Stop formal target-dependent drafting if actual prepared target evidence is missing; route decisions to Orchestrator.
+- [role.coder-implementation] Implement only assigned approved files and focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds.
+- [role.qa-verification] Run approved checks and report commands, observations, reproduction, evidence and limits. Create only essential temporary data/logs/reports in the brief-authorized location and lifetime. Do not edit product source, tests, fixtures or configuration to pass checks, deploy or accept work. Persistent product-state checks require explicit scope and cleanup ownership. Return failures for Coder correction and required QA recheck.
+- [role.reviewer-independent] Independently inspect the assigned final changes and evidence and report actionable findings and limits. Remain read-only; do not execute QA tests, edit files, perform Git mutations or decide acceptance.
+- [review.significant-no-plan] For significant/high-risk work without a plan: Coder → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. Do not omit Reviewer merely because no plan exists. This creates no new plan obligation.
+- [review.significant-plan] For significant/high-risk plan work: each task uses Coder → fresh QA as required → Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.
+- [review.final-plan-recheck] For final overall Reviewer findings on plan work, including behavior findings, use Coder → Reviewer without QA reassignment; repeat until resolved. This exception applies only to that final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.
+- [platform.claude] Existing per-role tool allowlists reduce available tools; Bash and role contracts are not a filesystem sandbox. A role-scoped Git guard is a separate integration and is not supplied by these policy sections alone.
+[ARC role policy: contract end]

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

@@ -0,0 +1,46 @@
+# Preserve state after failure
+
+Read on branch collision, Git preparation failure, partial completion, or Git metadata write denial.
+
+On an actual failed Git/tool command, partial completion, unexpected branch/HEAD, missing assigned path,
+or conflicting edit, stop dependent work. Inspect and record the actual absolute path, branch or detached HEAD, HEAD,
+index, worktree/untracked files, ownership, and completed steps. Report the precise blocker and needed resolution to
+Orchestrator. Do not retry, fall back, or repeat completed mutations automatically.
+
+Never automatically stash, reset, clean, unstage, discard, amend, delete branches/worktrees, remove locks,
+change permissions to bypass a blocker, or bypass sandbox restrictions. Preserve all unrelated work and recovery
+artifacts. Orchestrator obtains any needed human decision, resolves preparation within authorization,
+then revalidates affected gates and issues a precise delta restart brief. An explicit user selection is required where a
+choice is needed; silence, planning approval and refusal of another option do not count.
+
+A profile reapplication failure should restore all previously replaced profile bytes and modes.
+If rollback itself fails, preserve recovery files and report their paths; do not claim a clean state or remove manual
+recovery material.
+
+## Branch collision and invalid names
+
+For an invalid name, branch creation/switch failure, lookup error, or unexpected current branch, inspect and record the
+error and actual Git state, then stop Coder handoff. A branch created without a successful switch is partial completion:
+report it, never delete it automatically, and do not treat preparation as complete.
+Do not fall back to another branch or checkout. A new collision suffix requires fresh user approval of the candidate
+(handoff-prep). Existing staged/unstaged/untracked changes stay preserved; if they block a switch or ownership is
+unclear, stop until Orchestrator resolves it.
+
+## Git metadata write denial
+
+If authorized staging, commit, branch creation, or switch is denied writing `.git/index.lock` or other Git metadata,
+block handoff and inspect read-only the exact command, workspace, error, failed path, Git directory, branch, HEAD,
+index, partial completion, lock existence, related processes, and OS permissions/ACLs, sandbox restrictions,
+and concurrent Git activity (Orchestrator performs read-only inspection of related processes and ACLs itself or assigns
+it to QA; Scouter, Planner, and Reviewer cannot run commands); record supported causes and remaining uncertainty.
+Lock-creation denial alone does not prove a stale lock. Do not delete locks, change permissions/ownership,
+bypass the sandbox, or move workspaces. If the denial is a permission-system prompt for an already authorized operation,
+request only the permission system's approval for that exact single Git command and workspace, never broad Git access.
+Before retrying recheck branch, HEAD, index, and partial completion; do not repeat completed work.
+After success verify the result and revalidate the whole handoff gate. Denied approval keeps handoff blocked;
+report the actual state.
+
+## Handoff record write denial
+
+If writing the canonical handoff record is denied or unavailable, stop that write, report the path and error to
+Orchestrator, and do not change permissions or bypass the sandbox. Use the inline-record fallback in handoff.

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

@@ -0,0 +1,102 @@
+# Prepare the current checkout
+
+Claude v1 supports the current checkout only; ARC-managed worktree execution is unsupported.
+Do not create or attach worktrees as a fallback. Report unsupported requests before dependent work.
+
+### Execution-target request gate
+
+Before requesting the user's execution-target choice, Orchestrator verifies and records planned document scope,
+absolute paths and scope coverage, design/plan depth and valid omissions, dependencies and intended execution order.
+The request does not require completed documents or individual approvals; unfinished drafts alone do not block it.
+The set contains required artifacts, not a spec on every path. Resolve scope/dependency decisions needed to identify
+the target; do not require choice evidence before asking for that choice.
+For every supported execution-target option, before obtaining the user's choice, present to the user:
+
+- Planned document list, each document's scope and coverage, repository-relative expected paths, dependencies and order,
+  and pending writing and approval status.
+- Verified absolute workspace, intended repository, current branch or detached HEAD, base HEAD, any validated
+  new-branch candidate and collision status when offered, staged/unstaged/untracked changes, preservation and edit ownership.
+
+Obtain explicit choice under the Explicit choice rule before preparation.
+Claude v1 offers current checkout/current branch (or detached HEAD) or a task branch in that checkout only.
+Planning approval or silence does not select a branch. Before branch creation present its exact candidate and base.
+Preserve unrelated changes; never stash, reset or clean to prepare.
+
+### Git mutation evidence gate
+
+Before each preparation Git mutation—branch creation/switch, approved-document staging,
+or commit—read this reference and recheck explicit execution-target choice or verified valid reuse; absolute workspace
+and intended repository; current branch or detached HEAD and HEAD; staged/unstaged/untracked changes, preservation and
+edit ownership; and the exact command, target paths, and approved scope. Confirm no unresolved failure or partial
+completion. Record these facts before the action. Missing or mismatched evidence stops that mutation.
+Initial target preparation does not require the complete approved document set: verify planned scope and target inputs.
+For approved-document staging and commit, also verify the complete approved document set and individual approval
+evidence, approved versions, dependencies, and actual index. Read-only Git checks remain allowed.
+Do not infer execution authority from an external skill's early commit step.
+
+After branch creation/switch verify actual absolute path, branch, HEAD and preserved state before dependent drafting.
+After staging verify index paths and diff before commit; unrelated staged files block the mutation. Stop and inspect
+on failure or partial completion, record actual state and completed steps, and revalidate affected gates after resolution.
+
+Batch-commit all remaining approved planning documents together in one focused docs commit before the first Coder
+handoff. Stage only those document paths and verify the staged content and scope.
+Verify the resulting SHA, subject, paths, branch, HEAD and remaining state. Already committed approved documents need no
+duplicate commit. Record actual preparation order and any deviation honestly, then complete the handoff gate before the
+next Coder start. User authorization persists for the unchanged approved target and scope; do not repeatedly ask for the
+same choice.
+
+## New task branch naming
+
+With explicit user approval of the exact candidate and base, create the branch in the current checkout (for example
+`git switch -c <branch>` from the approved base HEAD). Name it `<type>/<short-kebab-case-topic>`: a lowercase prefix for
+the task's main purpose and a short, specific lowercase kebab-case topic without spaces.
+
+| Prefix | Purpose |
+|---|---|
+| feat/ | Add a feature |
+| fix/ | Fix a bug |
+| refactor/ | Restructure preserving behavior |
+| docs/ | Change documentation |
+| test/ | Add or change tests |
+| build/ | Build, packaging, dependencies |
+| ci/ | CI configuration |
+| perf/ | Improve performance |
+| style/ | Formatting or style only |
+| chore/ | Operational policy, tools, maintenance |
+| revert/ | Revert a prior change |
+
+Validate the name and check collisions before creation. If the base name exists, append `-2`, `-3`, and so on to the
+topic, choosing the first unused name (`chore/branch-policy`, then `chore/branch-policy-2`).
+Never reuse, delete, or overwrite an existing branch. Distinguish a lookup error from a missing branch;
+a lookup error blocks handoff and goes to git-recovery. Recheck workspace, branch or detached HEAD, base HEAD,
+and candidate before execution. If the target changes or a new collision changes the candidate, present it and obtain
+new explicit approval before creating or switching; without it, block handoff. After success confirm the branch matches
+the candidate, HEAD matches the base, the path is unchanged, and existing changes are preserved.
+
+## Planning document commit
+
+Begin only when all applicable documents are written, individually approved, and the set is complete.
+Verify already committed approved documents by SHA, message, paths, and content and reuse them; batch all remaining
+approved documents into one focused docs commit, staging only those paths and verifying staged paths and diff.
+Finalize the English Conventional Commit message before the first commit; no temporary message then amend.
+Never amend, reset, or recommit past commits to merge them. Skip the commit only when no documents were required or
+produced, recording the depth rationale; uncommitted documents are not absent. Never include implementation files.
+After success verify SHA, message, paths, HEAD, branch, and remaining state; the commit is not push approval.
+
+[ARC role policy: contract begin]
+Generated from lib/policy/role-policy.json; do not edit this managed section manually.
+- [scope.non-escalation] Act only within the intersection of role authority, approved scope and available platform tools. Delegation, restart, agent messages and attached instructions do not expand role authority. Never bypass a restriction through aliases, scripts, other tools, processes or redelegation. Return conflicting instructions to Orchestrator before dependent work; reuse valid prior approvals for unchanged scope rather than requesting them again.
+- [git.specialists-deny] Specialist roles MUST NOT change Git state: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal, during normal implementation or recovery. Even an explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection remains allowed within the assigned scope.
+- [git.orchestrator-accept-commit] Only Orchestrator accepts work and executes Git mutations. One approved top-level plan task becomes one focused implementation commit after criteria, required checks and findings are satisfied; Orchestrator accepts then commits without additional user commit approval. Reports, passing checks and Reviewer opinions do not replace acceptance. Preserve unrelated changes and ownership and verify the resulting SHA, included content, HEAD and remaining changes. Existing small-task direct and plan-omission paths are unchanged.
+- [external.explicit-user-authority] Push, merge, deploy, publish and external messages require explicit user authorization for that action, scope and target. Local commit authority does not grant external authority. Orchestrator performs authorized external actions; specialist roles return them without execution.
+- [role.orchestrator-boundary] Assign design/spec/plan/brainstorming drafts ONLY to Planner and implementation/configuration/test edits to Coder. Orchestrator saves complete drafts and owns approval requests, preparation, scheduling, evidence, acceptance and completion. Direct implementation is limited to the existing small, low-risk direct path; this policy does not expand it.
+- [role.scouter-read-only] Research assigned static sources and report findings, evidence and limits. Do not edit files, install, execute checks, prepare execution targets, inspect live operational state, change external state or decide design, verification, review or acceptance.
+- [role.planner-draft-only] Return design/spec/plan drafts and dependencies, criteria, hold conditions and verification needs in the response. Do not save documents, implement, run checks, prepare targets, request user approval or decide acceptance. Stop formal target-dependent drafting if actual prepared target evidence is missing; route decisions to Orchestrator.
+- [role.coder-implementation] Implement only assigned approved files and focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds.
+- [role.qa-verification] Run approved checks and report commands, observations, reproduction, evidence and limits. Create only essential temporary data/logs/reports in the brief-authorized location and lifetime. Do not edit product source, tests, fixtures or configuration to pass checks, deploy or accept work. Persistent product-state checks require explicit scope and cleanup ownership. Return failures for Coder correction and required QA recheck.
+- [role.reviewer-independent] Independently inspect the assigned final changes and evidence and report actionable findings and limits. Remain read-only; do not execute QA tests, edit files, perform Git mutations or decide acceptance.
+- [review.significant-no-plan] For significant/high-risk work without a plan: Coder → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. Do not omit Reviewer merely because no plan exists. This creates no new plan obligation.
+- [review.significant-plan] For significant/high-risk plan work: each task uses Coder → fresh QA as required → Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.
+- [review.final-plan-recheck] For final overall Reviewer findings on plan work, including behavior findings, use Coder → Reviewer without QA reassignment; repeat until resolved. This exception applies only to that final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.
+- [platform.claude] Existing per-role tool allowlists reduce available tools; Bash and role contracts are not a filesystem sandbox. A role-scoped Git guard is a separate integration and is not supplied by these policy sections alone.
+[ARC role policy: contract end]

package/claude/skill/references/handoff.md

@@ -0,0 +1,100 @@
+# Coder handoff
+
+Orchestrator verifies the absolute workspace/repository, branch or detached HEAD, HEAD, staged/unstaged/untracked state,
+ownership, document approvals and committed planning documents before first start and restart.
+The approved execution target must remain valid. Claude v1 supports current checkout execution and does not support
+ARC-managed worktrees.
+
+Execution-target choice and actual preparation precede formal drafting and saving of required specs/plans.
+Initial design proposals may precede choice. Initial target preparation does not authorize Coder; all applicable
+approvals, complete documents, verified batch docs commits or valid absence, and final Git verification remain required.
+Record planned document scope/paths and actual preparation separately, followed by actual drafting/save/approval and
+commit results; preserve actual order and evidence gaps. Reuse a valid choice during document drafting and subsequent
+implementation while scope and target remain unchanged. Authorized HEAD and dirty-state changes alone do not invalidate
+choice; verify preservation and ownership. A changed scope or target requires fresh explicit choice before dependent
+drafting or preparation and does not require document completion. Never fall back automatically.
+
+Resolve the Git common directory (`git rev-parse --path-format=absolute --git-common-dir`) and keep one canonical record
+at `<git-common-dir>/arc/handoff/<plan-or-task-slug>.md`, outside the working tree.
+The slug is unique per plan: the dated plan filename stem, or a spec/task slug when no plan exists; never overwrite
+another plan's record. Never stage it or store secrets there. Orchestrator updates the record after each accepted task
+commit (task ID, SHA, state). Record approved document paths/versions/coverage/dependencies and approval evidence;
+explicit target choice; prior and resulting Git state; document commit SHA/subject/files; task scope, ownership,
+checks and limits. If a gate or record was late, record actual order and resolve forward; never claim retroactive
+compliance.
+
+The Coder brief supplies absolute workspace, verified branch/HEAD, canonical record path, approved task/criteria,
+exact file ownership, expected tests, dependency limits and blocked conditions. Restart brief: supply only verified
+deltas and mark unchanged fields; `unchanged` means unchanged relative to the record file the fresh Coder reads,
+and every other brief field is in full. Coder trusts Orchestrator verified prep rather than independently repeating
+approval/Git evidence checks, reads fields marked unchanged, and stops on an actual observed conflict.
+Tell Coder that others share the repository and unrelated work must be preserved.
+
+Roles report directly to Orchestrator. Do not delegate at depth 2. Orchestrator sequences dependent work,
+resolves actual blockers and revalidates affected gates before resume. No automatic retry after unexpected Git or tool
+failure.
+
+If the record write is denied or unavailable, Orchestrator carries the full record inline in every Coder brief (no
+delta, no record-file `unchanged`) and states why; that satisfies the accessible-record requirement.
+Do not delete it automatically.
+
+## Task readiness at every assignment
+
+Before each first start or restart, if an approved plan exists, link its current dependency/readiness record
+(planning.md) in the canonical record and brief. Where plan omission is valid under existing rules, do not create a
+plan or map solely to satisfy this linking duty; record the applicable omission judgment and rationale in the
+canonical record and brief. Plan absence alone does not qualify for omission, and an unapproved required plan
+cannot bypass its approval gate.
+
+Before assignment, apply every readiness condition in
+[planning.md, Dependency and readiness record](planning.md#dependency-and-readiness-record), including predecessor
+checks, Orchestrator acceptance and verified focused commit or accepted no-change evidence. A Coder completion report
+alone is insufficient. Verify the linked record is current and capacity and file ownership permit assignment.
+Readiness supplements the full handoff gate and execution-target restrictions; it never waives them.
+For authorized HEAD or state changes, refresh this record and affected briefs, verify preservation and ownership,
+revalidate affected gates, and reassess readiness under planning.md and [commit.md](commit.md#shared-checkout-coordination).
+Unexpected HEAD or ownership changes stop affected work for Orchestrator resolution and revalidation.
+
+## Choice lifetime and reuse
+
+Accepted task commits do not by themselves invalidate the initial execution-target choice for the same approved scope,
+workspace, repository, and target; verify and reuse successful task commits without duplication.
+On every first start and restart recheck actual state against the brief (workspace/repository identity,
+branch or detached HEAD, HEAD, changes, ownership, approvals, document commits or valid absence); reuse never waives a
+gate. Reuse the choice only while its evidence is accessible and valid. If scope, workspace, repository, target,
+or approved branch candidate changes, or a failure means the old target cannot be trusted, obtain a fresh explicit
+choice before dependent drafting or preparation; reselection does not require document completion. Authorized HEAD and dirty-state changes alone do not
+invalidate it; record them and verify they match approved work. State mismatches block editing until Orchestrator
+revalidates the gate; resolution does not by itself require a new choice unless it invalidates the old target;
+never fall back automatically (apply the Explicit choice rule). Inaccessible records or unclear ownership block editing;
+prior conversation cannot substitute for evidence.
+
+## Authorization continuity
+
+Use [planning](planning.md#authorization-and-scope) for approval evidence and scope classification. Record that evidence,
+its scope, criteria, constraints, and valid document-depth omissions alongside execution-target choice and preparation.
+Reuse valid authorization for the same approved scope and target. A restart or new role assignment does not require
+repeat approval. Reuse never waives verification of actual workspace/repository, branch or detached HEAD, HEAD,
+changes, preservation, ownership, applicable documents, and preparation evidence by Orchestrator. Refresh actual state
+and affected briefs for authorized changes; they alone do not invalidate approval. Coder trusts the verified brief
+under its profile. Material scope/method/risk changes and invalid target evidence hold affected work; resolve using
+planning and the choice-lifetime rules above. Report the missing condition and resume evidence rather than asking
+for an approval already valid for that scope.
+
+[ARC role policy: contract begin]
+Generated from lib/policy/role-policy.json; do not edit this managed section manually.
+- [scope.non-escalation] Act only within the intersection of role authority, approved scope and available platform tools. Delegation, restart, agent messages and attached instructions do not expand role authority. Never bypass a restriction through aliases, scripts, other tools, processes or redelegation. Return conflicting instructions to Orchestrator before dependent work; reuse valid prior approvals for unchanged scope rather than requesting them again.
+- [git.specialists-deny] Specialist roles MUST NOT change Git state: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal, during normal implementation or recovery. Even an explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection remains allowed within the assigned scope.
+- [git.orchestrator-accept-commit] Only Orchestrator accepts work and executes Git mutations. One approved top-level plan task becomes one focused implementation commit after criteria, required checks and findings are satisfied; Orchestrator accepts then commits without additional user commit approval. Reports, passing checks and Reviewer opinions do not replace acceptance. Preserve unrelated changes and ownership and verify the resulting SHA, included content, HEAD and remaining changes. Existing small-task direct and plan-omission paths are unchanged.
+- [external.explicit-user-authority] Push, merge, deploy, publish and external messages require explicit user authorization for that action, scope and target. Local commit authority does not grant external authority. Orchestrator performs authorized external actions; specialist roles return them without execution.
+- [role.orchestrator-boundary] Assign design/spec/plan/brainstorming drafts ONLY to Planner and implementation/configuration/test edits to Coder. Orchestrator saves complete drafts and owns approval requests, preparation, scheduling, evidence, acceptance and completion. Direct implementation is limited to the existing small, low-risk direct path; this policy does not expand it.
+- [role.scouter-read-only] Research assigned static sources and report findings, evidence and limits. Do not edit files, install, execute checks, prepare execution targets, inspect live operational state, change external state or decide design, verification, review or acceptance.
+- [role.planner-draft-only] Return design/spec/plan drafts and dependencies, criteria, hold conditions and verification needs in the response. Do not save documents, implement, run checks, prepare targets, request user approval or decide acceptance. Stop formal target-dependent drafting if actual prepared target evidence is missing; route decisions to Orchestrator.
+- [role.coder-implementation] Implement only assigned approved files and focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds.
+- [role.qa-verification] Run approved checks and report commands, observations, reproduction, evidence and limits. Create only essential temporary data/logs/reports in the brief-authorized location and lifetime. Do not edit product source, tests, fixtures or configuration to pass checks, deploy or accept work. Persistent product-state checks require explicit scope and cleanup ownership. Return failures for Coder correction and required QA recheck.
+- [role.reviewer-independent] Independently inspect the assigned final changes and evidence and report actionable findings and limits. Remain read-only; do not execute QA tests, edit files, perform Git mutations or decide acceptance.
+- [review.significant-no-plan] For significant/high-risk work without a plan: Coder → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. Do not omit Reviewer merely because no plan exists. This creates no new plan obligation.
+- [review.significant-plan] For significant/high-risk plan work: each task uses Coder → fresh QA as required → Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.
+- [review.final-plan-recheck] For final overall Reviewer findings on plan work, including behavior findings, use Coder → Reviewer without QA reassignment; repeat until resolved. This exception applies only to that final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.
+- [platform.claude] Existing per-role tool allowlists reduce available tools; Bash and role contracts are not a filesystem sandbox. A role-scoped Git guard is a separate integration and is not supplied by these policy sections alone.
+[ARC role policy: contract end]

package/claude/skill/references/limits.md

@@ -0,0 +1,42 @@
+# Subagent limits
+
+Before the first subagent creation, Orchestrator reads this reference and the adjacent
+`../limits.toml` (installed at `skills/arc/limits.toml`). Require version = 1,
+`max_total_subagents` and `max_concurrent_subagents` as positive safe integers.
+Installation defaults are max_total_subagents = 100 and max_concurrent_subagents = 5.
+A missing, malformed or unreadable policy blocks new creation; report it rather than assuming defaults.
+Freeze these settings for one ARC coordination session/tree; reinstalling affects new sessions.
+
+## Counting and reservations
+
+Maintain a session ledger of instance IDs, parent IDs, pending reservations, creation outcomes,
+and active/completed state. The Orchestrator itself is excluded. All created descendants,
+including nested or non-ARC agents, count toward the total. A completed agent never refunds
+the cumulative budget. Follow-up/resume of the same instance does not increment total;
+a fresh instance, retry that creates a new instance, or replacement does increment it.
+Waiting, blocked, running and idle resumable instances consume concurrency until their
+completion/termination is confirmed. Obey any lower actual runtime capacity, including
+native retention of completed instances; ARC counts do not prove that a native slot is free.
+
+Before any parallel dispatch, reserve the entire proposed batch in the ledger:
+created + pending reservations + proposed <= max_total_subagents, and
+active + pending reservations + proposed <= max_concurrent_subagents and available runtime capacity.
+Record a reservation before each creation call. Confirmed creation converts it into a created,
+active ID. Release a reservation only when failure proves that no instance was created.
+An uncertain result keeps its reservation and capacity until reconciled; never retry blindly.
+Serialize work when a batch does not fit. There are no reserved role slots.
+
+## Continuation and exhaustion
+
+Preserve the ledger through continuation, resume and context compaction; reconcile actual instance
+IDs before dispatch. Ledger loss must never reset counters to zero. If reconstruction is incomplete,
+hold creation and report the unknown budget; use a conservative bound only with sufficient evidence.
+Completion frees confirmed active capacity, never the total-created budget. Exhaustion holds new
+creation and requires reporting remaining work and budgets. It never authorizes skipping required
+QA or Reviewer, role freshness, approval, ownership, dependency or same-file edit gates.
+
+This cumulative guard and ARC scheduling are prompt-level policy, not hard runtime enforcement.
+Policy text tests prove package consistency, not actual agent compliance or native runtime support.
+Claude `settings.json.env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` constrains its native session.
+Independent sessions, accounts and platforms do not share this ARC ledger; Agent Teams and hosted APIs
+are outside this contract. Native application must be checked in a supported new session separately.