@ps-neko/nekowork 0.1.0-alpha.0

package/docs/QUICKSTART.md

@@ -0,0 +1,344 @@
+# Quickstart
+
+This guide gets a new user from a clean checkout to the first NEKOWORK run.
+
+## 1. Install From Source
+
+HARNESS `0.1.0-alpha.0` is prepared as a public alpha candidate but is not published to npm yet. Use the repository path:
+
+```bash
+git clone https://github.com/Ps-Neko/NEKOWORK.git harness
+cd harness
+npm ci
+```
+
+Verify the checkout:
+
+```bash
+node scripts/cli.js doctor --quick
+```
+
+`doctor --quick` checks Node.js, package metadata, git state, API key overrides, and provider CLI presence without running the slower freshness checks.
+
+## 2. One-Minute Demo
+
+Use this first when you want the shortest no-API experience:
+
+```bash
+npm run demo:quick -- --cleanup
+```
+
+The quick demo creates a disposable target project, runs `doctor -> run -> gate status`, and removes the target when `--cleanup` is set. It uses mock providers and does not call Claude, Codex, Gemini, or paid APIs.
+
+Expected shape:
+
+```text
+doctor ... OK
+run workflow ... OK
+gate status ... OK
+Demo completed: verdict=approve_with_fixes, ship_ready=false, applied=false
+```
+
+## 3. Beginner Path
+
+Use this path first. It is the recommended shortest safe loop:
+
+```bash
+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` is the short safe wrapper. It runs `work -> verify -> ship`, does not apply by default, and stops on Human Gate. `apply` is always explicit and requires a verified `SHIP_READY` live-work diff.
+
+## 4. Run A Mock Review
+
+Mock mode is the default. It does not call Claude, Codex, Gemini, or any paid API.
+
+For ambiguous or risky work, start with the local question gate:
+
+```bash
+node scripts/cli.js ask "trading dashboard mockup" --session first-ask
+```
+
+`ask` creates a question-gate handoff only. It does not call providers and does not mutate project files.
+
+```bash
+node scripts/cli.js review "check the project setup" --no-ship --session first-smoke
+```
+
+Expected result:
+
+- session state under `.harness/state/sessions/first-smoke/`
+- handoff markdown files under `handoffs/`
+- `review-summary.json` with `mode: legacy-full-review-cycle`
+- no PR or publish action because `--no-ship` is set
+
+Example output:
+
+```text
+[review:first-smoke] 1 ideate
+[review:first-smoke] 2 plan
+[review:first-smoke] 3 implement
+[review:first-smoke] 4 self-review
+[review:first-smoke] 5 codex-review
+[review:first-smoke] 7 ship skipped (--no-ship)
+```
+
+`review-cycle` is an explicit alias for the same legacy full cycle:
+
+```bash
+node scripts/cli.js review-cycle "check the project setup" --no-ship --session first-review-cycle
+```
+
+For a planning-only first pass:
+
+```bash
+node scripts/cli.js plan "draft an implementation plan" --session first-plan
+```
+
+For multiple read-only perspectives before implementation:
+
+```bash
+node scripts/cli.js team "trading dashboard mockup" --workers planner,research,security,test --no-write --session first-team
+```
+
+`team` writes handoffs and a `team-summary.json` file. It does not run an implement stage and does not mutate project files.
+
+For a single-executor implementation handoff:
+
+```bash
+node scripts/cli.js work "implement the planned dashboard mockup" --single-executor --session first-work
+```
+
+In mock mode this writes an implement handoff only. In live mode the executor works in an isolated git worktree and NEKOWORK captures a diff under the session; the target project is not changed until a later verified apply path exists. `work` also writes `acceptance-criteria.json`, reusing `prd.json` when available or creating a deterministic minimum from the task.
+
+Then verify that work with Codex:
+
+```bash
+node scripts/cli.js verify "verify the planned dashboard mockup" --session first-work
+```
+
+`verify` reads the prior `work` handoff and optional diff. It does not implement or ship. Add `--secure` when you want Codex challenge even if the task is not auto-detected as sensitive.
+
+If verification creates a human gate, inspect it:
+
+```bash
+node scripts/cli.js gate status --session first-work
+```
+
+Then make an explicit human decision:
+
+```bash
+node scripts/cli.js gate approve --session first-work --reason "Reviewed and accepted this risk"
+node scripts/cli.js gate block --session first-work --reason "Release risk rejected"
+```
+
+`gate approve` requires an open `HUMAN_GATE`. It records approval for audit; it does not delete the original gate file.
+
+Then produce a ship/no-ship readiness handoff:
+
+```bash
+node scripts/cli.js ship "prepare dashboard ship readiness" --require-clean-gates --session first-work
+```
+
+`ship` requires the prior `work` and `verify` handoffs. It does not publish, deploy, create a PR, or mutate the target project. If Codex reported fixable findings, `ship` writes a no-ship handoff and `NO_SHIP`; if Codex fully approved, it writes `SHIP_READY`. Existing `HUMAN_GATE` always blocks it.
+
+For live work that produced a captured diff, apply it only after ship readiness:
+
+```bash
+node scripts/cli.js apply --session first-work
+```
+
+`apply` requires `SHIP_READY`, no newer `NO_SHIP`, no unresolved gate, a clean git worktree excluding `.harness/` state, and a captured diff from `work --live`. It applies the diff but does not commit, push, publish, or deploy.
+
+To run the decomposed wrapper in one command:
+
+```bash
+node scripts/cli.js run "implement and verify a change" --session first-run
+```
+
+`run` executes `work -> verify -> ship`. It does not apply by default. Add `--apply` only when live work produced a captured diff and you want the verified `SHIP_READY` diff applied.
+
+## 5. Inspect The Install Catalog
+
+```bash
+node scripts/install-plan.js --list
+node scripts/install-plan.js --profile developer
+node scripts/install-plan.js --profile developer --target claude --json
+```
+
+Profiles:
+
+- `core`: minimal rules, agents, hooks, and platform configs
+- `developer`: daily development, quality workflow, Codex loop, ops-readiness
+- `security`: secure review defaults
+- `product`: question gate, scope review, acceptance criteria
+- `quality`: disciplined workflow, test-first planning, evidence-based review
+- `frontend`: UI mockup, component review, accessibility-oriented flow
+- `testing`: test planning, regression, and coverage-oriented flow
+- `research`: research-oriented profile
+- `full`: every current module
+
+## 6. Use HARNESS In A Target Project
+
+For a disposable end-to-end target project demo:
+
+```bash
+npm run demo:external
+```
+
+Add `-- --cleanup` if you want the generated target removed after the run:
+
+```bash
+npm run demo:external -- --cleanup
+```
+
+See [EXAMPLE-PROJECT.md](EXAMPLE-PROJECT.md) for the full walkthrough and expected outputs.
+
+For small checked-in case-study targets, inspect:
+
+```text
+examples/trading-dashboard-mock/
+examples/github-actions-hardening/
+```
+
+Each example has its own `npm test` and NEKOWORK case-study artifacts under `case-study/`.
+
+Recommended 0.0.3 integration:
+
+```bash
+cd <target-project>
+git submodule add https://github.com/Ps-Neko/NEKOWORK.git .harness-tool
+```
+
+Run a non-destructive preflight:
+
+```bash
+node .harness-tool/scripts/portability/simulate-port.js . --profile developer --verbose
+```
+
+Apply generated harness surfaces:
+
+```bash
+node .harness-tool/scripts/install-apply.js --profile developer --project-root .
+```
+
+Smoke test in the target project:
+
+```bash
+node .harness-tool/scripts/cli.js doctor --project-root . --quick
+node .harness-tool/scripts/cli.js plan "target project smoke" --project-root . --session target-smoke
+```
+
+Expected outputs in the target project:
+
+- `.harness/install-state.json`
+- `.harness/state/sessions/target-smoke/`
+- `.claude/`
+- `.codex/config.toml`
+- `.cursor/hooks.json`
+- `.gemini/GEMINI.md`
+- `.opencode/config.json`
+
+## 7. Turn On Live Provider Calls
+
+Live mode uses local CLI sessions by default.
+
+Claude:
+
+```bash
+claude auth status
+npm run verify:claude
+```
+
+Codex:
+
+```bash
+npm install -g @openai/codex
+codex login
+npm run verify:codex
+```
+
+Gemini:
+
+```bash
+gemini
+npm run verify:gemini
+node scripts/cli.js doctor --quick --gemini-smoke
+```
+
+Plain `doctor` reports Gemini installation only. Add `--gemini-smoke` when you want the live Gemini auth check included in the health report.
+
+Then run:
+
+```bash
+node scripts/cli.js review "live provider smoke" --live --no-ship
+```
+
+If you have API key environment variables set, HARNESS blocks them by default before delegated CLI calls. Unset them for local CLI auth:
+
+```bash
+unset ANTHROPIC_API_KEY
+unset OPENAI_API_KEY
+unset GEMINI_API_KEY
+unset GOOGLE_API_KEY
+```
+
+On PowerShell:
+
+```powershell
+Remove-Item Env:ANTHROPIC_API_KEY -ErrorAction SilentlyContinue
+Remove-Item Env:OPENAI_API_KEY -ErrorAction SilentlyContinue
+Remove-Item Env:GEMINI_API_KEY -ErrorAction SilentlyContinue
+Remove-Item Env:GOOGLE_API_KEY -ErrorAction SilentlyContinue
+```
+
+## 8. Future npm Install Path
+
+The package metadata is prepared as `@ps-neko/nekowork@0.1.0-alpha.0`, but publish execution requires npm owner auth.
+
+After the public alpha is published, the intended install paths are:
+
+```bash
+npm i --save-dev @ps-neko/nekowork
+```
+
+or:
+
+```bash
+npm i -g @ps-neko/nekowork
+```
+
+Do not use these npm commands until a public package has actually been published.
+
+## Troubleshooting
+
+`npm ci` fails:
+
+- Confirm Node.js 22 or newer with `node -v`.
+- Check corporate proxy or registry settings in `.npmrc`.
+
+`--live` fails immediately:
+
+- Confirm the provider CLI is installed and logged in.
+- Unset API key environment variables unless you intentionally opted into a metered path.
+
+`doctor` exits with `FAIL`:
+
+- Read the failed row first.
+- Run without `--quick` if you need repair/sync/codemap freshness checks.
+- Use `--json` for CI or issue reports.
+
+`repair --check` reports stale output:
+
+- Run `node scripts/repair.js`.
+- Then rerun `node scripts/repair.js --check`.
+
+`sync-claude-md --check` reports a diff:
+
+- Run `node scripts/sync-claude-md.js`.
+
+`build-codemaps --check` reports stale codemaps:
+
+- Run `node scripts/build-codemaps.js`.

