@ps-neko/nekowork 0.1.0-alpha.0

package/docs/ADVANCED.md

@@ -0,0 +1,321 @@
+# Advanced Features
+
+The public alpha path focuses on `doctor`, `ask`, `plan`, `team`, `work`, `verify`, `gate`, `ship`, `apply`, `run`, `review`, `review-cycle`, and install/apply. This page keeps the larger runtime surface discoverable without crowding the first-run docs.
+
+## team
+
+`team` is the public read-only team handoff command:
+
+```bash
+node scripts/cli.js team "split and review this change" --workers planner,research,security,test --no-write --session team-smoke
+```
+
+Rules:
+
+- Workers create handoffs only.
+- No worker runs the `implement` stage.
+- All live Claude calls run in non-interactive handoff mode and are protected by the git mutation guard.
+- The next mutating step must be a single executor work/review cycle.
+
+Outputs:
+
+- `.harness/state/sessions/<id>/team.json`
+- `.harness/state/sessions/<id>/team-summary.json`
+- `.harness/state/sessions/<id>/handoffs/`
+
+## work
+
+`work` is the public single-executor implementation phase:
+
+```bash
+node scripts/cli.js work "implement the accepted plan" --single-executor --session work-smoke
+```
+
+Rules:
+
+- Only the `executor` agent runs.
+- Acceptance criteria are required as a session artifact and are written to `acceptance-criteria.json`.
+- Codex review does not run in this command.
+- Ship does not run in this command.
+- Mock mode writes an implement handoff only.
+- Live mode uses an isolated git worktree and persists a diff under the session.
+- The target project is not mutated directly by `work`.
+
+Outputs:
+
+- `.harness/state/sessions/<id>/work-summary.json`
+- `.harness/state/sessions/<id>/acceptance-criteria.json`
+- `.harness/state/sessions/<id>/handoffs/03-implement.md`
+- `.harness/state/sessions/<id>/handoffs/03-implement.json`
+- `.harness/state/sessions/<id>/diffs/` when live execution produces a diff
+
+## verify
+
+`verify` is the public Codex-only verification phase:
+
+```bash
+node scripts/cli.js verify "verify the accepted work" --session work-smoke
+node scripts/cli.js verify "verify sensitive auth work" --session work-smoke --secure
+```
+
+Rules:
+
+- A prior `work` handoff in the same session is required.
+- Codex review always runs.
+- Codex challenge runs when `--secure` is set or sensitive task/file names are detected.
+- The shared risk classifier decides challenge and Human Gate policy.
+- Implement does not run.
+- Ship does not run.
+- Critical or blocking findings write `HUMAN_GATE`.
+
+Outputs:
+
+- `.harness/state/sessions/<id>/verify-summary.json`
+- `.harness/state/sessions/<id>/handoffs/05-codex-review.md`
+- `.harness/state/sessions/<id>/handoffs/06-codex-challenge.md` when secure/challenge is active
+- `.harness/state/sessions/<id>/HUMAN_GATE` when Codex blocks or reports critical findings
+
+## gate
+
+`gate` is the explicit human decision phase:
+
+```bash
+node scripts/cli.js gate status --session work-smoke
+node scripts/cli.js gate approve --session work-smoke --reason "Reviewed and accepted the risk"
+node scripts/cli.js gate block --session work-smoke --reason "Release risk rejected"
+```
+
+Rules:
+
+- `status` inspects `HUMAN_GATE`, `GATE_APPROVED`, and `GATE_BLOCKED`.
+- `approve` requires an open `HUMAN_GATE` and a reason.
+- `block` requires an existing session and a reason.
+- Approval does not delete `HUMAN_GATE`; it records `GATE_APPROVED` for audit.
+- An explicit block records `GATE_BLOCKED` and keeps `ship` stopped.
+- The target project is not mutated by this command.
+
+Outputs:
+
+- `.harness/state/sessions/<id>/GATE_APPROVED` when approved
+- `.harness/state/sessions/<id>/GATE_BLOCKED` when blocked
+- `.harness/state/sessions/<id>/gate-summary.json`
+- `.harness/state/sessions/<id>/gate-events.jsonl`
+
+## ship
+
+`ship` is the public ship/no-ship readiness phase:
+
+```bash
+node scripts/cli.js ship "prepare ship readiness" --require-clean-gates --session work-smoke
+```
+
+Rules:
+
+- A prior `work` handoff in the same session is required.
+- A prior `verify`/`codex-review` handoff in the same session is required.
+- Existing `HUMAN_GATE` blocks ship unless `gate approve` recorded a later approval.
+- Blocking or critical Codex findings write or preserve `HUMAN_GATE`.
+- Financial and deploy-sensitive risk policy is rechecked before readiness.
+- `approve_with_fixes` creates a no-ship handoff rather than a ready marker.
+- The target project is not mutated by this command.
+
+Outputs:
+
+- `.harness/state/sessions/<id>/ship-summary.json`
+- `.harness/state/sessions/<id>/handoffs/07-ship.md` when not human-gated
+- `.harness/state/sessions/<id>/SHIP_READY` when Codex verification is fully approved
+- `.harness/state/sessions/<id>/NO_SHIP` when fixable findings remain
+
+## apply
+
+`apply` is the explicit project-mutation phase for live work diffs:
+
+```bash
+node scripts/cli.js apply --session work-smoke
+node scripts/cli.js apply --session work-smoke --allow-dirty
+```
+
+Rules:
+
+- A prior `work` handoff in the same session is required.
+- A prior `verify`/`codex-review` handoff in the same session is required.
+- `SHIP_READY` is required.
+- `NO_SHIP`, open `HUMAN_GATE`, or `GATE_BLOCKED` stops apply.
+- A captured diff from `work --live` is required.
+- The project must be a git worktree.
+- The project worktree must be clean, excluding `.harness/` session state, unless `--allow-dirty` is used.
+- `APPLIED_DIFF` makes apply idempotent unless `--force` is used.
+
+Outputs:
+
+- `.harness/state/sessions/<id>/APPLIED_DIFF`
+- `.harness/state/sessions/<id>/apply-summary.json`
+
+## run
+
+`run` is the public convenience wrapper for the decomposed pipeline:
+
+```bash
+node scripts/cli.js run "implement and verify this change" --session run-smoke
+node scripts/cli.js run "sensitive auth change" --session run-smoke --secure
+node scripts/cli.js run "live change" --session run-smoke --live --apply
+```
+
+Rules:
+
+- Runs `work -> verify -> ship`.
+- Does not apply by default.
+- `--secure` is forwarded to `verify`.
+- `--live` is forwarded to `work`, `verify`, and `ship`.
+- `--apply` runs `apply` only when `ship` produced `SHIP_READY`.
+- Open gates stop the run with exit code 3.
+- `NO_SHIP` skips apply and leaves a no-ship readiness handoff.
+
+Policy:
+
+- `run` is the short safe wrapper for new users.
+- `run` does not call `plan` in the `0.0.3` line.
+- `plan` is recommended before `work` for larger changes.
+- `work` still records `acceptance-criteria.json`, so `run` preserves success criteria evidence.
+- `apply` is always explicit; use `run --apply` only after live work can produce a captured diff.
+
+Outputs:
+
+- `.harness/state/sessions/<id>/run-summary.json`
+- all normal `work`, `verify`, `ship`, and optional `apply` outputs
+
+## review-cycle
+
+`review-cycle` is the explicit compatibility alias for the legacy full workflow:
+
+```bash
+node scripts/cli.js review-cycle "legacy full-cycle smoke" --no-ship
+```
+
+Rules:
+
+- It is equivalent to `review` in the `0.0.3` line.
+- It keeps the old `ideate -> plan -> implement -> self-review -> codex-review -> codex-challenge -> ship` behavior discoverable while new automation migrates to `run` or the decomposed commands.
+- It writes `review-summary.json` with `mode: legacy-full-review-cycle`.
+- It may use legacy live-review behavior, so new controlled project mutation should prefer `work --live -> verify -> ship -> apply`.
+
+## team-lite
+
+`team-lite` is a lightweight staged team pipeline inspired by OMC concepts:
+
+```bash
+node scripts/cli.js team-lite "split and verify this change" --session team-smoke
+```
+
+Stages:
+
+- `team-plan`
+- `team-prd`
+- `team-exec`
+- `team-verify`
+- `team-fix`
+
+Product rule:
+
+- Team stages produce handoffs and coordination state.
+- Multi-worker phases are read-only by default.
+- Project file mutation belongs to a single executor phase in the main work/review path.
+- Codex verification and human gate policy still apply after team output is used.
+- `team-lite.json` records `mode: advanced-team-lite-handoff`, `mutation: read-only-handoffs`, and `target_project_mutated: false`.
+
+Outputs:
+
+- `.harness/state/sessions/<id>/team-lite.json`
+- `.harness/state/sessions/<id>/monitor.json`
+- `.harness/state/sessions/<id>/heartbeat.jsonl`
+- `.harness/state/sessions/<id>/handoffs/`
+
+## ralph
+
+`ralph` is an explicit opt-in loop that repeats until PRD acceptance criteria pass, a human gate is hit, a cost cap stops it, or `--max-iter` is reached.
+
+```bash
+node scripts/cli.js ralph "finish the acceptance criteria" --max-iter 5
+node scripts/cli.js ralph "finish using the decomposed flow" --engine run --max-iter 5
+```
+
+Rules:
+
+- The default engine is `review`, preserving the legacy full review-cycle behavior.
+- `--engine run` repeats the decomposed `run` wrapper instead: `work -> verify -> ship`.
+- Ralph never applies by default; even with the run engine, project mutation still belongs to an explicit `apply` path outside the loop.
+- Each iteration writes a child session such as `<ralph-session>-i1`.
+- The parent session writes `ralph-summary.json` with the selected engine and iteration sessions.
+
+Use it only when repeated local iteration is desired. It is not part of the basic quickstart.
+
+## wait
+
+`wait` is the persistent wakeup daemon for explicit active sessions:
+
+```bash
+node scripts/cli.js wait status
+node scripts/cli.js wait start
+node scripts/cli.js wait stop
+```
+
+Rules:
+
+- The persistent-mode hook writes `wakeup.json` only when a session has an `active` file.
+- The daemon parses `active` and resumes only supported modes: `ralph`, `run`, and `review-cycle`.
+- Ralph active sessions may resume with either `engine: review` or `engine: run`.
+- `HUMAN_GATE` stops resume and writes `wait-summary.json` instead.
+- Failed resume attempts keep `wakeup.json` and add a short backoff.
+- Successful or blocked decisions append `wait-events.jsonl`.
+
+This is still an advanced opt-in surface. It does not bypass gates and does not apply diffs by itself.
+
+## instincts
+
+Instincts are project-local learning records. Promotion is intentionally manual.
+
+```bash
+node scripts/cli.js instincts list
+node scripts/cli.js instincts ready --blocked
+node scripts/cli.js instincts promote <id>
+```
+
+Promotion requires confidence `1.0`; automatic promotion without human confirmation is outside the 0.0.3 release scope.
+
+## Cost Tracking
+
+Cost records are appended to `.harness/costs.jsonl` when live runners report token usage.
+
+```bash
+node scripts/cli.js costs --since=7d
+node scripts/cli.js costs --since=7d --rows
+node scripts/cli.js costs --since=7d --json
+```
+
+These are estimates, not billing records.
+
+## Rust Runtime
+
+The Rust runtime under `runtime/` is a supervisor and IPC experiment for persistent operation.
+
+Verify it with:
+
+```bash
+npm run verify:runtime
+```
+
+The Node CLI remains the primary 0.0.3 user path.
+
+## Full Builder Surface
+
+The install/apply flow builds the configured harness outputs. You can also run builders directly:
+
+```bash
+node scripts/build-claude.js
+node scripts/build-codex.js
+node scripts/build-cursor.js
+node scripts/build-gemini.js
+node scripts/build-opencode.js
+```
+
+Use `HARNESS_PROJECT_ROOT=<target>` to project outputs into another repository while reading catalog inputs from the NEKOWORK checkout.

