@yunhozz/arc 0.1.0 → 0.1.2

package/MANIFEST.sha256

@@ -1,4 +1,4 @@
-6ed88ea4d7d6aada81573fff39a3f4c47aea19c8625e5c65550e1c1f9e3a1583  README.md
+cbd254348f60c8610d0e5c4b8216c9772c0bd5dbfef324796da516b87054b06e  README.md
 484d9b2002ce542c87589bb719d644d3762706aad28a6ee010024875f8cc00e2  bin/arc.mjs
 a1afdc6e5f37cc7cd6597e0406635c577175fb525d812ce7eac248efa7758ccd  claude/agents/arc-coder.md
 ce1936983accc15ee529416dd67bd48abdad678bfebc16d240869e8b96644379  claude/agents/arc-planner.md
@@ -70,7 +70,7 @@ c8b5bc4fc7ecd8d9e67ddc63cbee4a3e185919acaa0dbc387f178d55e5811e23  lib/policy/rol
 4174dfcfcd4d69a5486b91108ec03279cfd50644109c7457aa87f9ac877fb1ac  lib/safe-fs/native.mjs
 ff9c33c8b3c2bd466d54ffbe4c7139ccd87c79c7de34a6c4cde92e9f6e9b42d2  native/binding.c
 205bedc1dee1a9ffa58124c6e21256a1f0cbe24f06f7c8d7cb0b99524cfab9d0  native/binding.gyp
-01f34babd4982a40465744d96c4a3a614f229e0c7cf466f9846f80e91db47ab2  package.json
+af31bae3e14711fe2d972a1d328222c60a1b58c23f28db87c907cb55c57e0f15  package.json
 208c65cfde244d39ce45c3cf1b0acb128f04d21199b6b3fb5466e62db5b64af9  prebuilds/darwin-arm64/arc_safe_fs.node
 572887ac794d10a8b921d8168ea2328e31f05b45987611ff02c83114dba901af  prebuilds/darwin-x64/arc_safe_fs.node
 2bb9443021f9d873712b26321de733eddd6794c45f0bc79e2d5dc98669196635  prebuilds/index.json

package/README.md

@@ -1,266 +1,62 @@
-# 🤖 ARC (Agent Role Coordination)
+# 🤖 ARC — Agent Role Coordination
 
-ARC coordinates research, design, implementation, and verification in Codex and Claude Code.
-The Orchestrator assigns work and accepts results.
+ARC brings clear roles, scoped handoffs, and verification to work in Codex and Claude Code.
 
-![Task flow diagram](docs/images/role-flow.svg)
+![ARC workflow](docs/images/role-flow.svg)
 
-## 🚀 Install and manage ARC
+## 👥 Roles
 
