@ps-neko/nekowork 0.1.0-alpha.2 → 0.1.0-alpha.4

package/CLAUDE.md

@@ -8,7 +8,7 @@
 
 ## 자동 갱신 영역
 
-<!-- HARNESS:START version=0.1.0-alpha.2 -->
+<!-- HARNESS:START version=0.1.0-alpha.4 -->
 <!-- 이 영역은 scripts/sync-claude-md.js 가 자동 갱신한다. 직접 편집 금지. -->
 
 ## 카탈로그 요약

package/README.md

@@ -1,14 +1,19 @@
 # NEKOWORK
 
-Local-first AI development harness for Claude Code, Codex CLI, and Gemini CLI.
+Local-first AI development quality runtime 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.
+NEKOWORK prevents AI coding agents from shipping unverified changes.
+
+It runs:
 
-Claude writes or plans, Codex challenges the result in a separate context, and human gates stop critical or repeated-risk changes.
+1. Work
+2. Independent verification
+3. Human approval
+4. Explicit apply
 
-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.
+No auto-commit. No auto-push. No surprise deploy.
 
 Product principle:
 
@@ -16,11 +21,16 @@ Product principle:
 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.
+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.
 
-NEKOWORK intentionally keeps the catalog selective. Every agent, skill, hook, profile, module, and pack must preserve the verification loop.
+NEKOWORK is intentionally not a 100-agent pack. Every agent, skill, hook, profile, module, and pack must:
 
-**Public alpha evidence:** 7 packs / 9 profiles / 36 components / 5 harness targets / 6 case-study flows / 245 tests / 0 moderate+ npm audit issues / fresh `npx @alpha` smoke
+1. improve verification,
+2. preserve one-executor writes,
+3. produce auditable evidence,
+4. respect Human Gate.
+
+**Public alpha evidence:** 7 packs / 9 profiles / 36 components / 5 harness targets / 7 case-study flows / 252 tests / 0 moderate+ npm audit issues / fresh `npx @alpha` smoke
 
 NEKOWORK does not automatically commit, push, publish, deploy, or apply diffs. `apply` is explicit and requires verified ship-ready evidence.
 
@@ -28,6 +38,32 @@ NEKOWORK does not automatically commit, push, publish, deploy, or apply diffs. `
 
 ![NEKOWORK one-minute terminal demo](docs/assets/demo-terminal.svg)
 
+## Start Here
+
+Use the current npm alpha for the published health smoke:
+
+```bash
+npx -y @ps-neko/nekowork@alpha check
+```
+
+Use a source checkout for the new simple command path:
+
+```bash
+node scripts/cli.js check
+node scripts/cli.js run "implement this safely" --session first-run
+node scripts/cli.js report --session first-run
+node scripts/cli.js gate status --session first-run
+```
+
+The simple path maps to the full evidence loop: `check = doctor --quick`, and `run = work -> verify -> ship`.
+
+To add generated harness surfaces to another local repository:
+
+```bash
+cd /path/to/my-project
+npx -y @ps-neko/nekowork@alpha init --profile developer --project-root .
+```
+
 ## Example Report
 
 `report` is the main trust surface. It turns session evidence into a readable `REPORT.md`:
@@ -51,6 +87,26 @@ Evidence:
 
 See the full report contract and example artifact in [docs/DEMO-REPORT.md](docs/DEMO-REPORT.md), and the one-minute terminal transcript in [docs/DEMO.md](docs/DEMO.md).
 
+## Human Gate Example
+
+```text
+Risk: security-sensitive auth parser change
+Codex verdict: approve_with_fixes
+Ship ready: false
+
+Required before apply:
+[ ] Add parser boundary test
+[ ] Remove long-lived API key env fallback
+[ ] Re-run verify --strict-quality
+
+Decision:
+- approve
+- block
+- request fixes
+```
+
+Human Gate is the point where NEKOWORK stops being an autopilot and becomes an approval system.
+
 ## Compared With Agent Packs
 
 | Tool pattern | Optimizes for | NEKOWORK optimizes for |
@@ -60,11 +116,21 @@ See the full report contract and example artifact in [docs/DEMO-REPORT.md](docs/
 | Autopilot | Fast autonomous execution | Report, gate, explicit apply |
 | Discipline workflows | Better development habits | Evidence-backed ship decision |
 
+## When To Choose What
+
+| Use case | Prefer |
+|---|---|
+| Add TDD and discipline habits to Claude Code | Superpowers |
+| Get the broadest Claude Code skill/command environment | Everything Claude Code |
+| Simulate startup team roles from planning to QA | GStack |
+| Run autonomous multi-agent execution | OMC |
+| Verify AI changes, require human approval, then apply explicitly | NEKOWORK |
+
 ## 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 -> report -> gate`