package/docs/RELEASE-READINESS.md

@@ -0,0 +1,140 @@
+# Release Readiness
+
+Status date: 2026-05-07
+
+NEKOWORK / HARNESS is release-ready for local use and repository-based installation. Public npm publishing is prepared as an alpha candidate, but execution requires npm owner auth.
+
+## Decision
+
+- Decision: do not publish 0.0.3 to npm.
+- Public alpha candidate: `0.1.0-alpha.0`, publish with `--tag alpha`.
+- `package.json` is set to `private: false` for the public alpha candidate.
+- The canonical repo is `Ps-Neko/NEKOWORK`.
+- Current release track is `0.1.0-alpha.0`.
+- Required local provider auth is delegated CLI auth, not long-lived API keys.
+- Core workflow invariant is Claude work -> Codex verification -> Human Gate.
+- Risk classifier, acceptance criteria artifacts, and profile safety validation are part of the release gate.
+- Remaining optional work is internal project/provider integration on request.
+- Public package metadata is prepared as `@ps-neko/nekowork`, but actual `npm publish` still requires npm owner auth.
+- See [PUBLISH-ALPHA.md](PUBLISH-ALPHA.md) for the public alpha checklist.
+
+## Required Gates
+
+Run these before a release tag 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 run security:hardening
+npm pack --dry-run --json
+npm publish --dry-run --access public --tag alpha
+```
+
+Current local verification after the decomposed workflow expansion:
+
+- `npm run test:unit`: covered by full `npm test`
+- `npm run validate:all`: pass
+- `npm run lint`: pass
+- `node scripts/sync-claude-md.js --check`: pass
+- `node scripts/build-codemaps.js --check`: pass
+- `npm test`: 238 tests pass
+- `npm run demo:quick -- --cleanup`: 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`
+
+## Install Smoke
+
+For the default developer profile:
+
+```bash
+node scripts/install-plan.js --list --json
+node scripts/install-plan.js --profile developer --json
+node scripts/portability/simulate-port.js <target> --profile developer --json
+node scripts/install-apply.js --profile developer --project-root <target>
+node scripts/cli.js plan "release readiness smoke" --project-root <target>
+node scripts/cli.js run "release readiness decomposed smoke" --project-root <target> --session release-run-smoke
+```
+
+The disposable install equivalent is:
+
+```bash
+npm run demo:external -- --cleanup
+```
+
+Expected target outputs:
+
+- `.harness/install-state.json`
+- `.harness/state/sessions/`
+- `.harness/state/sessions/release-run-smoke/run-summary.json`
+- `.claude/`
+- `.codex/config.toml`
+- `.cursor/hooks.json`
+- `.gemini/GEMINI.md`
+- `.opencode/config.json`
+
+The one-command workflow equivalent is:
+
+```bash
+npm run demo:quick -- --cleanup
+```
+
+Expected quick-demo outputs:
+
+- `.harness/state/sessions/<session>/work-summary.json`
+- `.harness/state/sessions/<session>/verify-summary.json`
+- `.harness/state/sessions/<session>/ship-summary.json`
+- `.harness/state/sessions/<session>/run-summary.json`
+
+## Full Builder Smoke
+
+The install profile currently projects the runtime-required Claude/Codex surfaces. The full builder surface is verified separately:
+
+```bash
+HARNESS_PROJECT_ROOT=<target> node scripts/build-claude.js
+HARNESS_PROJECT_ROOT=<target> node scripts/build-codex.js
+HARNESS_PROJECT_ROOT=<target> node scripts/build-cursor.js
+HARNESS_PROJECT_ROOT=<target> node scripts/build-gemini.js
+HARNESS_PROJECT_ROOT=<target> node scripts/build-opencode.js
+```
+
+Expected target outputs:
+
+- `.claude/`
+- `.codex/config.toml`
+- `.cursor/hooks.json`
+- `.gemini/GEMINI.md`
+- `.opencode/config.json`
+
+## Not Included
+
+- `npm publish`
+- Public package publish execution, pending npm owner auth
+- Internal LLM provider wiring
+- Internal project rollout
+- Automatic apply, commit, push, PR creation, release, or deploy
+- Automatic promotion of learned instincts without human approval
+
+## Public npm Checklist
+
+Only run this checklist after the project owner explicitly approves public publishing:
+
+1. Confirm the npm package name is still `@ps-neko/nekowork`.
+2. Confirm the `harness` binary is still intentional.
+3. Confirm the public alpha version is `0.1.0-alpha.0`.
+4. Run the required gates above.
+5. Inspect `npm pack --dry-run --json` and confirm only intended files are included.
+6. Confirm npm account access and 2FA readiness with `npm whoami`.
+7. Confirm `private: false` in `package.json`.
+8. Publish with `npm publish --access public --tag alpha`.
+9. Smoke test from a fresh directory with `npx @ps-neko/nekowork@alpha doctor --quick`.
+10. Restore documentation from "future npm path" to "published npm path" where appropriate.

