@ps-neko/nekowork 0.1.0-alpha.0

package/docs/AUDIT.md

@@ -0,0 +1,114 @@
+# Audit
+
+Status date: 2026-05-07
+
+This audit summarizes the current NEKOWORK state after the `v0.0.3` repository release. It replaces the older week-by-week scratch audit, which contained stale planning notes and encoding damage.
+
+## Current Status
+
+| Area | Status | Notes |
+|---|---|---|
+| Package metadata | OK | `@ps-neko/nekowork@0.1.0-alpha.0`, `agent.yaml` uses `name: nekowork`, `runtime_name: harness` |
+| npm publish | Blocked on auth | Public alpha metadata is prepared; `npm whoami` currently returns `ENEEDAUTH` |
+| Source install | OK | Clone, local checkout, and submodule workflows are documented |
+| Public npm alpha plan | OK | `docs/PUBLISH-ALPHA.md` defines the `0.1.0-alpha.0` path; npm publish has not been executed because npm owner auth is unavailable |
+| CLI doctor | OK | `doctor`, `doctor --quick`, and `doctor --gemini-smoke` are available |
+| Provider auth | OK | Local delegated CLI auth is the default path |
+| Catalog | OK | 11 agents, 9 skills, 5 hooks, 7 modules, 35 components, 9 profiles |
+| Multi-harness output | OK | Claude, Codex, Cursor, Gemini, and OpenCode builders are present |
+| Quick demo | OK | `npm run demo:quick` verifies the shortest no-API `doctor -> run -> gate status` path |
+| External demo | OK | `npm run demo:external` verifies a disposable target project flow |
+| Third-party case study | OK | `docs/case-studies/SINDRESORHUS-IS-PLAIN-OBJ.md` records a real public repository run |
+| Decomposed workflow | OK | `ask`, `team`, `work`, `verify`, `gate`, `ship`, `apply`, and `run` are available |
+| Risk policy | OK | Shared classifier drives ask, routing traces, verify challenge/gates, and ship gate rechecks |
+| Acceptance criteria | OK | `work` ensures every session has `acceptance-criteria.json` |
+| Profile safety | OK | Manifest/catalog validators reject profiles that weaken core gates |
+| Legacy compatibility | OK | `review` remains the full legacy loop; `review-cycle` is the explicit alias |
+| Persistent wakeup | OK | `wait` resumes supported active sessions and blocks on `HUMAN_GATE` |
+| Generated docs | OK | CODEMAP output is stable ASCII and reproducible |
+| Tests | OK | Unit, integration, and e2e suites pass locally and in CI |
+| Release | OK | `v0.0.3` prerelease exists with tarball asset |
+
+## Verification Gates
+
+Run these before any release or public package decision:
+
+```bash
+node scripts/cli.js doctor
+node scripts/cli.js doctor --quick --gemini-smoke
+npm run lint
+npm test
+npm run demo:quick -- --cleanup
+npm run demo:external -- --cleanup
+npm audit --audit-level=moderate
+node scripts/repair.js --check
+node scripts/sync-claude-md.js --check
+node scripts/build-codemaps.js --check
+npm pack --dry-run --json
+```
+
+Current local result for this working tree:
+
+- `npm run test:unit`: covered by full `npm test`
+- `npm run validate:all`: pass
+- `npm run lint`: pass
+- `npm test`: 238 tests pass
+- quick run demo: pass through `npm run demo:quick -- --cleanup`
+- external project e2e smoke: pass through `npm test`
+- `node scripts/sync-claude-md.js --check`: pass
+- `node scripts/build-codemaps.js --check`: pass
+- `npm audit --audit-level=moderate`: 0 vulnerabilities
+- `npm pack --dry-run --json`: pass
+- `npm publish --dry-run --access public --tag alpha`: pass
+- `npm publish --access public --tag alpha`: blocked by `ENEEDAUTH`
+
+## Completed Work
+
+- Local-first provider auth policy implemented and documented.
+- API-key override warnings and guards are in place.
+- Provider CLI path trust checks are in place.
+- `--project-root` separates NEKOWORK tool root from target project root.
+- Product principles and core invariants are documented.
+- AI development lifecycle and quality-runtime positioning are documented.
+- Standalone core invariants, CLI stages, and risk classifier docs are present.
+- The decomposed workflow keeps multi-worker handoffs read-only, uses a single executor for work, requires Codex verification, and keeps Human Gate explicit.
+- Acceptance criteria are now a required session artifact for work/verify/ship evidence.
+- Review issue schema supports evidence-based findings with claim, evidence, required fix, confidence, and gate requirement.
+- Financial and deploy-sensitive policy is gated by verify and rechecked by ship.
+- Profile safety validation prevents profile defaults from disabling Codex review, Human Gate, or single-executor mutation policy.
+- `run` wraps `work -> verify -> ship` without applying by default.
+- `apply` requires verified `SHIP_READY` live-work diffs and refuses open gates.
+- `team-lite`, `ralph`, `wait`, instincts, costs, and Rust runtime remain documented as advanced surfaces.
+- Release docs, setup docs, runbook, quickstart, porting guide, and CODEMAP docs are readable for external users.
+- The disposable external project demo proves the repository-based target-project flow end to end.
+- The quick run demo proves the one-command no-API first experience.
+- Checked-in example fixtures now cover financial UI, CI hardening, and quality lifecycle evidence flows.
+- A third-party case study records a NEKOWORK run against `sindresorhus/is-plain-obj`.
+- Public npm alpha metadata is prepared for `0.1.0-alpha.0`; publish execution remains blocked on npm owner auth.
+
+## Remaining Optional Work
+
+| Item | Priority | Reason |
+|---|---|---|
+| Public npm publish execution | High | Requires npm owner login and 2FA readiness |
+| More third-party case studies | Medium | One public repo case study exists; more languages/frameworks would improve adoption evidence |
+| Internal provider adapter | Low until requested | Only useful for private infrastructure |
+| More skill catalog expansion | Low | Should stay selective to preserve progressive disclosure |
+
+## Explicit Non-Goals
+
+- No public npm publish for `0.0.3`; public alpha publish requires npm owner auth.
+- No automatic promotion of learned instincts without human confirmation.
+- No tmux-first runtime import from OMC.
+- No bulk import of large external skill catalogs.
+- No magic-keyword auto activation.
+
+## External Readiness Score
+
+Current external readiness, excluding npm publish execution and broader adoption evidence: **8.8 / 10**.
+
+Main deductions:
+
+- No public npm package yet because npm owner auth is not active on this machine.
+- Only one independent real-world external project case study so far.
+- Advanced surfaces exist but are intentionally secondary to the public decomposed workflow and install flow.