+1. Beginner: `check -> run -> report -> gate`
 2. Advanced: `ask -> plan -> team -> work -> verify -> gate -> ship -> report -> apply`
 3. Legacy: `review` / `review-cycle`
 
@@ -74,9 +140,9 @@ NEKOWORK is for teams that want AI-assisted development without making the agent
 
 ## Status
 
-- Current repository version: `0.1.0-alpha.2`
+- Current repository version: `0.1.0-alpha.4`
 - Current package name: `@ps-neko/nekowork`
-- Current npm alpha: `@ps-neko/nekowork@0.1.0-alpha.2`
+- Current npm alpha: `@ps-neko/nekowork@0.1.0-alpha.4`
 - Supported install path today: npm alpha, clone, submodule, or local repository integration
 - Dist-tag note: use `@alpha` until a stable release; `latest` still points at the first alpha line
 - Default mode: mock providers, no API keys, no provider CLI calls
@@ -84,10 +150,10 @@ NEKOWORK is for teams that want AI-assisted development without making the agent
 Current local verification:
 
 - `npm run lint`: pass
-- `npm test`: 245 tests pass
+- `npm test`: 252 tests pass
 - `npm audit --audit-level=moderate`: 0 vulnerabilities
 - `npm pack --dry-run --json`: pass
-- `npx -y @ps-neko/nekowork@alpha doctor --quick`: pass with warnings only
+- `npx -y @ps-neko/nekowork@alpha check`: pass with warnings only
 
 ## Case-study Evidence
 
@@ -99,6 +165,7 @@ Current local verification:
 | npm package boundary | package/release risk | pack/audit evidence |
 | Auth parser boundary | auth/security risk | parser boundary evidence |
 | Python protocol parser | protocol correctness risk | test-backed verification |
+| Dotenv configuration boundary | config/security risk | no-secret parser evidence |
 
 ## Official Packs
 
@@ -123,7 +190,7 @@ Requirements:
 Fastest no-API demo:
 
 ```bash
-npx -y @ps-neko/nekowork@alpha doctor --quick
+npx -y @ps-neko/nekowork@alpha check
 ```
 
 Repository demo:
@@ -143,8 +210,7 @@ Recommended path for most users:
 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 check
 node scripts/cli.js run "implement, verify, and prepare ship readiness" --session first-run
 node scripts/cli.js report --session first-run
 node scripts/cli.js gate status --session first-run
@@ -152,6 +218,13 @@ node scripts/cli.js gate status --session first-run
 
 `run` executes `work -> verify -> ship`. `report` turns the session evidence into a readable `REPORT.md`. It does not apply by default. `apply` is always explicit and requires a verified `SHIP_READY` live-work diff.
 