package/docs/AI-DEVELOPMENT-LIFECYCLE.md

@@ -0,0 +1,105 @@
+# AI Development Lifecycle
+
+NEKOWORK is a local-first AI development quality runtime. Its job is not to collect every useful agent feature; its job is to make AI development disciplined, high-quality, independently verified, and human-gated.
+
+## Position
+
+```text
+Good development habits
++ quality rules, hooks, and skills
++ product-aware scope control
++ read-only multi-agent thinking
++ Codex verification
++ Human Gate and explicit apply
+= NEKOWORK gated AI development runtime
+```
+
+The short slogan remains:
+
+```text
+Claude work -> Codex verification -> Human Gate
+```
+
+## Product Rules
+
+1. Claude should develop well.
+2. The workflow should produce high-quality work.
+3. Independent verification is mandatory before trust.
+4. Human Gate is a feature, not a failure.
+5. Multiple agents may think, but only one executor writes.
+6. Rich skills, hooks, and rules may improve quality, but cannot weaken safety.
+7. Apply is explicit and evidence-based.
+
+## Absorption Model
+
+External project ideas are absorbed as capabilities, not as a new architecture:
+
+| Source Pattern | Useful Strength | NEKOWORK Boundary |
+|---|---|---|
+| Development discipline | Brainstorm, plan, TDD, debugging, verification before completion | `quality`, `developer`, and `testing` profiles |
+| Rich agent environment | Skills, hooks, rules, MCP, memory, scanner-style checks | Profile/module based selective install |
+| Product questioning | Product, design, QA, release, and scope control questions | `ask`, `plan`, and `product` profile |
+| Team orchestration | Multiple perspectives and parallel review | `team` read-only handoffs |
+| NEKOWORK core | Codex verification, Human Gate, controlled apply | Non-bypassable runtime invariants |
+
+Capabilities can expand. The architecture cannot weaken the verification loop.
+
+## Workflow
+
+```text
+ask
+  -> plan
+  -> team
+  -> work
+  -> verify
+  -> gate
+  -> ship
+  -> apply
+```
+
+Quality enters early through `ask` and `plan`, not only at the final review step. Team mode collects multiple perspectives, but the write phase stays single-executor. Verification is independent, gate decisions are explicit, and apply requires evidence.
+
+## Quality Profile
+
+The `quality` profile is the disciplined-development bundle:
+
+- brainstorm before work
+- test-first planning
+- systematic debugging
+- evidence-based review
+- verification before completion
+- quality gate required
+- Codex verification required
+- Human Gate on critical findings
+- single-executor mutation policy
+
+Example:
+
+```bash
+node scripts/install-plan.js --profile quality
+node scripts/cli.js plan "implement feature X" --session feature-x
+node scripts/cli.js run "implement feature X" --profile quality --session feature-x
+node scripts/cli.js verify "verify feature X" --profile quality --strict-quality --session feature-x
+```
+
+`--strict-quality` is opt-in. In normal quality mode, missing evidence or acceptance coverage is recorded as warnings. In strict quality mode, those warnings become a fix-required verification verdict before ship readiness.
+
+## Evidence-Based Review
+
+Review findings should be specific enough to audit later:
+
+```json
+{
+  "claim": "The implementation may allow real order execution.",
+  "evidence": "OrderPanel imports brokerClient from src/api/broker.ts.",
+  "severity": "critical",
+  "category": "security",
+  "required_fix": "Replace brokerClient with a mock adapter before ship.",
+  "confidence": 0.91,
+  "gate_required": true
+}
+```
+
+The handoff schema allows these fields on issues so Codex review and challenge findings can carry evidence instead of vague objections.
+
+`verify-summary.json` can also record structured `acceptance_coverage` rows so acceptance criteria are checked against review evidence instead of only being written at plan time.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,205 @@
+# Architecture
+
+NEKOWORK is the product. HARNESS is the local runtime packaged by NEKOWORK as a local-first AI development harness. The project keeps one canonical catalog and projects it into multiple agent surfaces.
+
+## Core Idea
+
+```text
+agent.yaml
+  |
+  |-- agents/
+  |-- skills/
+  |-- hooks/
+  |-- rules/
+  |-- manifests/
+  |
+  +--> builders
+        |-- .claude/
+        |-- .codex/
+        |-- .cursor/
+        |-- .gemini/
+        `-- .opencode/
+```
+
+The canonical source is the repository catalog. Generated harness directories are outputs and can be rebuilt.
+
+## Product Invariants
+
+NEKOWORK is a verification runtime, not a general agent pack:
+
+```text
+Claude work -> Codex verification -> Human Gate
+```
+
+Core invariants:
+
+- Multi-worker phases are read-only by default.
+- Only one executor may mutate project files in a work cycle.
+- Codex review is the default independent verification path.
+- Secure or sensitive changes require Codex challenge or human gate.
+- Profiles may add capabilities, but they cannot weaken core safety gates.
+
+See [PRODUCT-PRINCIPLES.md](PRODUCT-PRINCIPLES.md), [CORE-INVARIANTS.md](CORE-INVARIANTS.md), [CLI-STAGES.md](CLI-STAGES.md), and [RISK-CLASSIFIER.md](RISK-CLASSIFIER.md) for the product contract, stage semantics, and risk policy.
+
+## Runtime Shape
+
+```text
+User command
+  |
+  +--> scripts/cli.js
+        |
+        |-- doctor
+        |-- install plan/apply
+        |-- ask / plan / team / work / verify / gate / ship / apply / run / review / review-cycle
+        |-- ralph
+        |-- team-lite
+        |-- sessions / costs / instincts
+        |
+        +--> orchestrators/
+              |
+              +--> agents/dispatch.js
+                    |
+                    +--> provider runners
+                          |-- mock
+                          |-- claude CLI
+                          |-- codex CLI
+                          `-- gemini CLI
+```
+
+Mock mode is the default. Live mode delegates authentication to local provider CLIs.
+
+## Public Flow
+
+The public alpha surface is intentionally small:
+
+```bash
+node scripts/cli.js doctor
+node scripts/cli.js install --plan --profile developer
+node scripts/cli.js install --apply --profile developer --project-root <target>
+node scripts/cli.js ask "clarify a risky or ambiguous request" --project-root <target>
+node scripts/cli.js plan "target project smoke" --project-root <target>
+node scripts/cli.js team "target project handoff review" --project-root <target>
+node scripts/cli.js work "single executor implementation" --session work-smoke --project-root <target>
+node scripts/cli.js verify "Codex verification" --session work-smoke --project-root <target>
+node scripts/cli.js gate status --session work-smoke --project-root <target>
+node scripts/cli.js ship "ship readiness" --session work-smoke --project-root <target>
+node scripts/cli.js apply --session work-smoke --project-root <target>
+node scripts/cli.js run "decomposed wrapper" --session run-smoke --project-root <target>
+node scripts/cli.js review "change request" --no-ship --project-root <target>
+node scripts/cli.js review-cycle "legacy full-cycle request" --no-ship --project-root <target>
+```
+
+Advanced features are documented separately:
+
+- `team-lite`
+- `ralph`
+- instincts
+- cost tracking
+- Rust runtime
+
+## Review Pipeline
+
+The `0.0.3` `review` command remains the Claude-led and Codex-reviewed legacy full cycle. `review-cycle` is an explicit compatibility alias for the same behavior:
+
+```text
+ideate
+  -> plan
+  -> implement
+  -> self-review
+  -> codex-review
+  -> codex-challenge when secure or sensitive
+  -> ship when not --no-ship
+```
+
+The long-term phase model is additive and keeps `review` compatibility during migration:
+
+```text
+ask -> plan -> team -> work -> verify -> gate -> ship -> apply
+```
+
+`ask` is a local question gate. `team` creates read-only handoffs from multiple worker perspectives. `work` lets one executor produce an implement handoff and, in live mode, an isolated workspace diff. `verify` runs Codex-only verification against that prior work handoff. `gate` records explicit human approve/block decisions for `HUMAN_GATE`. `ship` creates a ship/no-ship readiness handoff and refuses to bypass unresolved gates. `apply` is the only decomposed command in this chain that mutates the target project, and only by applying a verified `SHIP_READY` live-work diff. `team-lite` remains an advanced read-only staged handoff experiment. Future `review` can be retired or kept as a compatibility wrapper once callers have migrated to the decomposed commands.
+
+`work` does not run Codex review or ship. It also does not mutate the target project directly; live executor changes are captured as a session diff for later verification.
+
+`work` also ensures `acceptance-criteria.json` exists. It reuses planned PRD acceptance criteria when available or records a task-derived minimum so verification and ship readiness always have success criteria to inspect.
+
+`verify` does not implement or ship. It requires `--session <id>` so it can read the prior `work` handoff and optional diff. Critical or blocking Codex findings write `HUMAN_GATE`.
+
+`gate` does not inspect or edit project files. It writes audit markers: `GATE_APPROVED`, `GATE_BLOCKED`, `gate-summary.json`, and `gate-events.jsonl`.
+
+`ship` does not implement, verify, publish, deploy, or mutate the target project. It requires both prior `work` and Codex verification handoffs. It writes `SHIP_READY` only for fully approved verification or explicit human gate approval, writes `NO_SHIP` for fixable findings, and stops with a human gate when `HUMAN_GATE` is unresolved or explicitly blocked.
+
+`apply` requires `SHIP_READY`, no newer `NO_SHIP`, no unresolved gate, and a captured diff from `work --live`. It applies that diff with `git apply --3way`, records `APPLIED_DIFF`, and leaves commit/push/release actions to the human.
+
+`run` is the compatibility-friendly wrapper around the decomposed path. It runs `work -> verify -> ship` and only runs `apply` when `--apply` is explicitly requested and `SHIP_READY` exists. New automation should prefer `run` or the explicit decomposed commands; old automation can continue to use `review` or `review-cycle`.
+
+`ralph` is an advanced repeated-iteration loop. Its default engine remains legacy `review` for compatibility, but `ralph --engine run` repeats the decomposed wrapper and records child run sessions. Ralph does not apply diffs; verified mutation still flows through `apply`.
+
+`wait` is an advanced persistent wakeup daemon. It watches session `wakeup.json` files, parses the session `active` contract, and resumes only supported modes (`ralph`, `run`, `review-cycle`). It writes `wait-summary.json` / `wait-events.jsonl`, backs off failed resumes, and refuses to resume sessions with `HUMAN_GATE`.
+
+Handoffs use five required fields:
+
+- `Decided`
+- `Rejected`
+- `Risks`
+- `Files`
+- `Remaining`
+
+This keeps Claude and Codex contexts separated and makes review artifacts compact enough to inspect.
+
+## Project Root Split
+
+NEKOWORK supports running as a tool inside another repository:
+
+```text
+target-project/
+  .harness-tool/   # NEKOWORK tool checkout or submodule
+  .harness/        # target project state
+```
+
+The tool root supplies catalog inputs. The target project root receives generated outputs, session state, and git-aware work.
+
+## Authentication Model
+
+Provider auth is delegated by default:
+
+| Provider | Default auth |
+|---|---|
+| Claude | `claude` local CLI session |
+| Codex | `codex` local CLI session |
+| Gemini | `gemini` or Google local CLI session |
+
+Long-lived API key environment variables are warned about or blocked before delegated provider calls unless the user explicitly opts into the metered path.
+
+## Safety Model
+
+Key guardrails:
+
+- Provider CLI path trust checks reject workspace-local shims by default.
+- Git mutation guards detect unexpected writes from read-only provider phases.
+- Multi-worker phases must stay read-only unless a single executor phase explicitly owns mutation.
+- `security-hardening` checks workflow permissions, action refs, dependency specs, MCP pins, OIDC policy, and package lock presence.
+- `doctor` checks local readiness and generated-output freshness.
+- Human gates remain the final stop for critical or repeated-risk changes.
+
+## Generated Outputs
+
+Builders project the catalog into tool-specific files:
+
+| Target | Output |
+|---|---|
+| Claude Code | `.claude/` |
+| Codex CLI | `.codex/config.toml` |
+| Cursor | `.cursor/hooks.json` |
+| Gemini CLI | `.gemini/GEMINI.md` |
+| OpenCode | `.opencode/config.json` |
+
+`scripts/repair.js` checks install-state hashes and rebuilds stale outputs.
+
+## Release State
+
+The current release line is `0.1.0-alpha.0`:
+
+- Repository and GitHub tarball release are available.
+- Public npm metadata is prepared, but publish execution is blocked until npm owner auth is available.
+- Clone, submodule, and local checkout integration remain the supported install paths until the package is published.