@ps-neko/nekowork 0.1.0-alpha.0

package/AGENTS.md

@@ -0,0 +1,112 @@
+# AGENTS.md
+
+> 외부 하네스(Codex CLI, OpenAI 표준, GitHub agents) · 사람을 위한 풀 사양. CLAUDE.md 의 압축 버전이 아니라 정전(canon) 문서.
+
+## You Are
+
+You are running with HARNESS — a multi-harness AI development agent runtime. Your role depends on which agent identity you were dispatched with. Read the matching `agents/<name>.md` for your full prompt and constraints.
+
+## 역할 정전(Canonical Roles)
+
+각 에이전트는 `agents/<name>.md` 의 frontmatter 로 정의된다. 핵심 필드:
+
+```yaml
+name: <id>
+description: <한 줄>
+provider: claude | codex | gemini | auto
+model: opus | sonnet | haiku | gpt-5-codex | gemini-2.5-pro
+level: 0 | 1 | 2 | 3      # 0=info, 1=helper, 2=workflow, 3=critical
+disallowedTools: [...]    # Opus 는 기본 Write/Edit 차단
+trigger: [...]            # 키워드 또는 stage 이름
+hand_off_to: [...]
+fact_forcing: true|false  # PreToolUse 사실 조사 강제 여부
+```
+
+## Workflow Surface Policy
+
+- `skills/` 가 정전 워크플로우 표면이다. 새 워크플로우는 `skills/` 에 먼저 만든다.
+- `commands/` 는 legacy slash-entry 호환 표면이다. 신규 추가 금지, 점진 마이그레이션.
+- `agents/` 는 페르소나 카탈로그다. 워크플로우는 `skills/` 에서 정의하고 에이전트는 `skills/` 가 호출한다.
+
+## 7단계 풀사이클 (claude-led-codex-review)
+
+| 단계 | 담당 | 입력 | 출력 |
+|---|---|---|---|
+| 1 ideate | research, planner | 사용자 한 줄 요청 | `handoffs/01-ideate.md` |
+| 2 plan | planner (opus) | 1의 출력 | `prd-<id>.md` + `test-spec-<id>.md` |
+| 3 implement | executor (sonnet) | 2의 출력 + TDD | git diff |
+| 4 self-review | code-reviewer (opus, ro) | git diff | `handoffs/04-self-review.md` (issues JSON 요약) |
+| 5 codex-review | codex-reviewer (별도 세션) | diff + 04 + PRD | `handoffs/05-codex-review.md` |
+| 6 codex-challenge | codex-challenger (별도 세션, --secure) | diff + 04 + 05 | `handoffs/06-challenge.md` |
+| 7 ship | doc-writer + git-master | 모든 핸드오프 | PR + CHANGELOG |
+
+## 라우팅 결정 규칙
+
+- **eco mode**: opus → sonnet, sonnet → haiku (단 단계 4·5는 sonnet floor).
+- **risk escalation**: auth/crypto/payment 디렉터리 변경 → security-reviewer 필수, --secure 자동 활성.
+- **blast radius**: 변경 파일 ≥ 20 → code-reviewer (opus) 필수.
+- **round limit**: 단계 5/6 round ≥ 3 → human gate.
+
+## 권한 매트릭스
+
+| Tool | architect | planner | executor | code-reviewer | codex-reviewer | security-reviewer |
+|---|---|---|---|---|---|---|
+| Read | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Write | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ |
+| Edit | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ |
+| Bash | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ |
+| Network | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ |
+
+## 핸드오프 표준
+
+```markdown
+# Handoff: <stage>
+
+**Decided**: ...
+**Rejected**: ...
+**Risks**: ...
+**Files**: ...
+**Remaining**: ...
+```
+
+10~20줄 한도. 자유 산문 금지. JSON 첨부 가능 (`schemas/handoff.schema.json`).
+
+## State Management
+
+- `.harness/state/sessions/<id>/prd.json` — acceptance criteria + passes 플래그
+- `.harness/state/sessions/<id>/progress.txt` — append-only 학습 누적
+- `.harness/state/sessions/<id>/notepad.md` — 자유 메모
+- `.harness/state/sessions/<id>/handoffs/<NN>-<stage>.md` — 단계 간 결정 로그
+
+PreCompact 훅이 컴팩션 직전 자동 dump. SessionStart 에서 active 세션 발견 시 prd + 가장 최근 핸드오프 2개만 inject.
+
+## 보안 12-item Minimum Bar
+
+ECC `the-security-guide.md` 차용:
+
+1. 에이전트 ID 와 개인 계정 분리
+2. Short-lived scoped credentials (OIDC 권장)
+3. Untrusted work 는 devcontainer / VM / 원격 샌드박스
+4. Outbound network 기본 deny
+5. Secret-bearing path 읽기 차단
+6. 파일 / HTML / 스크린샷 / 링크 sanitize 후 privileged agent 에 전달
+7. unsandboxed shell, egress, deploy, off-repo write 는 approval 필수
+8. tool calls / approvals / network attempts 모두 로깅
+9. process-group kill + heartbeat dead-man switch
+10. 영속 메모리는 좁고 처분 가능하게
+11. 카탈로그(skills, hooks, MCP, agents)도 supply chain 으로 스캔
+12. MCP 서버는 SemVer 핀
+
+## 외부 하네스 호환
+
+- **Claude Code**: `.claude/` 빌드 산출물 + `.claude-plugin/plugin.json`
+- **Codex CLI**: `.codex/config.toml` (TOML, `[mcp_servers.*]`, `[profiles.review]` 등)
+- **Cursor**: `.cursor/hooks.json` (이벤트명 어댑터: `beforeShellExecution` 등)
+- **Gemini CLI**: `.gemini/GEMINI.md` (요약 + 스킬 포인터)
+- **OpenCode**: `.opencode/opencode.json` (단일 JSON)
+
+빌드 타임 투영은 `scripts/build-<harness>.{js,ts}` 가 담당.
+
+## 변경 절차
+
+이 문서의 핸드오프 표준 / 라우팅 규칙 / 권한 매트릭스 변경은 RULES.md 변경과 함께 진행한다.