-Start interactive installation without a global CLI:
-
-```sh
-npx --yes @yunhozz/arc
-```
-
-Choose target → preset → total limit → concurrent limit → output language with Up/Down and Enter.
-For non-interactive installation, supply target, preset, and language:
-
-```sh
-npx --yes @yunhozz/arc --target codex --preset balanced --language ko
-```
-
-The same package can manage an existing installation:
-
-```sh
-npx --yes @yunhozz/arc preset smart --target codex
-npx --yes @yunhozz/arc uninstall --target codex
-```
-
-These npx commands do not install a global `arc` executable. To install the CLI globally:
-
-```sh
-npm i -g @yunhozz/arc
-arc
-arc preset smart --target codex
-arc uninstall --target codex
-```
-
-The npm command installs the CLI only. Run bare `arc` to install the harness and register zsh
-completion. For the current shell, run `eval "$(arc completion zsh)"`; for bash, use
-`eval "$(arc completion bash)"`.
-
-Bare `arc` starts installation; the `install` subcommand has been removed. A repository checkout
-also supports `./install.command` with the same installation options.
-
-### 🧰 Requirements and options
-
-| Requirement | Supported |
-|---|---|
-| Runtime | Node.js 22+ with npm (`npx`), Git, network access |
-| macOS | 13+, arm64/x64 |
-| Linux | glibc 2.28+, arm64/x64 |
-| Unsupported | Windows, musl Linux |
-
-Bundled native files handle installation; Python, a compiler, and `node-gyp` are unnecessary.
-
-| Installation option | Purpose |
-|---|---|
-| `--target <claude\|codex\|all>` | Installation target; interactive default: Claude |
-| `--preset <economy\|balanced\|smart>` | Role model preset; interactive default: Balanced |
-| `--language <en\|ko>` | English or 한국어; the final question |
-| `--max-total-subagents <count>` | Created subagents per session/tree; initial default: 100 |
-| `--max-concurrent-subagents <count>` | Simultaneous subagents; initial default: 5 |
-| `--check` | Validate payload and paths without writing |
-| `--dry-run` | Preview writes without applying them |
-| `--skip-global` | Skip global instructions, native configuration, and `.zshrc` access |
-| `--help`, `--version` | Show usage or version without loading native files |
-
-Check and dry-run validate included references locally, without network access or upstream freshness checks.
-For example:
-
-```sh
-npx --yes @yunhozz/arc --target all --preset smart --language en --check
-./install.command --target claude --preset economy --language ko --dry-run
-```
-
-### 🌐 Output language
-
-Each target stores `en` or `ko` in `skills/arc/settings.toml`. The language applies to the Orchestrator
-and all five roles, including progress, reports, and planning documents. An explicit user language request
-overrides this default; the input language alone does not change it. Code, commands, paths, identifiers,
-literals, quotations, and actual tool output retain their original form. Open a new session to load changed policies.
-
-For `all`, one selection applies to both targets. A common existing language is preselected; otherwise English
-is selected. `--skip-global` omits the global instruction block while retaining skill and role language policies.
-
-### 📁 Installed files and refreshes
-
-| Target | Location and managed files |
+| Role | Responsibility |
 |---|---|
