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

package/CLAUDE.md

@@ -8,7 +8,7 @@
 
 ## 자동 갱신 영역
 
-<!-- HARNESS:START version=0.1.0-alpha.2 -->
+<!-- HARNESS:START version=0.1.0-alpha.3 -->
 <!-- 이 영역은 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 / 251 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,31 @@ 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 from a source checkout:
+
+```bash
+node /path/to/harness/scripts/cli.js init --profile developer --project-root /path/to/my-project
+```
+
 ## Example Report
 
 `report` is the main trust surface. It turns session evidence into a readable `REPORT.md`:
@@ -51,6 +86,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 +115,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 +139,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.3`
 - 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.3`
 - 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 +149,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`: 251 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 +164,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 +189,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 +209,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 +217,12 @@ 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 from this checkout:
+
+```bash
+node /path/to/harness/scripts/cli.js init --profile developer --project-root /path/to/my-project
+```
+
 Advanced path:
 
 ```text
@@ -168,13 +239,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
 
@@ -338,7 +411,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.3.tgz`. It does not publish.
 
 ## Documentation
 
@@ -347,6 +420,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/docs/AUDIT.md

@@ -2,17 +2,17 @@
 
 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.3` 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.3`, `agent.yaml` uses `name: nekowork`, `runtime_name: harness` |
+| npm publish | OK | `@ps-neko/nekowork@alpha` points at `0.1.0-alpha.3` |
 | 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.3` 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 |
@@ -21,7 +21,7 @@ This audit summarizes the current NEKOWORK state after publishing the `0.1.0-alp
 | Fresh npm alpha smoke | OK | CI runs `npx -y @ps-neko/nekowork@alpha doctor --quick --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.3` 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`: 251 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.3` published
+- `npm view @ps-neko/nekowork dist-tags version versions --json`: `alpha` points at `0.1.0-alpha.3`; `latest` remains `0.1.0-alpha.0`
+- `npx -y @ps-neko/nekowork@alpha check`: passed for `0.1.0-alpha.3` 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.3` 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
+251 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,21 @@
 
 ## [Unreleased]
 