+To initialize another local repository with the published alpha:
+
+```bash
+cd /path/to/my-project
+npx -y @ps-neko/nekowork@alpha init --profile developer --project-root .
+```
+
 Advanced path:
 
 ```text
@@ -168,13 +241,15 @@ The default review path uses mock providers, so it does not need API keys or pro
 
 For the fuller first-run guide, see [docs/QUICKSTART.md](docs/QUICKSTART.md).
 
+For the trust and recovery model, see [Safety Guarantees](docs/SAFETY-GUARANTEES.md), [Failure Modes](docs/FAILURE-MODES.md), [Trust Model](docs/TRUST-MODEL.md), and [Why Not Autopilot](docs/WHY-NOT-AUTOPILOT.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), [examples/quality-lifecycle-smoke](examples/quality-lifecycle-smoke), and [docs/case-studies](docs/case-studies). They demonstrate financial UI, CI workflow, quality lifecycle, npm package, auth parser, and Python protocol library flows passing local checks while still preserving Codex verification, Human Gate policy, and explicit apply control.
+To inspect small case-study targets, see [examples/trading-dashboard-mock](examples/trading-dashboard-mock), [examples/github-actions-hardening](examples/github-actions-hardening), [examples/quality-lifecycle-smoke](examples/quality-lifecycle-smoke), and [docs/case-studies](docs/case-studies). They demonstrate financial UI, CI workflow, quality lifecycle, npm package, auth parser, Python protocol library, and environment configuration flows while still preserving Codex verification, Human Gate policy, and explicit apply control.
 
 ## What You Get
 
@@ -195,7 +270,15 @@ Outputs are written under:
 
 ## Use It In Another Project
 
-Recommended repository install shape:
+Shortest npm alpha install shape:
+
+```bash
+cd <target-project>
+npx -y @ps-neko/nekowork@alpha init --profile developer --project-root .
+npx -y @ps-neko/nekowork@alpha check --project-root .
+```
+
+Repository-pinned install shape:
 
 ```bash
 cd <target-project>
@@ -338,7 +421,7 @@ 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.2.tgz`. It does not publish.
+`npm pack --dry-run --json` currently produces a package named like `ps-neko-nekowork-0.1.0-alpha.4.tgz`. It does not publish.
 
 ## Documentation
 
@@ -347,6 +430,7 @@ npm pack --dry-run --json
 - [docs/CATALOG-PACKS.md](docs/CATALOG-PACKS.md) - curated catalog, official packs, and case-study evidence
 - [docs/PUBLISH-ALPHA.md](docs/PUBLISH-ALPHA.md) - public npm alpha release plan
 - [docs/ROADMAP.md](docs/ROADMAP.md) - small alpha roadmap and non-goals
+- [docs/FEEDBACK-TRIAGE.md](docs/FEEDBACK-TRIAGE.md) - alpha feedback classification and response guide
 - [docs/INTERNAL-PROVIDER.md](docs/INTERNAL-PROVIDER.md) - private command adapter protocol
 - [docs/DEMO.md](docs/DEMO.md) - sample command output and generated files
 - [docs/DEMO-REPORT.md](docs/DEMO-REPORT.md) - readable session report UX

package/agent.yaml

@@ -1,7 +1,7 @@
 spec_version: gitagent/0.1.0
 name: nekowork
 runtime_name: harness
-version: 0.1.0-alpha.2
+version: 0.1.0-alpha.4
 description: "NEKOWORK HARNESS - Local-first multi-AI development verification runtime"
 license: MIT
 homepage: https://github.com/Ps-Neko/NEKOWORK

package/docs/ARCHITECTURE.md

@@ -202,7 +202,7 @@ Builders project the catalog into tool-specific files:
 
 ## Release State
 
-The current release line is `0.1.0-alpha.2`:
+The current release line is `0.1.0-alpha.4`:
 
 - Repository and GitHub tarball release are available.
 - Public npm alpha is published as `@ps-neko/nekowork@alpha`.

package/docs/AUDIT.md

@@ -2,26 +2,26 @@
 
 Status date: 2026-05-08
 
-This audit summarizes the current NEKOWORK state after publishing the `0.1.0-alpha.2` public alpha. It replaces the older week-by-week scratch audit, which contained stale planning notes and encoding damage.
+This audit summarizes the current NEKOWORK state after publishing the `0.1.0-alpha.4` public alpha. 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.2`, `agent.yaml` uses `name: nekowork`, `runtime_name: harness` |
-| npm publish | OK | `@ps-neko/nekowork@alpha` points at `0.1.0-alpha.2` |
+| Package metadata | OK | `@ps-neko/nekowork@0.1.0-alpha.4`, `agent.yaml` uses `name: nekowork`, `runtime_name: harness`, and matching version |
+| npm publish | OK | `@ps-neko/nekowork@alpha` points at `0.1.0-alpha.4` |
 | Source install | OK | Clone, local checkout, and submodule workflows are documented |
