@yunhozz/arc 0.0.0-stage → 0.1.1

package/claude/skill/references/superpowers/writing-plans/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: writing-plans
+description: Use when you have a spec or requirements for a multi-step task, before touching code
+---
+
+# Writing Plans
+
+## Overview
+
+Write implementation plans for an engineer who has not seen this codebase or this spec. Assume they write idiomatic code in the project's language once they know the exact interface and the exact test, and that they will make a reasonable choice wherever the plan leaves one open. What they cannot know is what you decided: which files, which names and signatures, which values from the spec, which tests prove each task. Document those. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
+
+**Context:** If working in an isolated worktree, it should have been created via the `superpowers:using-git-worktrees` skill at execution time.
+
+**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
+- (User preferences for plan location override this default)
+
+## Scope Check
+
+If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
+
+## File Structure
+
+Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
+
+- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
+- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
+- Files that change together should live together. Split by responsibility, not by technical layer.
+- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.
+
+This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.
+
+## Task Right-Sizing
+
+A task is the smallest unit that carries its own test cycle and is worth a
+fresh reviewer's gate. When drawing task boundaries: fold setup,
+configuration, scaffolding, and documentation steps into the task whose
+deliverable needs them; split only where a reviewer could meaningfully
+reject one task while approving its neighbor. Each task ends with an
+independently testable deliverable.
+
+## Step Granularity
+
+**Each step is one action with a checkable result:**
+- "Write the failing test" - step
+- "Run it to make sure it fails" - step
+- "Implement the minimal code to make the test pass" - step
+- "Run the tests and make sure they pass" - step
+- "Commit" - step
+
+## Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+**Spec:** [path to the spec/design doc this plan implements — the plan
+argues from the spec, so the spec travels with it; executors read both]
+
+## Global Constraints
+
+[The spec's project-wide requirements — version floors, dependency limits,
+naming and copy rules, platform requirements — one line each, with exact
+values copied verbatim from the spec. Every task's requirements implicitly
+include this section.]
+
+## Review Focus
+
+[The five input classes or failure modes the spec implies but no task's
+tests exercise that are most likely to bite a person using this software
+— one line each, naming the input or condition and the behavior a
+reasonable person would expect, most likely first. The spec is a vision
+document: it says what the software must do, not everything it will
+meet, and its silence on an input is not permission for that input to
+break the program. Write the list here, once, with the spec in front of
+you. Then, for each line, add the test that pins it to the task that
+owns the code, in that task's own step style.]
+
+---
+```
+
+## Task Structure
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+**Interfaces:**
+- Consumes: [what this task uses from earlier tasks — exact signatures]
+- Produces: [what later tasks rely on — exact function names, parameter
+  and return types. A task's implementer sees only their own task; this
+  block is how they learn the names and types neighboring tasks use.]
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: FAIL with "function not defined"
+
+- [ ] **Step 3: Implement `function(input: InputType) -> ResultType` in `exact/path/to/file.py`**
+
+One line on the approach when the signature and the test leave a choice
+(which library call, which data structure); a code block only for an
+algorithm they do not determine.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+````
+
+## What a Step Contains
+
+A step is done when the implementer can write exactly one reasonable thing
+from it. That is the whole requirement: unambiguous, not complete. Each kind
+of step carries what makes it unambiguous and nothing more:
+
+- **A test step:** the test's name and its assertions, as code, with the
+  spec's exact values in them.
+- **A code step:** the exact signature (name, parameters, return type), the
+  file it lives in, and the specific values the spec pins. The implementer
+  writes the body. A body appears only for an algorithm the signature and
+  tests do not determine, or for exact copy the spec fixes.
+- **A verification step:** the command to run and the output that means it
+  passed.
+- **A reference to another task:** that task's Interfaces block says what
+  to use; the plan does not repeat that task's code.
+
+A plan is the set of decisions the implementer cannot make alone. A plan
+longer than the code it describes has written the code instead. Lines that
+decide nothing ("TBD", "handle edge cases", "add appropriate validation",
+"write tests for the above", a type or function no task defines) are the
+opposite failure, and the self-review catches both.
+
+## Self-Review
+
+After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.
+
+**1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.
+
+**2. Step scan:** Every step must let the implementer write exactly one reasonable thing, and no step may carry more than that: a line that decides nothing is a gap, a function body the signature and tests already determine is a transcript. Fix both.
+
+**3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.
+
+**4. Review Focus:** For each input class or failure mode the spec implies, is there a task whose tests exercise it? The five uncovered ones most likely to bite a person go in the Review Focus section, and each line there gets its test added to the owning task. An empty section means you checked and found none, not that you skipped the check.
+
+**5. Proportion:** Compare the plan's length to the spec's. A plan several times longer than the spec it implements is a transcript of the program, not a plan. If code blocks are most of the document, replace bodies with signatures, test names and assertions, and check that each step is still unambiguous.
+
+If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.
+
+## Execution Handoff
+
+After saving and self-reviewing the plan, link it for your human partner
+to read. If they have already explicitly supplied an execution method, ask
+them to review the plan and confirm it captures what they want; wait for that
+review before implementation, then use the preserved method. Otherwise, ask
+them to review the plan and choose an execution method before implementation.
+
+**When no execution method has already been supplied:**
+
+**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Please review the plan. Which execution approach would you prefer?**
+
+- **Subagent-driven** - A fresh subagent implements each task and a fresh reviewer checks it before the next one starts, then a whole-branch review at the end. Most thorough; costs a fresh context per task and per review.
+- **Native** - I implement every task myself in this session, the way this harness runs work, then one fresh reviewer on the most capable model checks the whole branch. Cheapest and fastest; no independent review until the end. Runs well with a mid-tier session model, since the plan carries the design.
+
+**For this plan I recommend <one of the two>, because <one sentence from the plan: how much the tasks depend on each other's interfaces, how many there are, what a shipped mistake would cost>. Does the plan capture what you want, and which approach should we use?"**
+
+**When an execution method has already been supplied:**
+
+**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Please review the plan. Does it capture what you want?"**
+
+**If Subagent-driven chosen:**
+- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
+
+**If Native chosen:**
+- **REQUIRED SUB-SKILL:** Use superpowers:executing-plans

package/claude/skill/references/verification.md

@@ -0,0 +1,125 @@
+# Verification and acceptance
+
+Define observable checks from acceptance criteria. For feature/behavior implementation use test-driven-development:
+meaningful test first, observed expected failure, minimal implementation, focused success, then the project suite.
+A required skill or test constraint must be reported before dependent edits. A waiver needs a precise Orchestrator
+record of narrow scope, understood/reversible risk, no dependent stages or cross-component lifecycle,
+and one focused verification path; a documentation exception authorizes only its named structural checks.
+Neither is a claim of TDD.
+
+QA runs approved checks without editing source and returns commands, results, failures, evidence and limitations.
+Report verification side effects within approved scope. Do not broaden tests, repair failures or claim acceptance
+independently. Reviewer independently reads the final complete diff after the required QA/focused checks for
+correctness, security and policy consistency; request runtime checks through Orchestrator because Reviewer has no Bash
+tool.
+
+Orchestrator inspects results, resolves findings and decides acceptance. Passing local tests does not establish remote
+model availability or actual provider effort application. Policy prose requires independent role/approval review;
+text presence alone cannot establish agent compliance. Distinguish tested behavior from unverified runtime assumptions.
+Unexpected failures trigger diagnosis and stop dependent work; expected failure-first RED does not authorize unrelated
+repairs.
+
+## Reviewer timing and task acceptance
+
+Task acceptance and its focused commit need only the task's risk-scaled evidence: a FRESH QA instance per task that
+needs QA (same-task rechecks may reuse), or Orchestrator focused checks for small, low-risk tasks; Reviewer is never a
+plan-task acceptance prerequisite. Do not delay an independently acceptable task for final-only checks,
+and do not defer currently required task checks to final verification. For significant work with a plan,
+Reviewer reviews once on the final full change after all plan tasks are accepted with their risk-scaled checks and any
+QA recheck at the final relevant state; without a plan, Reviewer follows QA before acceptance.
+A task commit does not mark unperformed final verification complete.
+
+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.
+
+Orchestrator writes the final base..HEAD diff plus changed-file list to `<git-common-dir>/arc/review/<slug>.diff` (same
+slug as the handoff record; base is the approved base HEAD recorded at handoff; inline when small or write denied) and
+cites its absolute path in the Reviewer brief. Reviewer reads that artifact, not Git commands, and states review limits.
+
+### UI browser acceptance checks
+
+QA may use the existing approved test environment to launch the app or exercise the URL through Bash only (QA has no
+browser tool), following any applicable installed browser skill's command-line instructions, only when assigned UI
+acceptance criteria and the brief supplies the workspace, existing launch command or URL, account and test-data scope,
+and permitted interactions; the brief cites this section with its path. This does not authorize editing
+source/documents/tests/configuration, installing dependencies, or changing environment configuration.
+Report missing prerequisites or tools unavailable through Bash to Orchestrator with the exact limitation and leave
+affected criteria unverified. Per criterion record command or URL, test state and viewport (or not applicable),
+interaction steps, expected and observed results, and accessible evidence. App startup, page load, and static checks
+alone are not proof of UI behavior. Clean up only QA-created processes and sessions; preserve shared services and
+sessions.
+
+### Criterion evidence and finding handoff
+
+QA reports every brief criterion by identifier (or original wording): method and scope, run status, accessible evidence,
+verdict, and unverified reason and remaining scope. Run status is passed, failed, not run, or environment blocked;
+verdict is proven, unmet, or unverified. A passing check alone does not prove a criterion; evidence must connect its
+conditions and expected result to observations. Partial confirmation, out-of-scope, missing-check, and
+environment-blocked gaps stay unverified; omit no criteria. PASS, if used, means only run status.
+Structural checks prove structure only, not behavior, installation, or live agent compliance.
+
+On QA execution failure or unmet criterion, Orchestrator assigns Coder correction and a QA recheck of the reproduction
+path and invalidated related checks before Reviewer; QA reports the prior finding resolved, unresolved, or unverified.
+Environment blocks, missing checks, and out-of-scope criteria are evidence gaps, not presumed defects;
+Reviewer does not substitute for QA evidence. Outside the required final plan correction loop,
+Orchestrator decides when a Reviewer recheck is warranted by the changed scope and independence.
+
+For an acceptance-linked finding Reviewer reports criterion, expected behavior, observed problem, related source,
+reproduction conditions and steps, and evidence, labeling each source-inferred or execution-observed,
+without running QA tests. Outside the final plan Reviewer correction exception, Orchestrator routes it to Coder and QA recheck. Reviewer still handles structure, design,
+factual, and security findings; observable security/interface issues may need both QA and Reviewer.
+
+Orchestrator accepts using verdicts, findings, rechecks, and remaining gaps, not an overall run result;
+disposition never turns unverified into proven. Low-risk work without QA likewise links each criterion to Orchestrator
+focused-check evidence.
+
+Read brief-cited `references/superpowers/test-driven-development/SKILL.md`; preserve ARC TDD exceptions.
+
+
+### Final plan Reviewer correction loop
+
+For a plan's final overall Reviewer findings, including behavior findings, Orchestrator assigns
+Coder → Reviewer recheck with no QA reassignment. Repeat corrections and Reviewer rechecks until findings are resolved;
+the initial single full review does not prohibit necessary rechecks. Before the initial final overall Reviewer,
+risk-required checks and QA execution failures or unmet criteria still require Coder correction → QA recheck.
+This exception applies only to findings from the final overall Reviewer of work with a plan.
+Work without a plan retains its existing verification flow. Scope expansion, separate mandatory obligations,
+or unresolved evidence gaps hold affected work for Orchestrator to resolve and obtain required approvals.
+Orchestrator assigns corrections/rechecks and decides acceptance. Reviewer remains read-only, must not run QA
+checks or decide acceptance. Previous QA evidence must not be presented as post-fix execution evidence;
+report only checks actually performed, their actor, target state, results and remaining limits.
+
+## Completion continuity
+
+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
+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.
+
+[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/visual-companion.md

@@ -0,0 +1,16 @@
+# Visual companion
+
+Use a visual when it materially helps design discussion or verification. Orchestrator determines the available
+capability and consent required by the actual tool. Planner returns visualization needs to Orchestrator because its
+tools are read-only file inspection; do not invent browser or shell access for it.
+Other depth 2 roles must stay within their exact allowlists and may not delegate visualization to another agent.
+
+Determine actual available browser and preview capabilities before use; do not assume managed preview tools exist.
+Use an available authorized local/browser workflow only when scoped by Orchestrator.
+Keep preview artifacts separate from user files, record generated side effects, preserve unrelated work,
+and report unavailable capabilities without claiming visual verification. Never expose secrets or publish a preview
+without authorization.
+
+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 without global fallback.

package/claude/skill/scripts/apply-models.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""Reapply installed Claude ARC models without invoking a provider."""
+import sys
+sys.dont_write_bytecode = True
+import argparse
+from pathlib import Path
+from model_config import ValidationError, apply_models, load_settings
+
+
+def main():
+    skill = Path(__file__).absolute().parent.parent
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--config', type=Path, default=skill / 'models.toml')
+    parser.add_argument('--agents-dir', type=Path, default=skill.parent.parent / 'agents')
+    parser.add_argument('--check', action='store_true')
+    parser.add_argument('--dry-run', action='store_true')
+    args = parser.parse_args()
+    try:
+        changed = apply_models(load_settings(args.config), args.agents_dir, check=args.check, dry_run=args.dry_run)
+    except (ValidationError, OSError) as exc:
+        print(f'error: {exc}', file=sys.stderr)
+        return 2
+    verb = 'Would update' if args.check or args.dry_run else 'Updated'
+    print(f'{verb} {len(changed)} Claude profiles.')
+    for path in changed:
+        print(path)
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/claude/skill/scripts/model_config.py

@@ -0,0 +1,211 @@
+"""Strict Claude ARC settings, frontmatter rendering and transactional updates."""
+from __future__ import annotations
+
+import os
+import json
+import base64
+from urllib.parse import urlparse
+from pathlib import Path
+import re
+import stat
+import tempfile
+import tomllib
+
+ROLE_FILES = {f'arc_{role}': f'arc-{role}.md' for role in ('scouter', 'planner', 'coder', 'qa', 'reviewer')}
+ROLE_TOOLS = {
+    'scouter': ['Read', 'Grep', 'Glob', 'WebFetch', 'WebSearch'],
+    'planner': ['Read', 'Grep', 'Glob'],
+    'coder': ['Read', 'Grep', 'Glob', 'Bash', 'Write', 'Edit'],
+    'qa': ['Read', 'Grep', 'Glob', 'Bash'],
+    'reviewer': ['Read', 'Grep', 'Glob'],
+}
+EFFORTS = {'low', 'medium', 'high', 'xhigh', 'max'}
+MODEL = re.compile(r'[A-Za-z0-9][A-Za-z0-9._:/@+\-]*\Z')
+
+
+class ValidationError(ValueError):
+    """Invalid local settings, profile or target path."""
+
+
+PRESETS = ('economy', 'balanced', 'smart')
+
+
+def _validate_role(settings: dict, name: str) -> dict:
+    if not isinstance(settings, dict) or set(settings) != {'model', 'effort'}:
+        raise ValidationError(f'{name}: require model and effort only')
+    model, effort = settings['model'], settings['effort']
+    if not isinstance(model, str) or MODEL.fullmatch(model) is None:
+        raise ValidationError(f'{name}: model must be a nonempty plain model identifier')
+    if not isinstance(effort, str) or effort not in EFFORTS:
+        raise ValidationError(f'{name}: unsupported effort')
+    return dict(settings)
+
+
+def validate_settings(data: dict) -> dict:
+    if not isinstance(data, dict) or set(data) != {'version', 'preset', 'roles'} or type(data['version']) is not int or data['version'] != 1:
+        raise ValidationError('update to version 1 unified presets; reinstall ARC or edit models.toml to include preset and all role presets')
+    if not isinstance(data['preset'], str) or data['preset'] not in PRESETS:
+        raise ValidationError('preset must be economy, balanced or smart')
+    roles = data['roles']
+    if not isinstance(roles, dict) or set(roles) != set(ROLE_FILES):
+        raise ValidationError('settings require exactly the five ARC roles')
+    result = {}
+    for name, variants in roles.items():
+        if not isinstance(variants, dict) or set(variants) != set(PRESETS):
+            raise ValidationError(f'{name}: require exactly economy, balanced and smart')
+        validated = {preset: _validate_role(settings, f'{name}.{preset}') for preset, settings in variants.items()}
+        result[name] = validated[data['preset']]
+    return result
+
+
+def require_regular(path: Path) -> None:
+    # Inspect every existing component without resolving symlinks.
+    path = Path(os.path.abspath(path))
+    for component in (path, *path.parents):
+        if component.is_symlink():
+            raise ValidationError(f'symlink is not supported: {component}')
+    if not path.is_file():
+        raise ValidationError(f'expected regular file: {path}')
+
+
+def load_settings(path: Path) -> dict:
+    require_regular(path)
+    try:
+        return validate_settings(tomllib.loads(path.read_text(encoding='utf-8')))
+    except (UnicodeError, tomllib.TOMLDecodeError) as exc:
+        raise ValidationError(f'{path}: invalid TOML: {exc}') from exc
+
+
+def _profile(content: bytes) -> tuple[list[str], dict, dict]:
+    try:
+        lines = content.decode('utf-8').splitlines(keepends=True)
+    except UnicodeError as exc:
+        raise ValidationError('profile must be UTF-8') from exc
+    if not lines or lines[0].rstrip('\r\n') != '---':
+        raise ValidationError('missing opening frontmatter delimiter')
+    fields, indices = {}, {}
+    current = None
+    closed = False
+    skip_until = 0
+    for index, line in enumerate(lines[1:], 1):
+        if index < skip_until:
+            continue
+        text = line.rstrip('\r\n')
+        if text == '---':
+            closed = True
+            break
+        if text == 'hooks:':
+            if 'hooks' in fields:
+                raise ValidationError('duplicate managed hooks')
+            raw = [item.rstrip('\r\n') for item in lines[index:index + 6]]
+            expected = ['hooks:', '  PreToolUse:', '    - matcher: Bash', '      hooks:', '        - type: command']
+            try:
+                if len(raw) != 6 or raw[:5] != expected or not raw[5].startswith('          command: '):
+                    raise ValueError('unsupported hook structure')
+                command = json.loads(raw[5][19:])
+                match = re.fullmatch(r'''node -e "eval\(Buffer\.from\('([A-Za-z0-9+/]+={0,2})','base64'\)\.toString\('utf8'\)\)" "([A-Za-z0-9+/]+={0,2})"''', command)
+                if not match:
+                    raise ValueError('unmanaged command')
+                bootstrap = base64.b64decode(match[1], validate=True).decode('utf-8')
+                expected_bootstrap = "import(Buffer.from(process.argv[1],'base64').toString('utf8')).then(module=>module.runHook()).catch(()=>{process.stderr.write('ARC Git guard failed to load\\n');process.exitCode=2;});"
+                url = urlparse(base64.b64decode(match[2], validate=True).decode('utf-8'))
+                if bootstrap != expected_bootstrap or url.scheme != 'file' or url.netloc or not url.path.endswith('/hooks/role-git-guard.mjs') or url.query or url.fragment:
+                    raise ValueError('invalid managed hook URL')
+            except (ValueError, TypeError, UnicodeError) as exc:
+                raise ValidationError('unsupported managed hooks') from exc
+            fields['hooks'] = command
+            indices['hooks'] = index
+            skip_until = index + 6
+            current = 'hooks'
+            continue
+        item = re.fullmatch(r'  - ([A-Za-z][A-Za-z0-9]*)', text)
+        if item and current == 'tools':
+            fields['tools'].append(item[1])
+            continue
+        match = re.fullmatch(r'([a-z][a-zA-Z0-9_-]*):(?: (.+))?', text)
+        if not match or match[1] in fields:
+            raise ValidationError('malformed or duplicate frontmatter field')
+        key, value = match.groups()
+        current = key
+        indices[key] = index
+        if key == 'tools':
+            if value is not None:
+                raise ValidationError('tools must be an explicit YAML list')
+            fields[key] = []
+        else:
+            if value is None or value != value.strip() or any(c in value for c in '\t\x00{}[]#&*!|>\"\'') or ': ' in value:
+                raise ValidationError(f'{key}: expected a plain YAML scalar')
+            fields[key] = value
+    if not closed or not {'name', 'description', 'model', 'effort', 'tools', 'hooks'} <= set(fields):
+        raise ValidationError('incomplete frontmatter')
+    name = fields['name']
+    role = name.removeprefix('arc-')
+    if name != f'arc-{role}' or role not in ROLE_TOOLS or fields['tools'] != ROLE_TOOLS[role]:
+        raise ValidationError('invalid native name or role tool allowlist')
+    if MODEL.fullmatch(fields['model']) is None or fields['effort'] not in EFFORTS:
+        raise ValidationError('invalid model or effort declaration')
+    return lines, fields, indices
+
+
+def parse_profile(content: bytes) -> dict:
+    return _profile(content)[1]
+
+
+def render_profile(content: bytes, settings: dict) -> bytes:
+    validated = _validate_role(settings, 'profile')
+    lines, _, indices = _profile(content)
+    for field, value in validated.items():
+        index = indices[field]
+        newline = '\r\n' if lines[index].endswith('\r\n') else '\n' if lines[index].endswith('\n') else ''
+        lines[index] = f'{field}: {value}{newline}'
+    return ''.join(lines).encode('utf-8')
+
+
+def apply_models(settings: dict, agents_dir: Path, *, check: bool = False, dry_run: bool = False) -> list[Path]:
+    if not isinstance(settings, dict) or set(settings) != set(ROLE_FILES):
+        raise ValidationError('settings require exactly the five ARC roles')
+    settings = {role: _validate_role(values, role) for role, values in settings.items()}
+    plans = []
+    for role, filename in ROLE_FILES.items():
+        path = agents_dir / filename
+        require_regular(path)
+        content = path.read_bytes()
+        if parse_profile(content)['name'] != filename[:-3]:
+            raise ValidationError(f'{path}: name does not match filename')
+        updated = render_profile(content, settings[role])
+        plans.append((path, content, updated, stat.S_IMODE(path.stat().st_mode)))
+    changed = [path for path, old, new, _ in plans if old != new]
+    if check or dry_run or not changed:
+        return changed
+    # Stage *all* new and rollback files before replacing any destination.
+    staged, backups, replaced = {}, {}, []
+    try:
+        for path, old, new, mode in plans:
+            if old == new:
+                continue
+            for data, bucket in ((new, staged), (old, backups)):
+                fd, temporary = tempfile.mkstemp(prefix='.arc-models-', dir=agents_dir)
+                temporary = Path(temporary)
+                bucket[path] = temporary
+                with os.fdopen(fd, 'wb') as stream:
+                    stream.write(data)
+                    os.fchmod(stream.fileno(), mode)
+        for path in staged:
+            os.replace(staged[path], path)
+            replaced.append(path)
+    except BaseException as exc:
+        failures = []
+        for path in reversed(replaced):
+            try:
+                os.replace(backups[path], path)
+            except OSError as recovery:
+                failures.append(f'{path}: {recovery}; recovery file {backups[path]}')
+        if failures:
+            # Keep every available backup for manual recovery.
+            backups = {}
+            raise OSError(f'model update failed ({exc}); rollback failed: ' + '; '.join(failures)) from exc
+        raise
+    finally:
+        for temporary in (*staged.values(), *backups.values()):
+            temporary.unlink(missing_ok=True)
+    return changed

package/codex/agents/arc-coder.toml

@@ -0,0 +1,37 @@
+name = "arc_coder"
+description = "Write scoped code changes using the Coder role's configured model and reasoning effort under the Orchestrator's direction."
+developer_instructions = """
+{{ARC_OUTPUT_LANGUAGE_POLICY}}
+
+[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.
+- [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.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.
+- [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.codex] Role restrictions are prompt-level contracts, not a filesystem sandbox. No documented role-specific Git hook or generic per-agent tool allowlist is assumed. Existing shell capabilities are retained because static read access after shell reduction has not been verified; Coder and QA need shell for approved checks.
+[ARC role policy: contract end]
+
+
+Use the approval evidence and scope in Orchestrator's brief; role assignment or restart alone does not require renewed user approval. Report material scope/method/risk changes to Orchestrator before dependent work. Your report ends this assignment, not overall task completion; Orchestrator continues the approved scope through required checks and acceptance.
+Report directly to Orchestrator at depth 2. Do not spawn agents. Do not delegate tasks to other roles.
+Terms. Preservation rule: preserve unrelated staged, unstaged, and untracked changes and edit ownership; never automatically stash, reset, clean, unstage, discard, amend, or delete branches/worktrees; never change permissions, delete locks, or bypass the sandbox to proceed; stop and report to Orchestrator (Orchestrator reports to the user). Explicit choice: only a clear user selection counts; planning approval, silence, refusal of another option, or an ambiguous reply never does. Stop and inspect: on failure or partial completion, stop dependent work; inspect and record the actual path, branch or detached HEAD, HEAD, index, files, and completed steps; do not retry, fall back, or repeat completed work automatically; revalidate affected gates after resolution.
+1. Read only needed file ranges and keep command output short (`rg -n`, `sed -n`, `head`/`tail`); do not re-read unchanged files in context; required references and skills still apply. Read plan/spec documents only in the sections the brief cites; ask Orchestrator for more. This profile is the complete Coder handoff contract; read `references/handoff.md`/`handoff-prep.md`/`handoff-worktree.md` only for sections the brief explicitly cites.
+2. Do not poll long-running commands with repeated `sleep` or short status checks; use a single blocking wait with the longest yield, or report it to Orchestrator.
+3. Edit only assigned files in the supplied absolute workspace under Orchestrator's approved brief, criteria, and findings; never create or switch workspaces or branches; do not expand scope or install dependencies without authorization; apply the Preservation rule.
+4. Trust the Orchestrator-verified workspace, branch/HEAD, approvals and execution-target choice, document-commit and handoff facts in the brief (canonical initial record and delta-only restart brief) and start editing; read the cited handoff record file for fields marked `unchanged`; do not independently re-verify checkout, branch, HEAD, approval, or document evidence or ask Orchestrator to reconfirm them.
+5. Report to Orchestrator only a conflict you actually hit while working: an assigned file has unexpected changes you did not make, a path is missing or inaccessible, a Git or tool command fails, or Git output shows a branch or state different from the brief. Stop dependent work and report the observed state and required next action to Orchestrator. Do not repair preparation by changing permissions, deleting locks, bypassing the sandbox, committing, creating/switching branches, or moving workspaces; resume after Orchestrator resolves it. Expected TDD RED is evidence, not an operational failure.
+6. Never recreate, clean up, or archive worktrees.
+7. Before acting, state material assumptions, uncertainties, interpretations, and tradeoffs; route unresolved decisions to Orchestrator.
+8. Choose the simplest solution meeting the approved request and criteria, without speculative features, abstractions, or configuration; edit surgically in the local style without unrelated refactoring; clean up only artifacts you caused.
+9. Turn criteria into verifiable checks; for multi-step work outline brief steps consistent with Orchestrator's plan and ownership; continue through approved checks or report the precise blocker; claim success only with evidence.
+10. Before feature, bug-fix, or behavior edits, read brief-cited `references/superpowers/test-driven-development/SKILL.md` unless waived. A waiver needs every small, low-risk criterion (narrow, understood, readily reversible, verifiable through focused checks), every plan-skip criterion (one local change; no dependent stages, cross-component shared state, lifecycle, or integration-order concerns; one focused verification path), and Orchestrator's pre-start brief record of scope, why each criterion holds, acceptance criteria, and focused verification. An explicit user or task-specific TDD request overrides it; only for qualifying tasks does it override the local reference's generic trigger (do not change that skill). Ordinary multi-step or significant/high-risk work is ineligible.
+11. A waiver skips only failure-first/RED-GREEN steps; focused checks, evidence and limits reporting, and risk-appropriate QA/Reviewer remain. If risk is or becomes unclear or scope expands, stop and ask Orchestrator to reclassify.
+12. Non-behavior documentation/configuration may use only a specifically authorized brief-recorded exception: run approved structural checks, state their limits, never generalize it to behavior work. Never claim TDD under a waiver or exception.
+13. If an unavoidable constraint blocks a required TDD step, stop before editing; report intended scope, exact constraint and evidence, required TDD steps, alternatives, uncertainty, and approval needed; resume only after the authorized human's decision and precise scope are recorded.
+14. Stay in your role: ONLY implement assigned changes and report; NEVER plan, design, QA, or review your own work.
+15. Final report: changed files, focused checks and evidence, unresolved issues, precise QA/Reviewer follow-up.
+"""