package/docs/RISK-CLASSIFIER.md

@@ -0,0 +1,50 @@
+# Risk Classifier
+
+NEKOWORK classifies task and file risk before verification and ship readiness. The shared implementation lives in:
+
+```text
+scripts/lib/risk-classifier.js
+```
+
+## Outputs
+
+The classifier returns:
+
+- `risk`: `low`, `medium`, `high`, or `critical`
+- `tags`: detected risk categories
+- `requiresCodexChallenge`: whether Codex challenge should run
+- `requiresHumanGate`: whether a human decision is required
+- `sensitive`: whether the work is sensitive for challenge/gate purposes
+
+## Gate-Sensitive Tags
+
+| Tag | Examples | Policy |
+|---|---|---|
+| `security` | auth, OAuth, JWT, token, secret, TLS, CSRF, CORS, XSS, webhook | Codex challenge |
+| `financial` | trading, broker, orders, payment, billing, refunds | Codex challenge + Human Gate |
+| `deploy` | production, release, CI/CD, workflows, cloud, infrastructure | Codex challenge + Human Gate |
+| `data` | database migration, delete, truncate, PII, rollback-sensitive work | Codex challenge |
+| `product-ui` | UI, UX, frontend, dashboard, mockup, prototype | scope questions |
+
+Critical verification findings always require Human Gate.
+
+## Current Enforcement
+
+- `ask` uses the classifier to shape questions and draft success criteria.
+- `dispatch` records classifier risk in routing traces.
+- `verify` uses it to decide Codex challenge and risk-policy Human Gate.
+- `ship` rechecks risk policy so seeded or manually edited sessions cannot bypass a gate.
+
+## Human Gate Reasons
+
+Verification handoffs trigger gate reasons when:
+
+- a Codex handoff returns `verdict: block`
+- any issue has `severity: critical`
+- task/file policy requires a human gate, such as financial or deploy-sensitive work
+
+The gate marker is written as:
+
+```text
+.harness/state/sessions/<id>/HUMAN_GATE
+```