-No unreleased changes yet.
+### Added
+- No entries yet.
+
+## [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/
@@ -59,11 +61,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)_ |  |

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 doctor --quick` fails, capture:
+
+- OS and shell
+- Node and npm versions
+- exact command
+- redacted output
+
+Then open an alpha feedback issue with the triage template.

package/docs/FEEDBACK-TRIAGE.md

@@ -0,0 +1,144 @@
+# Alpha Feedback Triage
+
+Status date: 2026-05-08
+
+This guide turns public alpha feedback into evidence-backed next steps without weakening NEKOWORK's safety model.
+
+Use it for GitHub issues filed through:
+
+- Alpha feedback
+- Bug report
+- Direct maintainer notes that include `doctor --quick --json`, `REPORT.md`, or install output
+
+## Triage Principles
+
+- Redact first. Remove secrets, tokens, private paths, proprietary code, and private repository names before copying issue content into docs or release notes.
+- Reproduce before changing behavior. Prefer a fresh `npx @alpha` smoke, a source-checkout smoke, or a disposable target project.
+- Keep no-ship evidence visible. A confusing or blocked run is still useful if it records `REPORT.md`, `NO_SHIP`, `verify-summary.json`, or `ship-summary.json`.
+- Do not convert feedback into automatic apply, publish, deploy, push, or PR behavior.
+- Do not make API keys the default provider path. Delegated local CLI auth remains the recommended path.
+
+## Initial Classification
+
+| Class | Signals | First response |
+|---|---|---|
+| Install failure | `npx`, npm, Node version, package metadata, binary resolution | Ask for OS/shell, Node/npm, exact command, and `doctor --quick --json` |
+| Auth confusion | Claude/Codex/Gemini login status, API key warning, provider CLI path | Clarify delegated CLI auth and ask whether env API keys were set intentionally |
+| Evidence confusion | Missing `REPORT.md`, unclear verdict, no `NO_SHIP`, acceptance coverage confusion | Ask for session path and report summary; link report contract |
+| Safety concern | apply, commit, push, publish, deploy, secrets, destructive changes | Confirm no automatic mutation occurred; request redacted logs and gate/ship summaries |
+| Platform mismatch | Windows path, shell quoting, CRLF, file URL, temp directory behavior | Reproduce on the named OS/shell before changing docs or code |
+| Product request | New agent, skill, pack, provider, workflow shortcut | Accept only if it strengthens verification evidence or first-run clarity |
+
+## Minimum Evidence
+
+An issue is actionable when it includes at least three of:
+
+- NEKOWORK version or git commit
+- install path, for example `npx @ps-neko/nekowork@alpha`
+- OS and shell
+- Node and npm versions
+- exact command
+- redacted `doctor --quick --json`
+- redacted `REPORT.md` summary
+- session evidence file names, such as `verify-summary.json` or `ship-summary.json`
+- expected behavior and actual behavior
+
+If the issue is about ship/apply safety, require:
+
+- `ship-summary.json` or `REPORT.md` summary
+- gate status
+- whether `apply` was requested
+- target project git status after the run
+
+## Severity
+
+| Severity | Meaning | Examples |
+|---|---|---|
+| Critical | Safety invariant appears bypassed | automatic apply, publish, deploy, push, PR, or secret exposure |
+| High | First-run or release path is blocked for a supported setup | `npx @alpha doctor --quick` fails on supported Node/npm |
+| Medium | Important docs or workflow confusion with a workaround | unclear report output, install docs missing platform note |
+| Low | Enhancement or polish | copy edit, new example request, extra case-study suggestion |
+
+Critical and high issues should keep `ship_ready=false` until reproduced or explicitly dismissed with evidence.
+
+## Reproduction Path
+
+Start with the smallest command that matches the report:
+
+```bash
+npx -y @ps-neko/nekowork@alpha doctor --quick --json
+```
+
+For source checkout reports:
+
+```bash
+git status --short --branch
+npm run lint
+npm test
+npm audit --audit-level=moderate
+```
+
+For target project reports:
+
+```bash
+node scripts/portability/simulate-port.js <target> --profile developer --json
+node scripts/cli.js doctor --quick --project-root <target> --json
+node scripts/cli.js report --session <session> --project-root <target> --stdout
+node scripts/cli.js gate status --session <session> --project-root <target> --json
+```
+
+Use `--profile security --secure` when the report involves auth, secrets, deploy, financial, or environment configuration boundaries.
+
+## Decision Outcomes
+
+| Outcome | Use when | Required evidence |
+|---|---|---|
+| Docs-only fix | Behavior is correct but unclear | before/after docs diff, command output if relevant |
+| Test-backed fix | Behavior is wrong or regressed | failing test or reproduced command, passing test after fix |
+| Case study | Feedback shows a new risk class or platform behavior | target commit, target test result, NEKOWORK run summary |
+| Release blocker | Public alpha install or safety invariant is broken | failed `@alpha` smoke or invariant evidence |
+| Not planned | Request weakens safety model or expands catalog without evidence value | explanation tied to product invariants |
+
+## Labels
+
+Recommended labels:
+
+- `alpha-feedback`
+- `bug`
+- `needs-repro`
+- `needs-evidence`
+- `docs`
+- `release-blocker`
+- `safety`
+- `platform-windows`
+- `platform-macos`
+- `platform-linux`
+
+If labels do not exist yet, use the same words in a maintainer comment.
+
+## Maintainer Response Template
+
+```markdown
+Thanks for the report. I am triaging this as `<class>` / `<severity>`.
+
+Evidence received:
+- Version:
+- Install path:
+- OS/shell:
+- Command:
+- doctor/report evidence:
+
+Next step:
+- reproduce with:
+- expected gate:
+- ship/apply status should remain:
+```
+
+## Alpha.3 Gate
+
+Do not publish `0.1.0-alpha.3` for feedback-only changes until:
+
+- `@alpha` smoke remains green
+- new feedback docs or templates are covered by tests
+- any release-blocker feedback is closed or documented as unresolved
+- changelog entries match the intended alpha.3 contents