-| Codex | `~/.codex` (or `CODEX_HOME`): `skills/`, `agents/`, `AGENTS.md`, `config.toml` |
-| Claude Code | `~/.claude`: `skills/`, `agents/`, `CLAUDE.md`, `settings.json` |
-
-The installer preserves content outside the managed `arc:begin`/`arc:end` instruction block.
-For Codex, it sets `min_wait_timeout_ms = 120000` and `default_wait_timeout_ms = 300000` when
-`[features.multi_agent_v2]` is a standalone table; otherwise it prints manual guidance.
-Claude requires the default `~/.claude` configuration directory.
-
-Every harness installation fetches fresh references per target from the
-[obra/superpowers](https://github.com/obra/superpowers) default branch and publishes full
-`brainstorming`, `writing-plans`, and `test-driven-development` trees under
-`skills/arc/references/superpowers/`. Roles read this local Markdown and its companion files.
-Existing global/shared copies and links remain untouched.
-
-Git and network access are required for harness installation; collection never executes upstream
-scripts or hooks. npm installation has no lifecycle hooks and does not fetch references or edit shell
-configuration. Harness installation stages references without rewriting package files, so read-only
-packages work. Collection or publication failure fails the target installation.
-
-Bundled references retain their
-[MIT license](https://github.com/obra/superpowers/blob/main/LICENSE), including Jesse Vincent's notice.
-`provenance.json` records revision, timestamp, hashes, and relative links for local consistency checks;
-it does not authenticate upstream or a malicious local rewrite.
-
-Reinstallation replaces managed ARC files and local model edits, preserves ARC limits, and creates no
-persistent backup. All selected target paths are checked before writing. Harness targets then install
-independently in Codex → Claude order: a later failure retains earlier success. Inspect per-target status
-and any `Residual path:` before recovery or retrying only the failed target. Concurrent installation,
-preset changes, or removal against the same target are unsupported.
+| Orchestrator | Routes work and accepts results |
+| Scouter | Researches and explores sources |
+| Planner | Drafts designs, specs, and plans |
+| Coder | Implements assigned changes |
+| QA | Runs assigned verification |
+| Reviewer | Independently reviews changes |
 
-## ⚙️ Models and presets
+## 🚀 Quick start
 
-The Orchestrator uses the current conversation's model. Other roles use `models.toml`:
-[Codex](codex/skill/models.toml) · [Claude Code](claude/skill/models.toml).
+**Requirements:** Node.js 22+, npm, Git, and network access. Supported platforms are macOS 13+ and Linux with glibc 2.28+ (arm64 or x64). Windows and musl Linux are not supported. Python, a compiler, and `node-gyp` are not required.
 
-Both schemas use `version = 1`, a root `preset`, and `roles.<role>.economy`, `.balanced`, and `.smart` variants.
-Codex entries use `model` and `model_reasoning_effort`; Claude entries use `model` and `effort`.
-Installation keeps all three variants and validates inactive ones too. Legacy schemas require migration
-to the linked schema or reinstallation.
-
-Switch presets without reinstalling or downloading references:
+Run the interactive installer:
 
 ```sh
-arc preset smart --target codex
-arc preset balanced --target all --check
-arc preset economy --target claude --dry-run
+npx --yes @yunhozz/arc
 ```
 
-Use the npx form above if the CLI is not globally installed. In a terminal, omitted preset and target
-are selected with arrow keys; non-interactive runs require both. Switching preserves custom model variants,
-profile instructions, language, limits, and global settings. It also reapplies model fields that have drifted.
-All targets are checked first, then each updates atomically in Codex → Claude order. A later failure keeps
-earlier success; failed target writes are rolled back and any remaining recovery paths are reported.
-Open a new session to load changed profiles.
-
-After editing an installed model file, apply its active preset with `arc preset`, or use the optional
-Python 3.11+ tool:
+Choose a target, model preset, agent limits, and output language. For a non-interactive install, provide the target, preset, and language:
 
 ```sh
-python3 ~/.claude/skills/arc/scripts/apply-models.py
-python3 ~/.codex/skills/arc/scripts/apply-models.py
+npx --yes @yunhozz/arc --target codex --preset balanced --language en
 ```
 
-## 👥 Subagent limits
-
-TTY installation prompts for omitted limits. Enter keeps each target's current value (or the initial defaults:
-100 total and 5 concurrent); a typed value applies to all selected targets. Non-interactive installation
-preserves omitted values.
-
-The ARC policy counts every created agent in one session/tree, including completed agents. Reuse does not count;
-fresh replacements do. This is prompt-level policy, not a hard runtime limit, and actual platform capacity may be
-lower. New settings apply to new sessions. See the operating guides for platform-specific configuration details.
-
-## 👥 Roles and workflow
-
-Read [How the ARC harness operates](docs/harness-operation.md) for responsibilities, approval and preparation,
-dependency scheduling, verification, commits, refresh boundaries, and recovery.
-
-ARC scales the workflow to each task's depth and risk:
+## ⚙️ Common options
 
-| Task depth and difficulty | Workflow |
+| Option | Purpose |
 |---|---|
-| Simple, low risk: narrow scope and clear checks | When eligible, the Orchestrator handles the change directly and runs focused checks; otherwise, a Coder makes the change and the Orchestrator verifies it. |
-| Ordinary implementation or behavior change | Approve any required design or plan documents, then assign a fresh Coder followed by fresh QA. The Orchestrator reviews the evidence and accepts the result. |
-| Complex or significant risk: shared contracts, state or lifecycle; security; data loss; public interfaces; costly installation or deployment | Approve required documents and preparation. For planned work, each task follows Coder → fresh QA → acceptance and commit, followed by an independent Reviewer on the full change. For unplanned work, use Coder → fresh QA → Reviewer → acceptance. |
+| `--target <claude\|codex\|all>` | Choose where to install |
+| `--preset <economy\|balanced\|smart>` | Choose specialist model settings |
+| `--language <en\|ko>` | Set the default output language |
+| `--max-total-subagents <count>` | Set the session-wide agent limit (default: 100) |
+| `--max-concurrent-subagents <count>` | Set the simultaneous agent limit (default: 5) |
+| `--check` | Validate without writing changes |
+| `--dry-run` | Preview changes without applying them |
+| `--skip-global` | Skip global instructions, native settings, and shell configuration |
 
-Design depth (Spike, Bounded, Architectural) determines which design documents are needed; task risk determines
-verification strength. Ready independent tasks may run in parallel within policy and runtime capacity. Coder
-completion alone does not release dependents. Codex supports managed worktrees; Claude v1 uses the current checkout.
+## 🔁 Manage ARC
 
-승인된 범위의 실행 요청은 같은 범위의 인계·재시작에도 유효합니다. Spike가 조사만 요청된 경우에는
-질문에 대한 증거·한계·불확실성을 보고하면 완료됩니다. 조사와 구현을 함께 요청했고 전체 범위가 충분히
-구체적인 경우에는 조사 결과 이후에도 승인된 구현, 필요한 검증, 수락, 결과 보고까지 진행합니다.
-중대한 범위·방법·위험 변경이나 새로운 결정이 생기면 영향을 받는 작업을 보류합니다.
-
-Bounded의 spec/plan 생략은 검증 위험이나 완료 책임을 줄이지 않습니다. 단일 로컬 변경, 의존 단계와
-공유 상태·수명주기·통합 순서 문제가 없음, 하나의 집중 검증 경로라는 plan 생략 조건을 기록합니다.
-필요한 문서·대상 준비·인계 조건을 충족한 뒤에는 승인된 남은 작업을 사용자에게 다시 제안만 하고 멈추지 않습니다.
-자세한 승인·완료 계약과 플랫폼별 책임 위치는 운영 문서에서 확인할 수 있습니다.
-
-## 📚 Operating guides
-
-| Environment | Guide | References |
-|---|---|---|
-| Codex | [Operating guide](codex/skill/SKILL.md) | [Planning](codex/skill/references/planning.md) · [Handoff](codex/skill/references/handoff.md) · [Verification](codex/skill/references/verification.md) |
-| Claude Code | [Operating guide](claude/skill/SKILL.md) | [Planning](claude/skill/references/planning.md) · [Handoff](claude/skill/references/handoff.md) · [Verification](claude/skill/references/verification.md) |
-
-## 🗑️ Remove ARC
-
-```sh
-arc uninstall --target codex
-arc uninstall --target all --dry-run
-arc uninstall --target claude --skip-global
-```
-
-Use the npx form above without a global CLI. A terminal prompts for an omitted target;
-non-interactive removal requires `--target`. Removal deletes the selected ARC skill (including language
-and limit settings), five role profiles, and managed instruction block, including edited ARC files.
-It preserves external skills, other profiles, Codex wait settings, native concurrency keys, and shared
-shell completion registration. No persistent backup is created.
-
-Remove the global CLI separately:
+Change the preset or remove an installation without a global CLI:
 
 ```sh
-npm uninstall -g @yunhozz/arc
+npx --yes @yunhozz/arc preset smart --target codex
+npx --yes @yunhozz/arc uninstall --target codex
 ```
 
-npm package removal leaves the installed harness configuration and shared completion block in place.
-`uninstall` remains available to remove that deployed configuration.
-
-
-## 역할 정책과 권한 경계
-
-ARC는 Orchestrator, Scouter, Planner, Coder, QA, Reviewer의 여섯 역할군을 정의합니다.
-배포되는 전문 에이전트 프로필은 기존 다섯 개이며, Orchestrator는 최상위 세션 역할입니다.
-`lib/policy/role-policy.json`이 공통 정책 원천입니다. `npm run update:role-policy`로 양 플랫폼의
-관리 영역을 생성하고 `npm run check:role-policy`로 오래된 산출물을 확인합니다. 관리 영역 밖의
-절차와 모델 설정은 보존하며, 모델 렌더러는 모델 관련 필드만 변경합니다.
-
-전문 역할은 정상 작업과 복구 중에도 stage, commit, push, merge, rebase, reset, branch 생성·전환,
-worktree 생성·제거를 실행할 수 없습니다. Orchestrator의 위임도 이 권한을 확대하지 않습니다.
-Scouter는 정적 조사, Planner는 응답으로 초안 반환, Coder는 배정 파일 구현과 집중 검사,
-QA는 승인된 검사와 제한된 임시 산출물, Reviewer는 독립적인 정적 검토를 담당합니다.
-Orchestrator가 검사 증거와 기준을 확인해 수락하고 작업별 집중 커밋을 생성합니다.
-push·merge·deploy·publish·외부 메시지는 해당 행위·범위·대상에 대한 명시적인 사용자 권한이 필요합니다.
-
-유의미하거나 위험도가 높은 작업에 계획이 없으면 Coder → QA → 최종 전체 Reviewer → Orchestrator 수락을
-따릅니다. 계획이 있으면 각 작업을 Coder → 필요한 fresh QA → Orchestrator 수락·커밋으로 진행하고,
-모든 작업과 필요한 QA가 끝난 뒤 Reviewer가 최종 전체 변경을 한 번 검토합니다. Reviewer는 매 커밋의
-필수 게이트가 아닙니다. 최종 계획 Reviewer 발견 사항은 Coder → Reviewer로 재검토합니다.
+## 🎛️ Models and language
 
-Codex의 역할 제한은 prompt 수준 계약이며 완전한 sandbox가 아닙니다. 역할별 Git hook이나 일반적인
-custom-agent 도구 allowlist를 제공한다고 가정하지 않습니다. shell 축소 후 정적 읽기 유지가 검증되지
-않았으므로 기존 shell 기능을 보존합니다. Claude는 기존 역할별 tools allowlist와 다섯 전문 프로필의
-`PreToolUse` hook을 함께 사용합니다. hook은 Orchestrator 전역 설정에 추가하지 않습니다.
-설치된 `skills/arc/hooks/git-policy.json`은 공통 정책에서 생성되며 패키지 manifest와 필수 자산 검사에
-포함됩니다. installer가 hook을 최종 설치 절대경로로 연결하므로 현재 작업 디렉터리에 의존하지 않습니다.
-모델·effort를 다시 적용해도 hook과 도구 목록은 보존됩니다.
+The Orchestrator uses the current conversation's model. The five specialist roles use the selected preset from their platform model file: [Codex](codex/skill/models.toml) · [Claude Code](claude/skill/models.toml). The configured language applies across ARC; an explicit user language request takes precedence.
 
-Claude hook 실행 환경의 `PATH`에 Node.js 22+가 있어야 합니다. 직접 Git 호출, `git -C`, `--git-dir`,
-경로로 지정한 Git 실행 파일, `sh -c`·`bash -c`, `&&`·`||`·`;`·pipeline 조합을 문자열로 분류합니다.
-허용된 조회 옵션만 통과하며 알 수 없는 Git subcommand·옵션, 지원하지 않는 shell 구문은 거부합니다.
-조회 목록은 status, diff, log, show, rev-parse, ls-files, ls-tree, branch 조회, config 조회,
-worktree list, remote 조회입니다. Git 변경이나 연결 명령의 일부가 금지되면 전체 shell 요청을 거부합니다.
-검사 실행(`npm test` 등)은 그대로 허용됩니다.
+## 📚 Guides
 
-이 guard는 임의 프로그램의 효과를 판정하는 sandbox가 아닙니다. alias, 함수, 변수 확장, 동적 코드,
-다른 프로그램이나 스크립트 내부에서 실행하는 Git을 완전히 분석하지 않습니다. 기존 Git 설정의 외부
-프로그램 실행 효과도 판정하지 않습니다. 간접 실행으로 역할 금지를 우회해서는 안 됩니다.
-잘못된 stdin·누락 command·정책 읽기 오류는 `PreToolUse` deny 응답을 반환합니다. bootstrap 로드 실패는
-종료 코드 2로 차단을 요청합니다. Node 자체 실행 실패나 Claude의 hook 실행 오류 처리는 플랫폼 동작에
-의존하므로 모든 오류에서 fail-closed라고 보장하지 않습니다. hook 오류나 정상 검사 차단은 우회하지 말고
-Orchestrator에게 보고하세요. [Claude hook 문서](https://code.claude.com/docs/en/hooks)를 참고하세요.
-설치·업데이트된 프로필은 새 에이전트를 시작할 때 적용됩니다. 이미 실행 중인 에이전트가 정책을
-자동으로 다시 읽거나 강제 적용받는다고 보장하지 않습니다. native 플랫폼에서의 실제 준수 여부는
-생성 일관성·프로필 파싱 같은 구조 검사와 구분해야 합니다.
+[How the ARC harness operates](docs/harness-operation.md) · [Codex guide](codex/skill/SKILL.md) · [Claude Code guide](claude/skill/SKILL.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunhozz/arc",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"