-| Public npm alpha | OK | `docs/PUBLISH-ALPHA.md` records the first alpha publish and the `0.1.0-alpha.2` alpha update |
-| CLI doctor | OK | `doctor`, `doctor --quick`, and `doctor --gemini-smoke` are available |
+| Public npm alpha | OK | `docs/PUBLISH-ALPHA.md` records the first alpha publish and the `0.1.0-alpha.4` alpha update |
+| CLI doctor/check | OK | `check`, `doctor`, `doctor --quick`, and `doctor --gemini-smoke` are available |
 | Provider auth | OK | Local delegated CLI auth is the default path |
 | Internal provider adapter | OK | `HARNESS_PROVIDER_OVERRIDE=internal` can call an explicit JSON command adapter without weakening gates |
 | Catalog | OK | 7 official packs, 11 agents, 10 skills, 5 hooks, 7 modules, 36 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 -> report -> gate status` path |
-| Fresh npm alpha smoke | OK | CI runs `npx -y @ps-neko/nekowork@alpha doctor --quick --json` from a disposable directory |
+| Fresh npm alpha smoke | OK | CI runs `npx -y @ps-neko/nekowork@alpha check --json` from a disposable directory |
 | Report UX | OK | `report` writes inspect-only `REPORT.md` and `report-summary.json` from session evidence |
 | External demo | OK | `npm run demo:external` verifies a disposable target project flow |
-| Third-party case studies | OK | `docs/case-studies/` records real public repository runs for npm package, auth boundary, and Python protocol targets |
+| Third-party case studies | OK | `docs/case-studies/` records real public repository runs for npm package, auth boundary, Python protocol, and environment configuration targets |
 | Decomposed workflow | OK | `ask`, `team`, `work`, `verify`, `gate`, `ship`, `report`, `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` |
@@ -30,7 +30,7 @@ This audit summarizes the current NEKOWORK state after publishing the `0.1.0-alp
 | 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.1.0-alpha.2` is tagged and published as a GitHub prerelease |
+| Release | OK | `v0.1.0-alpha.4` is tagged and published as a GitHub prerelease |
 
 ## Verification Gates
 
@@ -55,7 +55,7 @@ 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`: 245 tests pass
+- `npm test`: 252 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
@@ -63,9 +63,9 @@ Current local result for this working tree:
 - `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`: `0.1.0-alpha.2` published
-- `npm view @ps-neko/nekowork dist-tags version versions --json`: `alpha` points at `0.1.0-alpha.2`; `latest` remains `0.1.0-alpha.0`
-- `npx -y @ps-neko/nekowork@alpha doctor --quick`: passed for `0.1.0-alpha.2` with WARN summary from non-git project root and Gemini auth not checked
+- `npm publish --access public --tag alpha`: `0.1.0-alpha.4` published
+- `npm view @ps-neko/nekowork dist-tags version versions --json`: `alpha` points at `0.1.0-alpha.4`; `latest` remains `0.1.0-alpha.0`
+- `npx -y @ps-neko/nekowork@alpha check`: passed for `0.1.0-alpha.4` with WARN summary from non-git project root and Gemini auth not checked
 
 ## Completed Work
 
@@ -92,15 +92,15 @@ Current local result for this working tree:
 - `report` gives public alpha users a readable inspect-only session artifact without applying or mutating project files.
 - Official packs expose curated install shapes without creating a second safety model.
 - Checked-in example fixtures now cover financial UI, CI hardening, and quality lifecycle evidence flows.