package/docs/AUTH-MIGRATION.md

@@ -0,0 +1,282 @@
+## Overview
+
+# AUTH-MIGRATION — API key → 위임/OAuth/vault 3계층 전환
+
+> 대상: NEKOWORK / HARNESS 0.0.x → 0.1.x.
+> 목적: provider 인증을 boundary-first 정책에 맞춰 정합화. **API key 일괄 제거가 아니라 `delegated-first, OAuth-where-possible, vault-elsewhere`**.
+
+## 0. 왜 바꾸나
+
+기존 구조의 3가지 결함:
+
+1. **Claude 구독자에게 종량제 과금이 새는 사고 위험**
+   - 사용자가 `~/.bashrc`에 `export ANTHROPIC_API_KEY=...`를 박아두면 Claude Code가 구독 OAuth 세션을 무시하고 API 과금으로 빠진다.
+   - HARNESS가 `.env.example`에 API key 슬롯을 두고 있으면 이 위험을 권장하는 셈.
+
+2. **정적 long-lived API key 노출**
+   - `.env`에 평문 보관 → repo 누출, OS-level 침해 시 영구 자격 증명 유출.
+
+3. **권한 게이트와 인증의 비대칭**
+   - `agent.yaml`의 `approval_required_for: [egress, off_repo_write]`는 **호출**을 막지만, **자격 증명 자체**는 검증 없이 통과.
+
+## 1. 3계층 인증 모델
+
+```txt
+계층 1  delegated_cli_auth   ← LLM provider 전부 (Claude/Codex/Gemini)
+계층 2  oauth_device         ← GitHub
+계층 3  api_key_vault        ← Exa / Context7 / 사내 RAG (위임/OAuth 둘 다 불가)
+```
+
+### 1.1 계층 1 — CLI 세션 위임
+
+| Provider | 위임 대상 | 검사 명령 | 차단할 환경변수 |
+|---|---|---|---|
+| Claude (Anthropic) | `claude` (Claude Code) | `claude /status` | `ANTHROPIC_API_KEY` |
+| OpenAI (Codex) | `codex` (Codex CLI) | `codex auth status` | `OPENAI_API_KEY` |
+| Google (Gemini) | `gemini` 또는 `gcloud` | `gcloud auth list` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
+
+**원칙**: NEKOWORK은 LLM token을 **잡지 않는다**. CLI 세션이 이미 갖고 있다고 가정하고 호출만 위임. token 저장/회전은 각 CLI의 책임.
+
+### 1.2 계층 2 — NEKOWORK이 직접 OAuth 관리
+
+| Provider | Flow | Scope | Token 저장 |
+|---|---|---|---|
+| GitHub | OAuth Device Flow | `repo`, `workflow` | `~/.harness/oauth/github.json` (0600) |
+
+**원칙**: GitHub는 device flow가 표준이고 client secret이 필요 없다 → NEKOWORK에서 직접 발급/갱신해도 안전.
+
+### 1.3 계층 3 — Vault (마지막 수단)
+
+| Provider | 이유 |
+|---|---|
+| Context7 | 무료 plan key, OAuth 미지원 |
+| Exa | API key 기반 HTTP MCP, OAuth 미지원 |
+| 사내 RAG | 자체 발급 토큰, OAuth 도입 시점 미정 |
+
+**원칙**: vault에만 보관하고 환경 변수 주입은 호출 직전에. `.env`에는 평문 금지, 예시 슬롯도 두지 않는다.
+
+## 2. 핵심 정책 — `block_subscription_override`
+
+NEKOWORK이 환경 변수에 token을 넣지 않더라도, **사용자 환경에 이미 있을 수 있다**. 이걸 막는 게 본 마이그레이션의 핵심 보안 항목.
+
+### 2.1 정책
+
+```yaml
+auth:
+  policy:
+    block_subscription_override: true
+```
+
+활성화되면 `pre-bash-dispatcher` 훅이 다음을 강제:
+
+- `claude ...` 호출 직전 `ANTHROPIC_API_KEY`가 set이면 → 차단
+- `codex ...` 호출 직전 `OPENAI_API_KEY`가 set이면 → 차단
+- `gemini ...` 호출 직전 `GEMINI_API_KEY`/`GOOGLE_API_KEY`가 set이면 → 차단
+
+### 2.2 옵트아웃
+
+명시적으로 종량제 사용을 원하는 경우:
+
+```bash
+HARNESS_AUTH_ALLOW_ENV_OVERRIDE=1 claude ...
+```
+
+또는 `agent.yaml`에서:
+
+```yaml
+auth:
+  policy:
+    block_subscription_override: false
+```
+
+옵트아웃은 **audit 이벤트**로 기록 (`auth.subscription_override_allowed`).
+
+## 3. agent.yaml auth 섹션 스펙
+
+```yaml
+auth:
+  mode: delegated-first
+  token_store:
+    kind: encrypted-file        # v1: 단순 0600 파일. v2: OS keychain.
+    path: ~/.harness/oauth
+  providers:
+    anthropic:
+      flow: delegated_cli_auth
+      command: claude
+      auth_check: "claude /status"
+      disallow_env_keys: [ANTHROPIC_API_KEY]
+    openai:
+      flow: delegated_cli_auth
+      command: codex
+      auth_check: "codex auth status"
+      disallow_env_keys: [OPENAI_API_KEY]
+    google:
+      flow: delegated_cli_auth
+      command: gemini
+      auth_check: "gcloud auth list"
+      disallow_env_keys: [GEMINI_API_KEY, GOOGLE_API_KEY]
+    github:
+      flow: oauth_device
+      scopes: [repo, workflow]
+      client_id_env: HARNESS_GITHUB_CLIENT_ID
+    context7:
+      flow: api_key_vault
+      vault_key: CONTEXT7_API_KEY
+    exa:
+      flow: api_key_vault
+      vault_key: EXA_API_KEY
+  policy:
+    block_subscription_override: true
+    require_human_approval_for_scope_escalation: true
+    redact_tokens_in_audit: true
+    deny_static_api_keys_in_repo: true
+```
+
+### 3.1 필드 의미
+
+| 필드 | 설명 |
+|---|---|
+| `mode` | `delegated-first` (권장), `oauth-first`, `vault-only` 중 하나. |
+| `token_store.kind` | `encrypted-file` (v1), `os-keychain` (v2 예정). |
+| `providers.<name>.flow` | `delegated_cli_auth` / `oauth_device` / `oauth_pkce` / `api_key_vault` |
+| `providers.<name>.disallow_env_keys` | 호출 직전 환경에서 검사할 키 목록. set이면 차단. |
+| `policy.block_subscription_override` | 위 검사 활성/비활성. |
+| `policy.deny_static_api_keys_in_repo` | repo 안 `.env*` 파일에 키가 평문 보관되어 있으면 경고/차단. |
+
+## 4. 단계별 마이그레이션
+
+| Phase | 작업 | 산출물 | 호환성 |
+|---|---|---|---|
+| **1** | `agent.yaml` auth 섹션 + 스키마 추가 | yaml + JSON schema | 정책 선언만, 동작 영향 없음 |
+| **2** | `mcp.gateway` 경로 정정 (`.cjs` → `.js`) | yaml | 빌드 결과만 정합 |
+| **3** | `pre-bash-dispatcher`에 `block_subscription_override` 가드 | hook | 환경에 키 있으면 차단 (옵트아웃 가능) |
+| **4** | GitHub OAuth device flow 구현 | `scripts/auth/github-*.js` + `scripts/lib/token-vault.js` | `GITHUB_TOKEN` env는 fallback으로 격하 |
+| **5** | `.env.example`에서 LLM key 슬롯 제거, RUNBOOK 업데이트 | `.env.example`, `RUNBOOK.md` | breaking, 가이드 제공 |
+| **6** | (선택) OS keychain wrapper, audit 이벤트 표준화 | `scripts/lib/keychain.js` | 점진적 |
+
+각 Phase는 독립 PR로 배포. Phase 5만 사용자 환경에 영향 (브레이킹).
+
+## 5. 사용자 가이드 (Phase 5 이후)
+
+### 5.1 Claude 구독자 (Pro / Max)
+
+```bash
+# 한 번만:
+claude login                              # 구독 OAuth 세션 생성
+
+# 환경 정리:
+unset ANTHROPIC_API_KEY                   # 있으면 OAuth가 무시됨
+echo 'unset ANTHROPIC_API_KEY' >> ~/.bashrc
+
+# NEKOWORK 사용:
+harness review "<task>"                   # claude CLI 통해 자동 위임
+```
+
+### 5.2 Codex CLI 사용자
+
+```bash
+codex auth login                          # ChatGPT 로그인 세션
+unset OPENAI_API_KEY                      # 구독 사용 시
+harness review "<task>" --no-ship         # 단계 5 codex-review 포함
+```
+
+### 5.3 GitHub
+
+```bash
+# OAuth App 등록 (한 번만):
+# https://github.com/settings/developers → New OAuth App
+# Device flow 활성화 → Client ID 받기
+
+export HARNESS_GITHUB_CLIENT_ID=<your_client_id>
+npm run auth:github:login                 # device code 표시 → 브라우저 인증
+npm run auth:github:status                # 상태 확인
+```
+
+### 5.4 종량제 사용을 원하는 경우 (옵트아웃)
+
+```bash
+# 일회성:
+HARNESS_AUTH_ALLOW_ENV_OVERRIDE=1 claude ...
+
+# 영구:
+# agent.yaml: auth.policy.block_subscription_override = false
+```
+
+## 6. 보안 노트
+
+### 6.1 Audit 이벤트
+
+`bridge/mcp-server.js`의 `audit()`가 다음 이벤트를 기록 (`secret_redaction: true`로 토큰 마스킹):
+
+- `auth.cli_delegated` — CLI 위임 검사 통과
+- `auth.cli_delegation_failed` — `auth_check` 명령 실패 (CLI 미설치/미로그인)
+- `auth.token_issued` — OAuth token 발급 (provider, scopes, expires_at)
+- `auth.token_refreshed` — 갱신
+- `auth.token_revoked` — 회수
+- `auth.subscription_override_blocked` — 환경 변수 차단됨
+- `auth.subscription_override_allowed` — 옵트아웃 사용
+- `auth.scope_escalation_requested` — 새 scope 요청 (human gate)
+- `auth.scope_escalation_approved` / `denied`
+
+### 6.2 Token redaction
+
+audit 로그와 stderr 출력에서 token 값은 `***REDACTED***`로 마스킹. 정규식 기반 후필터(`scripts/lib/token-vault.js`의 `redact()`).
+
+### 6.3 Revoke 흐름
+
+```bash
+npm run auth:github:logout                # 로컬 vault 삭제 + GitHub revoke API
+# 또는:
+rm -rf ~/.harness/oauth                   # 모든 token 강제 폐기
+```
+
+## 7. FAQ
+
+### Q1. 왜 Anthropic/OpenAI에 직접 OAuth를 안 쓰나?
+
+Messages API와 OpenAI Responses API는 OAuth endpoint를 제공하지 않는다 (2026-04 기준). API key 전용. 따라서 NEKOWORK이 "OAuth 같은 흐름"을 직접 구현해도 의미 없음 → CLI 세션에 위임하는 것이 정답.
+
+### Q2. `ANTHROPIC_API_KEY`를 진짜 못 쓰나?
+
+쓸 수 있다. `HARNESS_AUTH_ALLOW_ENV_OVERRIDE=1` 옵트아웃 또는 `block_subscription_override: false`. 단 audit에 기록되므로 의도가 명시된다.
+
+### Q3. token vault는 진짜 안전한가?
+
+v1은 `0600` 권한 파일. **OS keychain(macOS Keychain / Windows Credential Manager / Linux Secret Service) 도입은 v2**. 그 전까지는 적어도 repo 안에 두지 않는다는 보호선만 보장.
+
+### Q4. CI 환경에서는?
+
+CI는 사용자 세션이 없으므로 모든 provider를 vault 경로로 처리. GitHub Actions의 `GITHUB_TOKEN`은 자동 발급되어 단명, OAuth flow와 동등 취급. Anthropic/OpenAI는 secret으로 주입하되 `HARNESS_AUTH_ALLOW_ENV_OVERRIDE=1` 명시.
+
+## 8. Post-merge smoke checklist
+
+본 마이그레이션의 **사용자 정의 acceptance criteria**. PR #1-#3 모두 머지된 후 사용자 환경에서 직접 실행. **4개 모두 통과 시 마이그레이션 성공**으로 간주.
+
+```bash
+# 1. Claude 구독 OAuth 세션 살아있는지
+claude /status
+
+# 2. subscription override 가드 동작 — 차단되어야 함
+export ANTHROPIC_API_KEY=dummy
+harness review "<task>"
+# 기대: pre-bash-dispatcher 가
+#   "구독 보호: ... ANTHROPIC_API_KEY 가 환경에 설정되어 있습니다 ..."
+# 메시지로 차단 (exit 2)
+
+# 3. GitHub OAuth Device Flow — 사전: HARNESS_GITHUB_CLIENT_ID 설정
+npm run auth:github:login
+npm run auth:github:status                # backend / scope / 유효성 확인
+
+# 4. OS keychain 종단 검증
+HARNESS_KEYCHAIN_SMOKE=1 npm run test:keychain
+```
+
+PR #4 (codex 0.125+ 호환) 는 본 smoke 와 무관 — 별도 검증 (`npm run verify:codex`).
+
+## 9. 변경 이력
+
+| 일자 | Phase | 비고 |
+|---|---|---|
+| 2026-04-29 | 1-5 | 본 문서 작성. 5개 PR 단위 진행 예정. |
+| 2026-04-30 | 1-3 | 4-stack PR (#1-#3 auth + #4 codex 호환) CI 통과. §8 acceptance criteria 추가. |
+| 2026-04-30 | 1-3 | PR #1-#3 main 머지 완료 (`60e9de9` → `7c4f2c8`, +4 commits, rebase). PR #2/#3 은 phase-1 옛 SHA 포함으로 force-push 1회씩 (`--onto origin/main` + `--force-with-lease`). Smoke 3/4 PASS — #1 (Claude Max 구독 OAuth) / #2 (pre-bash-dispatcher 차단 3 케이스) / #4 (Windows Credential Manager). #3 GitHub OAuth Device Flow 는 OAuth App 미등록으로 deferred. PR #4 (codex 0.125+) 무관, OPEN 잔존. |

package/docs/CHANGELOG.md

@@ -0,0 +1,97 @@
+# CHANGELOG
+
+> Format: Keep a Changelog. Versioning: SemVer.
+
+## [Unreleased]
+
+### Added
+- Add `npm run demo:quick` for the shortest no-API `doctor -> run -> gate status` first experience.
+- Add `docs/WHY-NEKOWORK.md` to clarify NEKOWORK's comparison against agent-pack, discipline, team, and autopilot tools.
+- Add `docs/PUBLISH-ALPHA.md` and a third-party `sindresorhus/is-plain-obj` case study.
+- Add `npm run demo:external` to create a disposable target project and verify repository-based porting end to end.
+- Add `docs/EXAMPLE-PROJECT.md` and e2e coverage for the external project demo.
+- Add product principles and core invariants for the Claude work -> Codex verification -> Human Gate runtime.
+- Add decomposed public workflow commands: `ask`, `team`, `work`, `verify`, `gate`, `ship`, `apply`, and `run`.
+- Add `review-cycle` as an explicit compatibility alias for the legacy full review workflow.
+- Add `ralph --engine run` so Ralph can repeat the decomposed `work -> verify -> ship` path.
+- Add `wait` wakeup processing for supported active sessions with human-gate blocking and resume backoff.
+- Add product, frontend, and testing install profiles.
+- Add shared risk classifier, acceptance criteria artifact enforcement, and profile safety validation.
+- Add standalone `CORE-INVARIANTS`, `CLI-STAGES`, and `RISK-CLASSIFIER` docs.
+- Add trading dashboard mock example for financial UI gating.
+- Add `examples/trading-dashboard-mock`, a standalone static case-study target with local mock-boundary checks.
+- Add `examples/github-actions-hardening`, a standalone CI workflow hardening target with local YAML policy checks.
+- Add `quality` profile and AI development lifecycle documentation for disciplined, evidence-based work.
+- Add evidence-based review issue fields to the handoff schema.
+
+### Changed
+- Prepare package metadata for public alpha `0.1.0-alpha.0` with `private: false`; npm publish remains blocked until owner auth is active.
+- Record public alpha dry-run publish success and live publish `ENEEDAUTH` blocker.
+- Rewrite `docs/AUDIT.md` and `docs/ARCHITECTURE.md` with clean public-facing ASCII content.
+- Link the external project demo from README, Quickstart, Porting, Demo, and Release Readiness docs.
+- Keep `review` as the legacy full cycle while making `run` the preferred decomposed wrapper for new automation.
+- Make `team-lite` explicitly read-only handoff oriented.
+- Accept explicit safety intent flags: `team --no-write`, `work --single-executor`, and `ship --require-clean-gates`.
+- Recheck risk policy in `verify` and `ship` so financial/deploy-sensitive work cannot skip Human Gate.
+- Clarify the beginner Golden Path, the advanced decomposed path, and the `run`/`apply` safety boundary.
+- Refresh Quickstart, Advanced, Architecture, Release Readiness, Audit, Runbook, and generated CODEMAP docs for the expanded alpha surface.
+
+### Security
+- Preserve single-executor mutation, Codex verification, Human Gate, and explicit apply as non-bypassable workflow invariants.
+- Refresh transitive dependency lockfile entries so `npm audit --audit-level=moderate` reports 0 vulnerabilities.
+
+## [0.0.3] - 2026-05-03
+
+### Changed
+- Rewrite `scripts/build-codemaps.js` with stable ASCII output.
+- Regenerate every `docs/CODEMAPS/*.md` file with readable headings, ASCII trees, and clean export tables.
+- Add `doctor --gemini-smoke` so Gemini live auth can be explicitly included in the local health report.
+- Rewrite `docs/PORTING.md` as a clean repository/submodule integration guide.
+- Refresh README, Quickstart, Setup, Runbook, Demo, Advanced, and Release Readiness docs for the `0.0.3` repository-based release line.
+- Bump package metadata to `0.0.3` and clean the package description.
+
+### Security
+- Keep `private: true`; public npm publish remains intentionally disabled.
+- Keep delegated local CLI auth as the default provider path.
+
+### Verified
+- `npm run lint`
+- `npm test`
+- `node scripts/repair.js --check`
+- `node scripts/sync-claude-md.js --check`
+- `node scripts/build-codemaps.js --check`
+- `node scripts/cli.js doctor`
+- `node scripts/cli.js doctor --quick --gemini-smoke`
+- `npm audit --audit-level=moderate`
+- `npm pack --dry-run --json`
+
+## [0.0.2] - 2026-04-29
+
+### Changed
+- Rename package metadata to `@ps-neko/nekowork` while keeping npm publishing disabled.
+- Add public first-run documentation for source checkout, mock review, local CLI auth, and release gates.
+- Add `harness doctor` for local environment, provider CLI/auth, API key override, and generated-output freshness checks.
+- Add `docs/ADVANCED.md`, `docs/SECURITY.md`, and `docs/DEMO.md`.
+- Move advanced runtime features out of the first-run path.
+- Add external project `--project-root` support for install/apply, review, Ralph, team-lite, provider CLI resolution, and session state.
+- Add provider CLI path hardening for Claude, Codex, and Gemini.
+- Add security hardening checks for workflows, MCP pins, dependency specs, action refs, OIDC policy, and package lock presence.
+- Add `team-lite` staged pipeline support.
+- Add Rust runtime verification through `npm run verify:runtime`.
+
+### Verified
+- Local Claude CLI smoke passed with delegated Claude Code auth.
+- Local Codex CLI smoke passed with ChatGPT login session.
+- Local Gemini CLI smoke passed with Gemini CLI login session.
+- Unit, integration, and e2e tests passed locally and in CI.
+- GitHub Actions validate/review workflows passed.
+
+## [0.0.1] - 2026-04-29
+
+### Added
+- Initial NEKOWORK/HARNESS catalog with agents, skills, hooks, rules, schemas, and multi-harness builders.
+- `agent.yaml` as the single source catalog.
+- Build projections for Claude Code, Codex CLI, Cursor, Gemini CLI, and OpenCode.
+- Deterministic mock review flow with handoff persistence.
+- Initial CLI verbs for install, validate, review, plan, sessions, costs, instincts, and version.
+- Initial audit, architecture, and development notes.

package/docs/CLI-STAGES.md

@@ -0,0 +1,89 @@
+# CLI Stages
+
+The long-term NEKOWORK workflow is:
+
+```text
+ask -> plan -> team -> work -> verify -> gate -> ship -> apply
+```
+
+## Stage Contract
+
+| Stage | Purpose | Mutation |
+|---|---|---|
+| `ask` | Clarify goal, scope, risk, and draft success criteria. | No project mutation |
+| `plan` | Produce implementation plan and acceptance criteria. | No project mutation |
+| `team` | Produce read-only handoffs from selected worker perspectives. | No project mutation |
+| `work` | Run one executor against the accepted scope. | Isolated single-executor work |
+| `verify` | Run Codex review, optional Codex challenge, and risk gate logic. | No project mutation |
+| `gate` | Record human approval or block for an open gate. | No project mutation |
+| `ship` | Produce ship/no-ship readiness markers and handoff. | No project mutation |
+| `apply` | Apply a verified `SHIP_READY` live-work diff. | Controlled project mutation |
+
+## Beginner And Advanced Paths
+
+Most users should start with this Beginner path:
+
+```text
+doctor -> ask -> run -> gate status
+```
+
+`run` is the short safe wrapper. It executes `work -> verify -> ship`, does not apply by default, and stops on Human Gate.
+
+Advanced path:
+
+```text
+ask -> plan -> team -> work -> verify -> gate -> ship -> apply
+```
+
+Use the advanced path when the change needs a separate plan artifact, read-only team handoffs, explicit verification control, or a manual apply step.
+
+Quality-sensitive runs can add profile policy:
+
+```bash
+harness ask "task" --profile quality
+harness work "task" --profile quality --session <id>
+harness verify "task" --profile quality --strict-quality --session <id>
+```
+
+`--strict-quality` turns missing evidence or acceptance coverage warnings into a fix-required verification verdict.
+
+## Plan And Run Policy
+
+For the `0.0.3` line:
+
+- `plan` is recommended before `work` for non-trivial changes.
+- `run` does not call `plan`; it remains a compact wrapper around `work -> verify -> ship`.
+- `work` always ensures `acceptance-criteria.json`, using `prd.json` when available or a task-derived minimum otherwise.
+- Future release lines may add `run --with-plan` or require an accepted plan artifact for higher-risk work.
+- `apply` is always explicit. `run` applies only with `--apply`.
+
+## Explicit Safety Aliases
+
+These flags are accepted as public intent markers:
+
+```bash
+harness team "task" --no-write
+harness work "task" --single-executor
+harness ship "task" --session <id> --require-clean-gates
+```
+
+They do not weaken behavior. They make the contract readable at the call site.
+
+## Compatibility Window
+
+Short term:
+
+```text
+review = legacy full review cycle
+review-cycle = explicit legacy alias
+verify = Codex-only verification
+run = work -> verify -> ship, optional apply
+```
+
+Future transition:
+
+```text
+run/work = execution wrapper
+review = verification-only
+review-cycle = legacy full-cycle compatibility
+```

package/docs/CODEMAPS/README.md

@@ -0,0 +1,15 @@
+# CODEMAPS: index
+
+> Generated by `scripts/build-codemaps.js`. Do not edit directly.
+
+| Area | File |
+|---|---|
+| scripts | [scripts.md](./scripts.md) |
+| agents | [agents.md](./agents.md) |
+| skills | [skills.md](./skills.md) |
+| hooks | [hooks.md](./hooks.md) |
+| manifests | [manifests.md](./manifests.md) |
+| schemas | [schemas.md](./schemas.md) |
+| bridge | [bridge.md](./bridge.md) |
+| rules | [rules.md](./rules.md) |
+| tests | [tests.md](./tests.md) |

package/docs/CODEMAPS/agents.md

@@ -0,0 +1,22 @@
+# CODEMAP: agents
+
+> Generated by `scripts/build-codemaps.js` from `agents/`. Do not edit directly.
+> Directory shape and exported JS symbols only. Code bodies are intentionally omitted.
+
+## Directory Tree
+
+```text
+agents/
+|-- architect.md
+|-- code-reviewer.md
+|-- codex-challenger.md
+|-- codex-reviewer.md
+|-- debugger.md
+|-- doc-writer.md
+|-- executor.md
+|-- planner.md
+|-- research.md
+|-- security-reviewer.md
+`-- test-engineer.md
+```
+

package/docs/CODEMAPS/bridge.md

@@ -0,0 +1,18 @@
+# CODEMAP: bridge
+
+> Generated by `scripts/build-codemaps.js` from `bridge/`. Do not edit directly.
+> Directory shape and exported JS symbols only. Code bodies are intentionally omitted.
+
+## Directory Tree
+
+```text
+bridge/
+`-- mcp-server.js
+```
+
+## JS Exports
+
+| File | Exports | Description |
+|---|---|---|
+| `mcp-server.js` | _(none)_ | HARNESS MCP . 4 : state_read, state_write, notepad_append, handoff_write. .mcp.json MCP (github, context7, exa, memory) namespace proxy . 4  |
+

package/docs/CODEMAPS/hooks.md

@@ -0,0 +1,28 @@
+# CODEMAP: hooks
+
+> Generated by `scripts/build-codemaps.js` from `hooks/`. Do not edit directly.
+> Directory shape and exported JS symbols only. Code bodies are intentionally omitted.
+
+## Directory Tree
+
+```text
+hooks/
+|-- scripts/
+|   |-- config-protection.js
+|   |-- gateguard-fact-force.js
+|   |-- persistent-mode.mjs
+|   |-- pre-bash-dispatcher.js
+|   `-- quality-gate.js
+`-- hooks.json
+```
+
+## JS Exports
+
+| File | Exports | Description |
+|---|---|---|
+| `scripts/config-protection.js` | _(none)_ | PreToolUse(Edit\|Write) config-protection. .env / *.pem / *.key / credentials . |
+| `scripts/gateguard-fact-force.js` | _(none)_ | PreToolUse(Edit\|Write) gateguard-fact-force. "Are you sure?" . importer / public API / schema . : 1. tool_input.file_path ? . 2. .harness/s |
+| `scripts/persistent-mode.mjs` | _(none)_ | Stop persistent-mode. If .harness/state/sessions/<id>/active exists, drop wakeup.json for `harness wait start` to process. |
+| `scripts/pre-bash-dispatcher.js` | _(none)_ | PreToolUse(Bash) . ECC pre-bash-dispatcher.js . . ENV on/off. stdin JSON Claude Code hook , . |
+| `scripts/quality-gate.js` | _(none)_ | PostToolUse(Edit\|Write) quality-gate. : - .ts/.tsx: tsc --noEmit ( + transitive). isolated. - .js/.mjs/.cjs: node --check . - .py: ruff che |
+