package/docs/RUNBOOK.md

@@ -0,0 +1,146 @@
+# Runbook
+
+This is the operator checklist for maintaining NEKOWORK.
+
+## Daily Health
+
+```bash
+git status --short --branch
+node scripts/cli.js doctor
+npm run lint
+npm test
+npm audit --audit-level=moderate
+```
+
+`doctor` exits with failure if required freshness checks fail. Use `--quick` for a faster local environment check. Use `node scripts/cli.js doctor --quick --gemini-smoke` when Gemini live auth readiness matters for the release or machine being checked.
+
+## Catalog Changes
+
+When changing `agent.yaml`, `agents/`, `skills/`, `hooks/`, `rules/`, `manifests/`, or generated docs:
+
+```bash
+npm run lint
+node scripts/repair.js
+node scripts/sync-claude-md.js
+node scripts/build-codemaps.js
+node scripts/repair.js --check
+node scripts/sync-claude-md.js --check
+node scripts/build-codemaps.js --check
+```
+
+Then run:
+
+```bash
+npm test
+```
+
+Profile changes must also preserve the profile safety validator:
+
+- every profile keeps the core modules
+- no profile can disable Codex verification or Human Gate
+- mutation policy cannot become parallel or unrestricted by profile default
+- outbound network cannot become unrestricted by profile default
+
+The validator runs through `npm run lint`.
+
+## Project Install Smoke
+
+Use a temporary target project:
+
+```bash
+node scripts/portability/simulate-port.js <target> --profile developer --verbose
+node scripts/install-apply.js --profile developer --project-root <target>
+node scripts/cli.js doctor --project-root <target> --quick
+node scripts/cli.js plan "release smoke" --project-root <target> --session release-smoke
+node scripts/cli.js run "release decomposed smoke" --project-root <target> --session release-run-smoke
+```
+
+Expected target outputs:
+
+- `.harness/install-state.json`
+- `.harness/state/sessions/release-smoke/`
+- `.harness/state/sessions/release-run-smoke/run-summary.json`
+- `.claude/`
+- `.codex/config.toml`
+- `.cursor/hooks.json`
+- `.gemini/GEMINI.md`
+- `.opencode/config.json`
+
+## Release Gates
+
+Before a tag, GitHub Release, or npm publish decision:
+
+```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
+```
+
+## Public npm Publish Checklist
+
+Do not run this checklist unless public publish is explicitly approved.
+
+1. Confirm `package.json#name` is `@ps-neko/nekowork`.
+2. Confirm the `harness` binary name is still intentional.
+3. Run all release gates.
+4. Inspect `npm pack --dry-run --json`.
+5. Confirm npm identity with `npm whoami`.
+6. Confirm account 2FA readiness.
+7. Confirm `private: false`.
+8. Confirm the public alpha version, for example `0.1.0-alpha.0`.
+9. Run `npm publish --access public --tag alpha`.
+10. Update README, Quickstart, Changelog, and release notes from "future npm path" to "published npm path".
+
+## GitHub Release Checklist
+
+```bash
+git tag -a v0.0.3 -m "HARNESS v0.0.3"
+git push origin v0.0.3
+npm pack --json
+gh release create v0.0.3 ps-neko-nekowork-0.0.3.tgz --title "HARNESS v0.0.3" --prerelease --notes-file <notes.md>
+```
+
+Remove the local tarball after it is uploaded.
+
+## Advanced Operations
+
+Advanced workflows are documented in [ADVANCED.md](ADVANCED.md):
+
+- `team-lite`
+- `ralph`
+- `wait`
+- `instincts`
+- cost tracking
+- Rust runtime
+
+## Troubleshooting
+
+`doctor` reports API key warnings:
+
+- Unset provider API keys for delegated local CLI auth.
+- Keep `HARNESS_AUTH_ALLOW_ENV_OVERRIDE=1` only for intentional metered paths.
+
+`repair --check` fails:
+
+- Run `node scripts/repair.js`.
+- Re-run `node scripts/repair.js --check`.
+
+`sync-claude-md --check` fails:
+
+- Run `node scripts/sync-claude-md.js`.
+
+`build-codemaps --check` fails:
+
+- Run `node scripts/build-codemaps.js`.
+
+CI fails on security hardening:
+
+- Check workflow permissions.
+- Check job timeouts.
+- Check MCP pins and HTTPS URLs.
+- Check package-lock and dependency specs.