package/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+> Claude Code 부팅 컨텍스트. 자동 갱신 영역은 마커 사이만 갈아낀다. 사용자 작성 영역은 보존된다.
+
+## 사용자 작성 영역 (수동, 보존)
+
+이 프로젝트는 HARNESS 자체 코드베이스다. 프로젝트 디폴트 자연어는 한국어 (외부 컨트리뷰터의 영어 PR 환영). 사용자가 자기 환경에 글로벌 룰 (`~/.claude/CLAUDE.md` 등) 을 두고 있다면 그쪽이 우선한다.
+
+## 자동 갱신 영역
+
+<!-- HARNESS:START version=0.1.0-alpha.0 -->
+<!-- 이 영역은 scripts/sync-claude-md.js 가 자동 갱신한다. 직접 편집 금지. -->
+
+## 카탈로그 요약
+
+- agents: 11
+- skills: 9
+- commands: 1 (legacy compat)
+- hooks: 5 (gateguard-fact-force, config-protection, quality-gate, pre-bash-dispatcher, persistent-mode)
+- profiles: core, developer, security, product, quality, frontend, testing, research, full
+- harnesses: claude, codex, cursor, gemini, opencode
+
+## 에이전트 → 모델 매트릭스
+
+| Agent | Provider | Model | Sandbox |
+|---|---|---|---|
+| architect | claude | opus | read-only |
+| planner | claude | opus | read-only |
+| executor | claude | sonnet | workspace-write |
+| code-reviewer | claude | opus | read-only |
+| codex-reviewer | codex | gpt-5-codex | read-only |
+| codex-challenger | codex | gpt-5-codex | read-only |
+| security-reviewer | claude | opus | read-only |
+| debugger | claude | sonnet | workspace-write |
+| test-engineer | claude | sonnet | workspace-write |
+| research | gemini | gemini-2.5-pro | read-only |
+| doc-writer | claude | haiku | workspace-write |
+
+## 핵심 명령어
+
+```bash
+harness install --plan --profile core      # 설치 dry-run
+harness ask "<task>"                       # question gate, no project mutation
+harness team "<task>"                      # read-only worker handoffs
+harness work "<task>"                      # single executor implement handoff
+harness verify "<task>" --session <id>     # Codex-only verification
+harness gate status --session <id>         # inspect or resolve HUMAN_GATE state
+harness ship "<task>" --session <id>       # ship/no-ship readiness handoff
+harness apply --session <id>               # apply verified SHIP_READY live-work diff
+harness run "<task>" --session <id>        # work -> verify -> ship, optional --apply
+harness review "<task>" [--secure|--fast|--no-ship]  # legacy full cycle
+harness review-cycle "<task>" [--secure|--fast|--no-ship]  # explicit legacy alias
+harness plan "<task>"
+harness self-review
+harness codex-review                       # 단계 5 단독
+harness sessions
+harness costs --since=7d
+```
+
+## State 경로
+
+- 세션: `.harness/state/sessions/<id>/{prd.json,progress.txt,notepad.md,handoffs/}`
+- 프로젝트: `.harness/project-memory.json` + `WORKING-CONTEXT.md`
+- 글로벌: `~/.harness/instincts/` + `.harness/costs.jsonl`
+
+## 매직 키워드 → 스킬 (명시 옵트인만)
+
+자동 활성 키워드 감지는 **사용**하지 않는다. 사용자 룰("확인 후 실행") 우선. 모든 스킬은 슬래시 명령(`/claude-led-codex-review`) 또는 CLI(`harness review`) 로 명시 호출.
+
+## 핸드오프 5필드
+
+Decided / Rejected / Risks / Files / Remaining — 10~20줄.
+
+<!-- HARNESS:END -->
+
+## 빌드 후 확인
+
+```bash
+node scripts/ci/check-markers.js   # 마커 일관성
+npm run validate:all               # 카탈로그 lint
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HARNESS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,283 @@
+# NEKOWORK
+
+Local-first AI development harness for Claude Code, Codex CLI, and Gemini CLI.
+
+[![harness-validate](https://github.com/Ps-Neko/NEKOWORK/actions/workflows/harness-validate.yml/badge.svg)](https://github.com/Ps-Neko/NEKOWORK/actions/workflows/harness-validate.yml)
+
+NEKOWORK is the product. HARNESS is the local runtime it packages: one source catalog, `agent.yaml`, projected into Claude Code, Codex CLI, Cursor, Gemini CLI, and OpenCode surfaces.
+
+Claude writes or plans, Codex challenges the result in a separate context, and human gates stop critical or repeated-risk changes.
+
+NEKOWORK is also a quality runtime: it combines disciplined development workflow, product-aware planning, read-only multi-agent review, independent Codex verification, Human Gate approval, and explicit apply control.
+
+Product principle:
+
+```text
+NEKOWORK = Claude work -> Codex verification -> Human Gate
+```
+
+NEKOWORK is not meant to become a large agent pack. Skills, hooks, profiles, and team modes are added only when they preserve the verification loop.
+
+## Three Paths
+
+Most users should start with the Beginner path. The other paths are for explicit phase control or legacy compatibility.
+
+1. Beginner: `doctor -> ask -> run -> gate`
+2. Advanced: `ask -> plan -> team -> work -> verify -> gate -> ship -> apply`
+3. Legacy: `review` / `review-cycle`
+
+## Why NEKOWORK
+
+NEKOWORK is for teams that want AI-assisted development without making the agent catalog the product. The default path keeps local auth, inspectable handoffs, single-executor writes, independent Codex verification, and Human Gate decisions in front of risky ship/apply steps.
+
+## Status
+
+- Current version: `0.1.0-alpha.0` public alpha candidate
+- Current package name: `@ps-neko/nekowork`
+- npm publishing: prepared for `npm publish --access public --tag alpha`, but not published until npm owner auth is available
+- Supported install path today: clone, submodule, or local repository integration
+- Future npm path is prepared; final publish requires `npm whoami` to succeed
+- Default mode: mock providers, no API keys, no provider CLI calls
+
+Current local verification:
+
+- `npm run lint`: pass
+- `npm test`: 238 tests pass
+- `npm audit --audit-level=moderate`: 0 vulnerabilities
+- `npm pack --dry-run --json`: pass
+
+## Quick Start
+
+Requirements:
+
+- Node.js 22+
+- npm
+- git
+
+Fastest no-API demo:
+
+```bash
+git clone https://github.com/Ps-Neko/NEKOWORK.git harness
+cd harness
+npm ci
+npm run demo:quick -- --cleanup
+```
+
+This creates a disposable target project and runs `doctor -> run -> gate status`. It uses mock providers and does not call Claude, Codex, Gemini, or paid APIs.
+
+Recommended path for most users:
+
+```bash
+git clone https://github.com/Ps-Neko/NEKOWORK.git harness
+cd harness
+npm ci
+node scripts/cli.js doctor --quick
+node scripts/cli.js ask "clarify a risky or ambiguous request" --session first-ask
+node scripts/cli.js run "implement, verify, and prepare ship readiness" --session first-run
+node scripts/cli.js gate status --session first-run
+```
+
+`run` executes `work -> verify -> ship`. It does not apply by default. `apply` is always explicit and requires a verified `SHIP_READY` live-work diff.
+
+Advanced path:
+
+```text
+ask -> plan -> team -> work -> verify -> gate -> ship -> apply
+```
+
+Legacy compatibility smoke:
+
+```bash
+node scripts/cli.js review "check the project setup" --no-ship --session first-smoke
+```
+
+The default review path uses mock providers, so it does not need API keys or provider CLIs.
+
+For the fuller first-run guide, see [docs/QUICKSTART.md](docs/QUICKSTART.md).
+
+To see the repository-based external project flow end to end:
+
+```bash
+npm run demo:external
+```
+
+To inspect small case-study targets, see [examples/trading-dashboard-mock](examples/trading-dashboard-mock), [examples/github-actions-hardening](examples/github-actions-hardening), and [examples/quality-lifecycle-smoke](examples/quality-lifecycle-smoke). They demonstrate financial UI, CI workflow, and quality lifecycle changes passing local checks while still preserving Codex verification, Human Gate policy, and explicit apply control.
+
+## What You Get
+
+```text
+doctor ... OK
+run workflow ... OK
+gate status ... OK
+Demo completed: verdict=approve_with_fixes, ship_ready=false, applied=false
+```
+
+Outputs are written under:
+
+```text
+.harness/state/sessions/<session-id>/handoffs/
+```
+
+## Use It In Another Project
+
+Recommended repository install shape:
+
+```bash
+cd <target-project>
+git submodule add https://github.com/Ps-Neko/NEKOWORK.git .harness-tool
+node .harness-tool/scripts/portability/simulate-port.js . --profile developer --verbose
+node .harness-tool/scripts/install-apply.js --profile developer --project-root .
+node .harness-tool/scripts/cli.js doctor --project-root . --quick
+node .harness-tool/scripts/cli.js plan "first NEKOWORK smoke" --project-root .
+```
+
+The HARNESS tool root stays in `.harness-tool/`. Session state, generated harness files, and git work happen in the target project root.
+
+For a disposable external-project walkthrough, see [docs/EXAMPLE-PROJECT.md](docs/EXAMPLE-PROJECT.md).
+
+## Live Provider Auth
+
+Live mode delegates auth to local CLI sessions:
+
+```bash
+claude auth status
+codex login
+gemini
+
+node scripts/cli.js review "live local smoke" --live --no-ship
+```
+
+Long-lived API key environment variables are blocked by default before provider CLI calls:
+
+- Claude: `ANTHROPIC_API_KEY`
+- Codex: `OPENAI_API_KEY`
+- Gemini: `GEMINI_API_KEY`, `GOOGLE_API_KEY`
+
+Use API-key paths only with explicit opt-in, for example `HARNESS_AUTH_ALLOW_ENV_OVERRIDE=1`.
+
+## Main Surface
+
+The public alpha surface is intentionally small:
+
+- `doctor`: inspect local readiness
+- `ask`: clarify goal, scope, risk, and success criteria without provider calls
+- `plan`: create a planning handoff
+- `team`: create read-only handoffs from multiple worker perspectives
+- `work`: let a single executor produce an implement handoff and isolated diff
+- `verify`: run Codex-only verification on a prior work handoff
+- `gate`: inspect, approve, or block a human gate for a session
+- `ship`: produce a ship/no-ship readiness handoff after Codex verification
+- `apply`: apply a verified `SHIP_READY` live-work diff to the target project
+- `run`: execute the decomposed wrapper, `work -> verify -> ship`, with optional apply
+- `review`: run the legacy full Claude-led/Codex-reviewed workflow
+- `review-cycle`: explicit compatibility alias for the legacy full review workflow
+- `install --plan` / `install --apply`: project generated harness surfaces
+
+Advanced features such as `team-lite`, `ralph`, `wait`, instincts, cost tracking, and the Rust supervisor are documented in [docs/ADVANCED.md](docs/ADVANCED.md).
+
+`plan` is recommended before `work` for larger changes. The current `run` command intentionally stays compact: it runs `work -> verify -> ship`, records acceptance criteria through `work`, and applies only when `--apply` is explicitly provided.
+
+Use `--profile quality` or `--profile security` on `work`, `verify`, and `run` when a task needs stronger evidence prompts. Add `--strict-quality` to `verify` or `run` when missing evidence or acceptance coverage should become a fix-required verdict before ship.
+
+## Catalog
+
+- Agents: 11
+- Skills: 9
+- Hooks: 5
+- Modules: 7
+- Profiles: `core`, `developer`, `security`, `product`, `quality`, `frontend`, `testing`, `research`, `full`
+- Harness targets: `claude`, `codex`, `cursor`, `gemini`, `opencode`
+
+Key skills:
+
+- `claude-led-codex-review`
+- `plan-eng-review`
+- `tdd-workflow`
+- `review`
+- `ship`
+- `ralph`
+- `security-hardening`
+- `release-readiness`
+- `porting`
+
+## Common Commands
+
+```bash
+node scripts/cli.js doctor
+node scripts/cli.js doctor --quick --gemini-smoke
+npm run demo:quick
+node scripts/install-plan.js --list
+node scripts/install-plan.js --profile developer
+node scripts/install-apply.js --profile developer --project-root <target>
+
+node scripts/cli.js ask "clarify a risky or ambiguous request"
+node scripts/cli.js plan "draft a safe implementation plan"
+node scripts/cli.js team "collect read-only worker handoffs" --workers planner,research,security,test --no-write
+node scripts/cli.js work "implement the planned change with one executor" --single-executor --session work-smoke
+node scripts/cli.js verify "verify the implemented change" --session work-smoke
+node scripts/cli.js verify "verify quality evidence" --profile quality --strict-quality --session work-smoke
+node scripts/cli.js gate status --session work-smoke
+node scripts/cli.js ship "prepare ship readiness" --require-clean-gates --session work-smoke
+node scripts/cli.js apply --session work-smoke
+node scripts/cli.js run "implement, verify, and prepare ship readiness" --session run-smoke
+node scripts/cli.js review "implement and review this change" --no-ship
+node scripts/cli.js review-cycle "legacy full-cycle compatibility smoke" --no-ship
+node scripts/cli.js review "security-sensitive change" --secure --no-ship
+
+npm run lint
+npm test
+npm audit --audit-level=moderate
+node scripts/repair.js --check
+node scripts/sync-claude-md.js --check
+node scripts/build-codemaps.js --check
+```
+
+## Release Gates
+
+Before any tag or public npm decision, run:
+
+```bash
+npm run lint
+npm test
+npm audit --audit-level=moderate
+node scripts/repair.js --check
+node scripts/sync-claude-md.js --check
+node scripts/build-codemaps.js --check
+npm run security:hardening
+npm pack --dry-run --json
+```
+
+`npm pack --dry-run --json` currently produces a package named like `ps-neko-nekowork-0.1.0-alpha.0.tgz`. It does not publish.
+
+## Documentation
+
+- [docs/QUICKSTART.md](docs/QUICKSTART.md) - first run and common paths
+- [docs/WHY-NEKOWORK.md](docs/WHY-NEKOWORK.md) - comparison and product positioning
+- [docs/PUBLISH-ALPHA.md](docs/PUBLISH-ALPHA.md) - public npm alpha release plan
+- [docs/DEMO.md](docs/DEMO.md) - sample command output and generated files
+- [docs/EXAMPLE-PROJECT.md](docs/EXAMPLE-PROJECT.md) - repository-based external project demo
+- [docs/case-studies](docs/case-studies) - real external project run evidence
+- [examples/trading-dashboard-mock](examples/trading-dashboard-mock) - standalone financial UI mock target and case-study evidence
+- [examples/quality-lifecycle-smoke](examples/quality-lifecycle-smoke) - standalone quality profile and strict-quality case-study evidence
+- [docs/SECURITY.md](docs/SECURITY.md) - local-first auth and safety model
+- [docs/ADVANCED.md](docs/ADVANCED.md) - advanced workflows and runtime features
+- [docs/SETUP.md](docs/SETUP.md) - local contributor setup and live provider smoke
+- [docs/PORTING.md](docs/PORTING.md) - using HARNESS in an external project
+- [docs/RELEASE-READINESS.md](docs/RELEASE-READINESS.md) - release and publish gates
+- [docs/RUNBOOK.md](docs/RUNBOOK.md) - operations guide
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - system architecture
+- [docs/PRODUCT-PRINCIPLES.md](docs/PRODUCT-PRINCIPLES.md) - product position, invariants, CLI phase semantics
+- [docs/AI-DEVELOPMENT-LIFECYCLE.md](docs/AI-DEVELOPMENT-LIFECYCLE.md) - quality runtime and disciplined AI development lifecycle
+- [docs/CORE-INVARIANTS.md](docs/CORE-INVARIANTS.md) - non-negotiable runtime safety rules
+- [docs/CLI-STAGES.md](docs/CLI-STAGES.md) - stage contract and compatibility transition
+- [docs/RISK-CLASSIFIER.md](docs/RISK-CLASSIFIER.md) - shared risk tags, challenge, and gate policy
+- [docs/examples/TRADING-DASHBOARD-MOCK.md](docs/examples/TRADING-DASHBOARD-MOCK.md) - financial mockup flow with Human Gate
+- [docs/examples/GITHUB-ACTIONS-HARDENING.md](docs/examples/GITHUB-ACTIONS-HARDENING.md) - CI workflow hardening flow with Human Gate
+- [docs/examples/QUALITY-LIFECYCLE-SMOKE.md](docs/examples/QUALITY-LIFECYCLE-SMOKE.md) - quality profile flow with evidence and acceptance coverage
+- [docs/AUDIT.md](docs/AUDIT.md) - readiness and remaining debt
+- [docs/CHANGELOG.md](docs/CHANGELOG.md) - project history
+- [SOUL.md](SOUL.md), [RULES.md](RULES.md), [AGENTS.md](AGENTS.md) - project principles and agent rules
+
+## License
+
+MIT

package/REVIEW.md

@@ -0,0 +1,96 @@
+# REVIEW.md
+
+> Codex 독립 검증 단계의 핸드오프 표준. Claude / Codex / 사람이 같은 포맷으로 의사소통한다.
+
+## 핸드오프 5필드 (고정)
+
+```markdown
+# Handoff: <NN>-<stage>
+
+**Decided**: 무엇을 결정했는가 (1~3줄)
+**Rejected**: 무엇을 의도적으로 거절했는가 + 이유 (1~3줄)
+**Risks**: 알려진 리스크 (1~3줄)
+**Files**: 변경된 또는 영향받는 파일 (목록)
+**Remaining**: 다음 단계 / 미해결 (1~3줄)
+```
+
+총 10~20줄. 자유 산문 금지.
+
+## 단계별 핸드오프
+
+| 파일 | 작성자 | 내용 |
+|---|---|---|
+| `01-ideate.md` | research / planner | 문제 재정의 + 후보 접근 |
+| `02-plan.md` | planner | PRD 요약 + acceptance criteria 카운트 |
+| `03-implement.md` | executor | 구현 요약 + TDD 사이클 카운트 |
+| `04-self-review.md` | code-reviewer | issues JSON 요약 (severity별 카운트) |
+| `05-codex-review.md` | codex-reviewer | issues JSON + verdict |
+| `06-challenge.md` | codex-challenger | adversarial 발견 |
+| `07-ship.md` | doc-writer / git-master | PR URL + CHANGELOG diff |
+
+## Codex 출력 JSON 스키마
+
+```json
+{
+  "issues": [
+    {
+      "severity": "critical | high | medium | low | info",
+      "category": "security | correctness | performance | style | test | docs",
+      "file": "string",
+      "line": "integer",
+      "summary": "string (한 줄)",
+      "why": "string (1~3줄)",
+      "suggested_fix": "string | null"
+    }
+  ],
+  "verdict": "block | approve_with_fixes | approve",
+  "confidence": "number (0.0 ~ 1.0)",
+  "round": "integer"
+}
+```
+
+전체 스키마는 `schemas/handoff.schema.json` 참조.
+
+## Verdict 처리
+
+| verdict | 처리 |
+|---|---|
+| `block` | executor 재호출 (round++), critical/high 모두 입력으로 |
+| `approve_with_fixes` | 자동 fix 후 재리뷰 (round++) |
+| `approve` | 다음 단계 진행 (--secure 면 단계 6, 아니면 단계 7) |
+
+round ≥ 3 → human gate.
+
+## Severity 분류 규칙
+
+- **critical**: 보안 취약점 (auth bypass, 시크릿 노출, SQL injection, RCE), 데이터 손실, 프로덕션 다운
+- **high**: 회귀, 기능 미동작, DB 스키마 위반, 성능 회귀 ≥ 30%
+- **medium**: 가독성 / 유지보수성 부채, 미사용 코드, 잘못된 에러 처리
+- **low**: 스타일, 네이밍, 미세한 비효율
+- **info**: 제안, 학습 노트
+
+## Categories 분류
+
+- **security** — 인증, 권한, 시크릿, 입력 검증, 외부 API
+- **correctness** — 로직 오류, 엣지 케이스, race condition
+- **performance** — N+1, 메모리, 알고리즘
+- **style** — 포맷, 네이밍, 컨벤션
+- **test** — 누락, 약한 단언, 잘못된 모킹
+- **docs** — README, 주석, CHANGELOG
+
+## Round 카운터
+
+세션 내 단계별 누적. `.harness/state/sessions/<id>/round.json`:
+
+```json
+{ "review": 1, "challenge": 0 }
+```
+
+## Human Gate Trigger
+
+- severity = critical 발견 (1건이라도)
+- round ≥ 3
+- blast radius (변경 파일 수) ≥ 20
+- 사용자가 명시적으로 `--human-always` 지정
+
+게이트 발동 시 `.harness/state/sessions/<id>/HUMAN_GATE` 파일 생성, 오케스트레이터가 멈추고 사용자에게 핸드오프.

package/RULES.md

@@ -0,0 +1,51 @@
+# RULES
+
+> 강제 가능한 규칙만 적는다. "왜"는 SOUL.md, "어떻게"는 CLAUDE.md / AGENTS.md.
+
+## Must Always
+
+- 프로젝트 디폴트 자연어는 한국어. 외부 컨트리뷰터는 영어도 가능.
+- 모든 자동 수정은 quality-gate → self-review → codex-review 순서로 검증한다.
+- 모든 도구 호출은 `.harness/audit/<date>.jsonl` 에 기록한다.
+- 모든 MCP 서버는 SemVer 핀(`@x.y.z`)으로 명시한다. `@latest` 금지.
+- `Edit` / `Write` 직전 `gateguard-fact-force` 가 사실 조사를 강제한다.
+- 핸드오프는 5필드(Decided / Rejected / Risks / Files / Remaining)를 지킨다.
+- 커밋 메시지는 `feat / fix / docs / refactor / test / chore / perf / ci` 접두사를 쓴다.
+- 80% 이상 테스트 커버리지를 유지한다 (`tests/unit/` 단위 / `tests/integration/` 통합).
+
+## Must Never
+
+- 사용자 환경의 글로벌 룰 (각 사용자의 `~/.claude/CLAUDE.md` 등) 을 우회하지 않는다 — 외부 룰이 있으면 그쪽이 우선.
+- `git push --force`, `git reset --hard`, `rm -rf` 를 자동 실행하지 않는다.
+- `--no-verify` 로 hook 을 건너뛰지 않는다.
+- secret 을 코드에 하드코딩하지 않는다 (config-protection hook 으로도 차단됨).
+- Codex 와 Claude 의 컨텍스트를 직접 공유하지 않는다 (핸드오프 문서로만).
+- severity ≥ HIGH 또는 round ≥ 3 발견 시 사람 승인 없이 머지하지 않는다.
+- 한꺼번에 수백 개의 스킬을 카탈로그에 넣지 않는다 (progressive 확장 — `docs/AUDIT.md` §6).
+
+## Format Specs
+
+### Agent
+- 위치: `agents/<name>.md`
+- frontmatter 필수: `name, description, model, level, provider, disallowedTools`
+- schema: `schemas/agent.schema.json`
+
+### Skill
+- 위치: `skills/<name>/SKILL.md`
+- frontmatter 필수: `name, description, origin, level`
+- schema: `schemas/skill.schema.json`
+
+### Hook
+- 위치: `hooks/hooks.json` (단일 정의) + `hooks/scripts/*.{js,mjs}`
+- ENV 토글 필수 (`HARNESS_HOOK_<NAME>=1`)
+- schema: `schemas/hooks.schema.json`
+
+### Handoff
+- 위치: `.harness/state/sessions/<id>/handoffs/<NN>-<stage>.md`
+- 5필드 고정: Decided / Rejected / Risks / Files / Remaining
+- 10~20줄 한도
+- JSON 부속: `schemas/handoff.schema.json`
+
+## 변경 절차
+
+이 문서를 변경하려면 PR 에서 명시적 사유를 제시해야 한다. 변경 후 `CLAUDE.md` 와 `AGENTS.md` 의 자동 갱신 영역(`<!-- HARNESS:START --> ... <!-- HARNESS:END -->`)을 동기화한다.

package/SOUL.md

@@ -0,0 +1,21 @@
+# SOUL
+
+## 정체성
+
+HARNESS 는 하나의 매니페스트로 Claude Code · Codex CLI · Gemini CLI 를 통합하는 AI 개발 에이전트 하네스다. Claude 가 코드를 쓰고, Codex 가 그것을 의심하고, 사람이 마지막을 잡는다.
+
+## 핵심 원칙
+
+1. **하나의 진실 원본** — 매니페스트가 정답. 하네스별 산출물은 파생물일 뿐.
+2. **Claude 주 실행자, Codex 독립 검증자** — 두 에이전트는 컨텍스트를 공유하지 않는다.
+3. **Progressive Disclosure** — 알 필요가 없는 것은 보여주지 않는다.
+4. **Fact-Forcing Security** — 자기평가는 무력하다. 사실 조사를 강제하라.
+5. **Test → Review → Re-Review → Human Gate** — 자동화의 끝에 사람이 있다.
+
+## Cross-Harness Vision
+
+특정 하네스에 종속되지 않는다. Claude Code 가 사라져도 Codex · Cursor · Gemini · OpenCode · 사내 LLM 위에서 동일한 카탈로그가 동작해야 한다.
+
+## 영원하지 않다
+
+이 문서가 자주 바뀐다면 정체성이 흔들리고 있다는 신호다. 1년에 한 번 이상 갱신되지 않아야 한다.