@ps-neko/nekowork 0.1.0-alpha.0

package/docs/PORTING.md

@@ -0,0 +1,154 @@
+# Porting NEKOWORK Into Another Project
+
+NEKOWORK `0.1.0-alpha.0` is prepared as a public alpha candidate. It is not published to npm yet, so use a submodule or local checkout until npm owner auth is available and the alpha is published.
+
+## Local Demo First
+
+Before touching a real target project, run the disposable external-project demo from the NEKOWORK checkout:
+
+```bash
+npm run demo:external
+```
+
+The demo creates a tiny target project, runs the porting preflight, applies generated harness outputs, runs `doctor --quick`, and creates a planning session. Use `npm run demo:external -- --cleanup` when you want the generated target removed after success.
+
+## Recommended Shape
+
+```text
+target-project/
+  .harness-tool/             # NEKOWORK checkout or submodule
+  .harness/                  # generated install/session state
+  .claude/                   # generated Claude Code surface
+  .codex/config.toml         # generated Codex surface
+  .cursor/hooks.json         # generated Cursor surface
+  .gemini/GEMINI.md          # generated Gemini surface
+  .opencode/config.json      # generated OpenCode surface
+```
+
+The tool root stays in `.harness-tool/`. Generated harness files, session state, and git-aware execution target the project root.
+
+## Submodule Install
+
+```bash
+cd <target-project>
+git submodule add https://github.com/Ps-Neko/NEKOWORK.git .harness-tool
+node .harness-tool/scripts/portability/simulate-port.js . --profile developer --verbose
+node .harness-tool/scripts/install-apply.js --profile developer --project-root .
+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
+```
+
+## Local Checkout Install
+
+Use this when developing NEKOWORK and testing it against another project:
+
+```bash
+cd C:/Users/Mun/harness
+node scripts/portability/simulate-port.js <target-project> --profile developer --verbose
+node scripts/install-apply.js --profile developer --project-root <target-project>
+node scripts/cli.js doctor --project-root <target-project> --quick
+node scripts/cli.js plan "target project smoke" --project-root <target-project> --session target-smoke
+```
+
+## What To Check
+
+After `install-apply`, confirm these exist in the target project:
+
+- `.harness/install-state.json`
+- `.harness/state/sessions/`
+- `.claude/`
+- `.codex/config.toml`
+- `.cursor/hooks.json`
+- `.gemini/GEMINI.md`
+- `.opencode/config.json`
+
+The generated files are derived from `agent.yaml`, `agents/`, `skills/`, `hooks/`, `rules/`, and `manifests/` in the NEKOWORK tool root.
+
+## Live Provider Auth
+
+Mock mode is the default and does not need provider CLIs. Live mode delegates to local CLI sessions:
+
+```bash
+claude auth status
+codex login status
+gemini
+```
+
+Then run:
+
+```bash
+node .harness-tool/scripts/cli.js doctor --project-root . --quick --gemini-smoke
+node .harness-tool/scripts/cli.js review "live smoke" --project-root . --live --no-ship
+```
+
+Unset long-lived provider API keys unless you intentionally opt into metered API-key paths:
+
+```bash
+unset ANTHROPIC_API_KEY
+unset OPENAI_API_KEY
+unset GEMINI_API_KEY
+unset GOOGLE_API_KEY
+```
+
+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
+```
+
+## Profiles
+
+- `core`: minimum rules, agents, hooks, and platform configs
+- `developer`: default daily workflow profile
+- `security`: security-focused review/challenge defaults
+- `research`: research agent and Gemini-oriented surface
+- `full`: all declared modules
+
+Preview a profile before applying it:
+
+```bash
+node .harness-tool/scripts/install-plan.js --profile developer --project-root .
+node .harness-tool/scripts/install-plan.js --list
+```
+
+## Refresh After Catalog Changes
+
+When NEKOWORK changes:
+
+```bash
+git -C .harness-tool pull --ff-only
+node .harness-tool/scripts/install-apply.js --profile developer --project-root .
+node .harness-tool/scripts/repair.js --check
+node .harness-tool/scripts/sync-claude-md.js --check
+node .harness-tool/scripts/build-codemaps.js --check
+```
+
+## Troubleshooting
+
+`simulate-port` reports high conflict:
+
+- Inspect existing `.harness`, `.harness-tool`, `.mcp.json`, `CLAUDE.md`, and `AGENTS.md`.
+- Prefer a dry run first and keep project-owned sections outside generated marker blocks.
+
+`doctor` reports API key warnings:
+
+- Unset provider API key variables.
+- Use `HARNESS_AUTH_ALLOW_ENV_OVERRIDE=1` only for intentional metered calls.
+
+`doctor --gemini-smoke` fails:
+
+- Run interactive `gemini` once and choose Google login.
+- Or configure Vertex/ADC auth for the local Gemini CLI.
+- Re-run `npm run verify:gemini` from the NEKOWORK checkout.
+
+Generated outputs are stale:
+
+- Run `node .harness-tool/scripts/install-apply.js --profile developer --project-root .`.
+- Re-run `node .harness-tool/scripts/cli.js doctor --project-root .`.
+
+## Version Pinning
+
+For PoC work, pin the NEKOWORK submodule to a tag such as `v0.0.3`. Avoid `latest`-style moving references in production workflows.

package/docs/PRODUCT-PRINCIPLES.md

@@ -0,0 +1,303 @@
+# Product Principles
+
+NEKOWORK is not a large agent pack. It is a local-first multi-AI development runtime where Claude produces work, Codex verifies it from a separate context, and human gates stop risky changes.
+
+## Position
+
+```text
+NEKOWORK = Claude work -> Codex verification -> Human Gate
+```
+
+Agent catalogs, skill packs, hooks, profiles, and team execution are useful only when they strengthen that verification loop.
+
+NEKOWORK also acts as a local-first AI development quality runtime:
+
+```text
+good development discipline
++ product-aware scope control
++ read-only multi-agent thinking
++ evidence-based Codex verification
++ Human Gate
++ explicit apply
+= gated AI development lifecycle
+```
+
+See [AI-DEVELOPMENT-LIFECYCLE.md](AI-DEVELOPMENT-LIFECYCLE.md) for the lifecycle view.
+
+## Core Invariants
+
+These rules are part of the product contract:
+
+1. Multi-worker phases are read-only by default.
+2. Only one executor may mutate project files in a work cycle.
+3. Codex review is the default independent verification path.
+4. Secure or sensitive changes require Codex challenge or human gate.
+5. Human gate cannot be bypassed by skill, hook, profile, or module expansion.
+6. Profiles may add capabilities, but they cannot weaken core safety gates.
+7. Live provider calls must use delegated local CLI auth unless the user explicitly opts into another path.
+8. Unexpected git mutation during read-only phases is a failure condition.
+
+See [CORE-INVARIANTS.md](CORE-INVARIANTS.md) for the standalone invariant contract.
+
+## CLI Phase Semantics
+
+The decomposed workflow is:
+
+```text
+ask -> plan -> team -> work -> verify -> gate -> ship -> apply
+```
+
+The phases mean:
+
+| Phase | Meaning | Mutation |
+|---|---|---|
+| `ask` | Clarify goal, scope, risk, and success criteria. | No project mutation |
+| `plan` | Produce an implementation plan and acceptance criteria. | No project mutation |
+| `team` | Produce read-only handoffs from multiple worker perspectives. | No project mutation |
+| `work` / `run` | Let a single executor implement the approved plan. | Single executor only |
+| `verify` | Run Codex review, optional Codex challenge, and gate logic against prior work. | No project mutation |
+| `gate` | Record explicit human approve/block decisions for `HUMAN_GATE`. | No project mutation |
+| `review` | Compatibility full cycle for `ideate -> plan -> implement -> self-review -> codex-review -> codex-challenge -> ship`. | Legacy full loop |
+| `review-cycle` | Explicit alias for the legacy `review` behavior during migration. | Legacy full loop |
+| `ship` | Prepare a ship/no-ship readiness handoff after gates pass. | No project mutation |
+| `apply` | Apply a verified `SHIP_READY` live-work diff to the target project. | Controlled project mutation |
+| `run` | Convenience wrapper for `work -> verify -> ship`, optional `apply`. | Wrapper; mutation only with `--apply` |
+
+For the `0.0.3` line, `review` remains the legacy full cycle, and `review-cycle` is an explicit compatibility alias:
+
+```text
+ideate -> plan -> implement -> self-review -> codex-review -> codex-challenge -> ship
+```
+
+Do not silently change that meaning. New wrappers and aliases should make the transition additive:
+
+```text
+short term:  ask + existing review cycle
+mid term:    work + verify + ship split mutation from verification and readiness
+long term:   ask -> plan -> team -> work -> verify -> gate -> ship -> apply
+```
+
+See [CLI-STAGES.md](CLI-STAGES.md) for the standalone stage contract and compatibility window.
+
+## Profile Boundaries
+
+Profiles group capabilities. They do not change safety invariants.
+
+Current and target profile meanings:
+
+| Profile | Boundary |
+|---|---|
+| `core` | Minimal rules, agents, hooks, platform configs, and safety gates. |
+| `developer` | Daily development flow with quality workflow, Codex loop, and ops readiness. |
+| `security` | Secure review defaults, network denial, critical human gates, and hardened checks. |
+| `product` | Question gate, scope review, acceptance criteria, and product/design planning surfaces. |
+| `quality` | Brainstorm, test-first planning, systematic debugging, evidence-based review, and verification before completion. |
+| `frontend` | UI mockup, component review, accessibility, and front-end workflow surfaces. |
+| `testing` | Test planning, regression checks, and coverage-oriented review surfaces. |
+| `research` | Research-oriented handoffs and optional external knowledge surfaces. |
+| `full` | All stable modules, still bounded by core safety invariants. |
+
+## Team Mode
+
+Team mode should start as read-only handoff generation:
+
+```text
+planner handoff
+research handoff
+design/product handoff
+security handoff
+test handoff
+codex review handoff
+```
+
+The public command is:
+
+```bash
+harness team "<task>" --workers planner,research,product,security,test
+harness team "<task>" --workers planner,research,product,security,test --no-write
+```
+
+The initial rule is simple:
+
+```text
+many workers may think
+one executor may write
+Codex must verify
+Human Gate may stop
+```
+
+Parallel write access is a later capability and requires stronger conflict tracking, ownership, audit logs, and rollback behavior.
+
+Advanced `team-lite` remains a handoff and coordination surface. It records read-only intent and does not replace the single-executor `work`/`run` phase.
+
+## Work Mode
+
+The public command is:
+
+```bash
+harness work "<task>" --session <id>
+harness work "<task>" --single-executor --session <id>
+harness work "<task>" --profile quality --session <id>
+```
+
+`work` is the single-executor mutation phase. In the `0.0.3` line it is deliberately conservative:
+
+- only the `executor` agent runs
+- mock mode writes an implement handoff only
+- live mode writes in an isolated git worktree
+- live diffs are persisted under the session
+- the target project is not mutated directly
+- Codex review and ship are not run
+
+The next step after `work` is verification before any apply or ship path.
+
+`work` writes `acceptance-criteria.json` for every session. It reuses `prd.json` acceptance criteria when present and otherwise records a task-derived minimum so verification and ship readiness always have a success artifact to reference.
+
+## Verify Mode
+
+The public command is:
+
+```bash
+harness verify "<task>" --session <id>
+harness verify "<task>" --profile quality --strict-quality --session <id>
+```
+
+`verify` is the Codex-only verification phase:
+
+- requires a prior `work` handoff in the same session
+- reads prior handoffs and any captured diff
+- runs `codex-review`
+- runs `codex-challenge` for `--secure` or sensitive work
+- expects findings to include evidence whenever possible: claim, evidence, required fix, confidence, and gate requirement
+- records quality/security evidence warnings when profile policy asks for them
+- records structured `acceptance_coverage` for the `quality` profile
+- can escalate quality warnings into a fix-required verdict with `--strict-quality`
+- writes `HUMAN_GATE` for critical or blocking findings
+- does not implement
+- does not ship
+
+## Gate Mode
+
+The public commands are:
+
+```bash
+harness gate status --session <id>
+harness gate approve --session <id> --reason "<why>"
+harness gate block --session <id> --reason "<why>"
+```
+
+`gate` is the explicit human decision phase:
+
+- `status` reads the session gate markers
+- `approve` requires an open `HUMAN_GATE`
+- `block` creates an explicit no-ship block for the session
+- approval writes `GATE_APPROVED` but keeps `HUMAN_GATE` for audit
+- block writes `GATE_BLOCKED` and keeps `ship` stopped
+- no project files are mutated
+
+## Ship Mode
+
+The public command is:
+
+```bash
+harness ship "<task>" --session <id>
+harness ship "<task>" --require-clean-gates --session <id>
+```
+
+`ship` is the readiness phase:
+
+- requires a prior `work` handoff in the same session
+- requires prior Codex verification in the same session
+- refuses to bypass an unresolved `HUMAN_GATE`
+- respects explicit `gate approve` and `gate block` markers
+- writes `SHIP_READY` only after a fully approved verification verdict
+- writes `NO_SHIP` when fixable Codex findings remain
+- does not publish, deploy, create a PR, or mutate project files
+
+## Apply Mode
+
+The public command is:
+
+```bash
+harness apply --session <id>
+```
+
+`apply` is the controlled mutation phase:
+
+- requires a prior `work` handoff
+- requires prior Codex verification
+- requires `SHIP_READY`
+- refuses newer `NO_SHIP`, open `HUMAN_GATE`, or `GATE_BLOCKED`
+- requires a captured diff from `work --live`
+- applies the diff with git
+- records `APPLIED_DIFF`
+- leaves commit, push, PR, release, publish, and deploy to the human
+
+`apply` is never implicit in the default beginner path. It only runs when the user explicitly asks for it through `apply` or `run --apply`.
+
+## Run Mode
+
+The public command is:
+
+```bash
+harness run "<task>" --session <id>
+```
+
+`run` is a convenience wrapper:
+
+- runs `work -> verify -> ship`
+- forwards `--secure` to `verify`
+- forwards `--live` to each phase
+- does not apply by default
+- applies only with explicit `--apply`
+- stops on human gates
+- writes `run-summary.json`
+
+`run` is the short safe wrapper for new users. It is intentionally narrower than the full long-term workflow: it does not run `plan` yet, but it records acceptance criteria through `work` and preserves the same Codex verification and Human Gate policy. `plan` remains recommended before `work` for larger changes and may become a required accepted artifact in a later release line.
+
+## Ralph Mode
+
+The public command is:
+
+```bash
+harness ralph "<task>" --engine review|run --max-iter <n>
+```
+
+`ralph` is advanced and explicit:
+
+- default `--engine review` preserves the legacy full-cycle behavior
+- `--engine run` repeats `work -> verify -> ship`
+- it never applies by default
+- every iteration is a child session
+- cost cap, human gate, and max-iteration limits stop the loop
+
+## Wait Mode
+
+The public commands are:
+
+```bash
+harness wait status
+harness wait start
+harness wait stop
+```
+
+`wait` is an advanced persistent resume surface:
+
+- it resumes only sessions that explicitly write an `active` contract
+- supported active modes are `ralph`, `run`, and `review-cycle`
+- it refuses to resume sessions with `HUMAN_GATE`
+- it records `wait-summary.json` and `wait-events.jsonl`
+- it may wake work back up, but it must not weaken Codex verification, Human Gate, or explicit apply rules
+
+## Sensitive Work
+
+Treat these categories as gate-sensitive:
+
+- auth, session, permission, OAuth, JWT, password, token, secret, crypto, TLS, CSRF, CORS, XSS, webhook
+- payment, billing, broker/order execution, trading, financial automation
+- production deploy, CI/CD workflow changes, cloud credentials, infrastructure changes
+- database migrations, destructive data changes, personal data, rollback-sensitive work
+
+Sensitive work may be planned, mocked, or reviewed, but it cannot bypass Codex verification and human gate policy.
+
+See [RISK-CLASSIFIER.md](RISK-CLASSIFIER.md) for the shared classifier contract.

package/docs/PUBLISH-ALPHA.md

@@ -0,0 +1,106 @@
+# Public Alpha Publish Plan
+
+NEKOWORK `0.0.3` stays a private/local alpha. The first npm release is prepared as the public alpha candidate `0.1.0-alpha.0`.
+
+Do not publish from the `0.0.3` line.
+
+The repository metadata has been advanced to `0.1.0-alpha.0` with `private: false`. Actual publish is still blocked until `npm whoami` succeeds for an owner account.
+
+## Current Registry State
+
+Checked on 2026-05-07:
+
+```text
+npm view @ps-neko/nekowork version --json
+-> E404 Not Found
+```
+
+The package name is not publicly visible on npm from this environment. The machine is also not logged in:
+
+```text
+npm whoami
+-> ENEEDAUTH
+```
+
+The publish package shape has been checked:
+
+```text
+npm publish --dry-run --access public --tag alpha
+-> pass
+```
+
+Actual publish is still blocked by auth:
+
+```text
+npm publish --access public --tag alpha
+-> ENEEDAUTH
+```
+
+## Release Shape
+
+Prepared first public package:
+
+```text
+name: @ps-neko/nekowork
+version: 0.1.0-alpha.0
+dist-tag: alpha
+bin: harness
+```
+
+The alpha tag matters. It prevents accidental default installation before the owner decides the public package should become the stable install path.
+
+## Required Owner Decision
+
+Before publishing, explicitly confirm:
+
+- npm scope ownership for `@ps-neko`
+- npm 2FA readiness
+- package name `@ps-neko/nekowork`
+- binary name `harness`
+- public alpha version `0.1.0-alpha.0`
+- `private` removed or set to `false`
+- publish tag is `alpha`, not `latest`
+
+## Required Gates
+
+Run:
+
+```bash
+node scripts/cli.js doctor
+node scripts/cli.js doctor --quick --gemini-smoke
+npm run lint
+npm test
+npm run demo:quick -- --cleanup
+npm run demo:external -- --cleanup
+npm audit --audit-level=moderate
+node scripts/repair.js --check
+node scripts/sync-claude-md.js --check
+node scripts/build-codemaps.js --check
+npm pack --dry-run --json
+npm publish --dry-run --access public --tag alpha
+```
+
+Inspect the `npm pack --dry-run --json` file list before publishing.
+
+## Publish Commands
+
+Only after npm owner auth is active:
+
+```bash
+npm publish --access public --tag alpha
+```
+
+Then smoke test from a fresh temporary directory:
+
+```bash
+npx @ps-neko/nekowork@alpha doctor --quick
+```
+
+If the `harness` bin cannot run correctly through `npx`, do not promote the package.
+
+## Post-Publish Work
+
+- Add README npm install path.
+- Add release notes.
+- Tag the commit.
+- Keep source/submodule install docs for users who want repository-pinned workflows.