-- Third-party case studies record NEKOWORK runs against `sindresorhus/is-plain-obj`, `jshttp/basic-auth`, and `python-hyper/h11`.
-- Public npm alpha `0.1.0-alpha.2` is published under the `alpha` dist-tag.
+- Third-party case studies record NEKOWORK runs against `sindresorhus/is-plain-obj`, `jshttp/basic-auth`, `python-hyper/h11`, and `motdotla/dotenv`.
+- Public npm alpha `0.1.0-alpha.4` is published under the `alpha` dist-tag.
 
 ## Remaining Optional Work
 
 | Item | Priority | Reason |
 |---|---|---|
 | Stable `latest` promotion | Medium | `alpha` is correct; npm keeps `latest` on the first alpha line for now, so move it to a stable version later |
-| More third-party case studies | Low | Three public repo case studies exist; more frameworks can still improve adoption evidence later |
+| More third-party case studies | Low | Four public repo case studies exist; more frameworks can still improve adoption evidence later |
 | More skill catalog expansion | Low | Catalog expansion should stay selective to preserve progressive disclosure |
 
 ## Explicit Non-Goals
@@ -118,5 +118,5 @@ Current external readiness, excluding broader adoption evidence: **9.1 / 10**.
 Main deductions:
 
 - `latest` currently remains on the first alpha; docs still recommend `@alpha` until a stable release exists.
-- Three independent real-world external project case studies exist so far.
+- Four independent real-world external project case studies exist so far.
 - Advanced surfaces exist but are intentionally secondary to the public decomposed workflow and install flow.

package/docs/CATALOG-PACKS.md

@@ -19,8 +19,8 @@ Packs are public install aliases over validated profiles. They make the catalog
 10 skills
 5 hooks
 5 harness targets
-6 case-study flows
-245 tests
+7 case-study flows
+252 tests
 ```
 
 Harness targets:
@@ -38,6 +38,7 @@ quality lifecycle smoke
 npm package boundary
 auth parser boundary
 Python protocol parser boundary
+environment configuration boundary
 ```
 
 ## Official Packs

package/docs/CHANGELOG.md

@@ -4,7 +4,34 @@
 
 ## [Unreleased]
 
-No unreleased changes yet.
+### Added
+- No entries yet.
+
+### Changed
+- No entries yet.
+
+## [0.1.0-alpha.4] - 2026-05-08
+
+### Added
+- Add release-surface version consistency coverage, bringing the suite to 252 tests.
+
+### Changed
+- Align published alpha smoke, feedback templates, and demo docs around the beginner `check` command.
+- Align `agent.yaml`, setup, porting, demo, and runbook release references with the package version.
+- Document `npx @alpha init --project-root .` as the shortest target-project install path.
+
+## [0.1.0-alpha.3] - 2026-05-08
+
+### Added
+- Add a `motdotla/dotenv` third-party case study for environment configuration and secret-loading boundary evidence.
+- Add alpha feedback triage guidance and issue-template classification fields.
+- Add beginner `check` and `init` CLI aliases for first-run health checks and install apply.
+- Add Safety Guarantees, Failure Modes, Trust Model, and Why Not Autopilot docs.
+- Add trust-doc and CLI alias tests, bringing the suite to 251 tests.
+
+### Changed
+- Rewrite the README first screen around unverified-change prevention, Human Gate, explicit apply, and no-surprise safety.
+- Add a direct competitor choice table and clearer selective-catalog framing.
 
 ## [0.1.0-alpha.2] - 2026-05-08
 

package/docs/CODEMAPS/scripts.md

@@ -114,7 +114,7 @@ scripts/
 | `ci/validate-hooks.js` | _(none)_ | hooks/hooks.json schemas/hooks.schema.json . |
 | `ci/validate-manifests.js` | _(none)_ | agent.yaml + manifests/install-{profiles,modules,components}.json . 1) schema 2) |
 | `ci/validate-skills.js` | _(none)_ | skills/<name>/SKILL.md frontmatter schemas/skill.schema.json . agent.yaml skills . |
