@yunhozz/arc 0.0.0-stage → 0.1.0

package/claude/skill/hooks/git-policy.json

@@ -0,0 +1,208 @@
+{
+  "schemaVersion": 1,
+  "globalValueOptions": [
+    "-C",
+    "--git-dir",
+    "--work-tree"
+  ],
+  "globalFlags": [
+    "--no-pager",
+    "-P",
+    "--literal-pathspecs"
+  ],
+  "commands": {
+    "status": {
+      "flags": [
+        "--short",
+        "-s",
+        "--branch",
+        "-b",
+        "--porcelain",
+        "--porcelain=v1",
+        "--porcelain=v2",
+        "--untracked-files=no",
+        "--untracked-files=all"
+      ],
+      "values": [],
+      "positionals": "any"
+    },
+    "diff": {
+      "flags": [
+        "--stat",
+        "--numstat",
+        "--shortstat",
+        "--name-only",
+        "--name-status",
+        "--oneline",
+        "--no-color",
+        "--color=never",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--raw",
+        "--patch",
+        "-p",
+        "--summary",
+        "--exit-code",
+        "--quiet",
+        "--check",
+        "--cached",
+        "--staged",
+        "--relative",
+        "--no-index"
+      ],
+      "values": [],
+      "positionals": "any"
+    },
+    "log": {
+      "flags": [
+        "--stat",
+        "--numstat",
+        "--shortstat",
+        "--name-only",
+        "--name-status",
+        "--oneline",
+        "--no-color",
+        "--color=never",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--raw",
+        "--patch",
+        "-p",
+        "--summary",
+        "--exit-code",
+        "--quiet",
+        "-<count>",
+        "--all",
+        "--decorate",
+        "--no-decorate",
+        "--graph"
+      ],
+      "values": [
+        "-n",
+        "--max-count",
+        "--format",
+        "--pretty"
+      ],
+      "positionals": "any"
+    },
+    "show": {
+      "flags": [
+        "--stat",
+        "--numstat",
+        "--shortstat",
+        "--name-only",
+        "--name-status",
+        "--oneline",
+        "--no-color",
+        "--color=never",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--raw",
+        "--patch",
+        "-p",
+        "--summary",
+        "--exit-code",
+        "--quiet",
+        "--no-patch",
+        "-s"
+      ],
+      "values": [
+        "--format",
+        "--pretty"
+      ],
+      "positionals": "any"
+    },
+    "rev-parse": {
+      "flags": [
+        "--show-toplevel",
+        "--git-common-dir",
+        "--absolute-git-dir",
+        "--git-dir",
+        "--verify",
+        "--short",
+        "--is-inside-work-tree",
+        "--abbrev-ref",
+        "--path-format=absolute"
+      ],
+      "values": [],
+      "positionals": "any"
+    },
+    "ls-files": {
+      "flags": [
+        "--stage",
+        "-s",
+        "--cached",
+        "--others",
+        "--exclude-standard",
+        "--deleted",
+        "--modified"
+      ],
+      "values": [],
+      "positionals": "any"
+    },
+    "ls-tree": {
+      "flags": [
+        "-r",
+        "--name-only",
+        "-l"
+      ],
+      "values": [],
+      "positionals": "any"
+    },
+    "branch": {
+      "flags": [
+        "--list",
+        "--all",
+        "-a",
+        "--remotes",
+        "-r",
+        "--show-current",
+        "-v",
+        "-vv"
+      ],
+      "values": [],
+      "positionals": "list"
+    },
+    "config": {
+      "flags": [
+        "--get",
+        "--get-all",
+        "--get-regexp",
+        "--list",
+        "-l",
+        "--show-origin",
+        "--show-scope",
+        "--local",
+        "--global",
+        "--system"
+      ],
+      "values": [],
+      "positionals": "query"
+    },
+    "worktree list": {
+      "flags": [
+        "--porcelain",
+        "-z",
+        "-v"
+      ],
+      "values": [],
+      "positionals": "none"
+    },
+    "remote": {
+      "flags": [
+        "-v",
+        "--verbose"
+      ],
+      "values": [],
+      "positionals": "none"
+    },
+    "remote get-url": {
+      "flags": [
+        "--all",
+        "--push"
+      ],
+      "values": [],
+      "positionals": "any"
+    }
+  }
+}

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]