-| `cli.js` | _(none)_ | NEKOWORK/HARNESS CLI entrypoint. Public verbs: doctor, ask, plan, team, work, verify, gate, ship, apply, run, report, review, review-cycle,  |
+| `cli.js` | _(none)_ | NEKOWORK/HARNESS CLI entrypoint. Public verbs: check, init, doctor, ask, plan, team, work, verify, gate, ship, apply, run, report, review, r |
 | `core/auth-guard.js` | ` BLOCKED_ENV `, `assertDelegatedCliAuth` |  |
 | `core/build-roots.js` | `buildRoots` |  |
 | `core/cli-resolver.js` | `assertProviderCliTrust`, `isPathInside`, `resolveCli`, `resolveProviderCli` |  |

package/docs/CODEMAPS/tests.md

@@ -10,11 +10,13 @@ tests/
 |-- e2e/
 |   |-- case-studies-doc.test.js
 |   |-- external-demo.test.js
+|   |-- feedback-triage-doc.test.js
 |   |-- github-actions-hardening-example.test.js
 |   |-- quality-lifecycle-example.test.js
 |   |-- quick-demo.test.js
 |   |-- review-cycle.test.js
-|   `-- trading-dashboard-example.test.js
+|   |-- trading-dashboard-example.test.js
+|   `-- trust-docs.test.js
 |-- integration/
 |   `-- build-pipeline.test.js
 |-- optional/
@@ -49,6 +51,7 @@ tests/
     |-- team.test.js
     |-- token-vault.test.js
     |-- verify.test.js
+    |-- version-consistency.test.js
     |-- wait.test.js
     `-- work.test.js
 ```
@@ -59,11 +62,13 @@ tests/
 |---|---|---|
 | `e2e/case-studies-doc.test.js` | _(none)_ |  |
 | `e2e/external-demo.test.js` | _(none)_ |  |
+| `e2e/feedback-triage-doc.test.js` | _(none)_ |  |
 | `e2e/github-actions-hardening-example.test.js` | _(none)_ |  |
 | `e2e/quality-lifecycle-example.test.js` | _(none)_ |  |
 | `e2e/quick-demo.test.js` | _(none)_ |  |
 | `e2e/review-cycle.test.js` | _(none)_ | E2E smoke tests for the deterministic mock review flow. |
 | `e2e/trading-dashboard-example.test.js` | _(none)_ |  |
+| `e2e/trust-docs.test.js` | _(none)_ |  |
 | `integration/build-pipeline.test.js` | _(none)_ | : install plan apply 5 state repair . . .harness/install-state.json . |
 | `optional/keychain-smoke.test.js` | _(none)_ | OS keychain . npm test (tests/optional/ ). : HARNESS_KEYCHAIN_SMOKE=1 npm run test:keychain : HARNESS_KEYCHAIN_SMOKE=1 node --test tests/opt |
 | `unit/acceptance-criteria.test.js` | _(none)_ |  |
@@ -95,6 +100,7 @@ tests/
 | `unit/team.test.js` | _(none)_ |  |
 | `unit/token-vault.test.js` | _(none)_ |  |
 | `unit/verify.test.js` | _(none)_ |  |
+| `unit/version-consistency.test.js` | _(none)_ |  |
 | `unit/wait.test.js` | _(none)_ |  |
 | `unit/work.test.js` | _(none)_ |  |
 

package/docs/DEMO.md

@@ -8,7 +8,7 @@ This demo uses mock providers. It does not call Claude, Codex, Gemini, or paid A
 npm run demo:quick -- --cleanup
 ```
 
-This is the shortest demo path. It creates a disposable target project, runs `doctor --quick`, runs `run = work -> verify -> ship`, generates `REPORT.md`, checks `gate status`, and removes the target when `--cleanup` is set.
+This is the shortest demo path. It creates a disposable target project, runs `check`, runs `run = work -> verify -> ship`, generates `REPORT.md`, checks `gate status`, and removes the target when `--cleanup` is set.
 
 Expected shape:
 
@@ -28,7 +28,7 @@ This transcript is the README-friendly demo path. It uses mock providers, so it
 ![NEKOWORK one-minute terminal demo](assets/demo-terminal.svg)
 
 ```text
-$ npx -y @ps-neko/nekowork@alpha doctor --quick
+$ npx -y @ps-neko/nekowork@alpha check
 NEKOWORK doctor
 STATUS  CHECK              MESSAGE
 PASS    node               Node 22+
@@ -67,7 +67,7 @@ The quick demo writes:
 npm run demo:external
 ```
 
-This creates a tiny disposable target project, applies the `developer` profile, runs `doctor --quick`, and writes a planning session into the target project's `.harness/` directory. See [EXAMPLE-PROJECT.md](EXAMPLE-PROJECT.md) for details.
+This creates a tiny disposable target project, applies the `developer` profile, runs `check`, and writes a planning session into the target project's `.harness/` directory. See [EXAMPLE-PROJECT.md](EXAMPLE-PROJECT.md) for details.
 
 ## Command
 
@@ -143,7 +143,7 @@ project root : C:\path\to\harness
 
 STATUS  CHECK                   MESSAGE
 PASS    node                    Node 24.x
-PASS    package metadata        @ps-neko/nekowork@0.1.0-alpha.2; public alpha package
+PASS    package metadata        @ps-neko/nekowork@0.1.0-alpha.4; public alpha package
 PASS    git worktree            project root is inside a git worktree
 WARN    gemini cli              installed, auth status is not checked non-interactively
 

package/docs/FAILURE-MODES.md

@@ -0,0 +1,94 @@
+# Failure Modes
+
+NEKOWORK should fail in ways that leave evidence behind and avoid surprise writes.
+
+## Health Check Warnings
+
+`check` is a quick alias for `doctor --quick`.
+
+Typical warnings include:
+
+- target directory is not a git repository
+- provider CLI is missing
+- optional live auth was not checked
+- package metadata is present but not release-ready
+
+Warnings are meant to tell the user what would matter for live work. They do not mutate the project.
+
+## No-Ship
+
+`ship` writes `NO_SHIP` when the session has unresolved quality, security, or acceptance risk.
+
+Recovery path:
+
+```bash
+node scripts/cli.js report --session <id>
+node scripts/cli.js run "fix the reported blocker" --session <new-id>
+node scripts/cli.js gate status --session <new-id>
+```
+
+`apply` refuses a no-ship session unless a maintainer intentionally changes the evidence flow.
+
+## Human Gate
+
+`HUMAN_GATE` means the tool found risk that needs a person before apply.
+
+The user can:
+
+```bash
+node scripts/cli.js gate status --session <id>
+node scripts/cli.js gate approve --session <id> --reason "reviewed risk"
+node scripts/cli.js gate block --session <id> --reason "needs more tests"
+```
+
+Approval records evidence. Blocking keeps the session from shipping.
+
+## Apply Refusal
+
+`apply` can refuse when:
+
+- there is no live-work diff
+- `SHIP_READY` is missing
+- a newer `NO_SHIP` exists
+- `HUMAN_GATE` is unresolved
+- the target worktree is dirty
+
+Recovery path:
+
+```bash
+git status -sb
+node scripts/cli.js report --session <id>
+node scripts/cli.js gate status --session <id>
+```
+
+Then either fix the blocker, approve/block the gate, or rerun the session.
+
+## Stale Generated Files
+
+When catalog, tests, or generated docs change, codemap or generated-output checks may fail.
+
+Recovery path:
+
+```bash
+node scripts/build-codemaps.js
+npm test
+```
+
+The generated diff should be reviewed like any other project change.
+
+## Provider Auth Problems
+
+Default mock mode does not require provider auth.
+
+Live mode can fail if local CLI auth is missing or expired. In that case, log in through the provider CLI, then rerun the same command. NEKOWORK does not need long-lived API-key fallback for the normal delegated CLI path.
+
+## npm / npx Problems
+
+If `npx -y @ps-neko/nekowork@alpha check` fails, capture:
+
+- OS and shell
+- Node and npm versions
+- exact command
+- redacted output
+
+Then open an alpha feedback issue with the triage template.