@ps-neko/nekowork 0.2.0-alpha.1 → 0.2.0-alpha.3

package/README.md

@@ -10,18 +10,18 @@ pushes, or deploys on its own.
 
 ## Status
 
-**Phase A skeleton** (2026-05-27). The 4 public verbs work via delegation to
-`@ps-neko/nekowork-cli` in the monorepo. To publish this package
-independently, the verify-pr code path needs to be moved into this package —
-see [HANDOFF-PACKAGE-SPLIT.md](./HANDOFF-PACKAGE-SPLIT.md).
-
-For the full alpha-stage product today, install:
+**Published alpha** (`@ps-neko/nekowork`, alpha dist-tag). This package is the
+published slim verification gate. Install with:
 
 ```bash
-npm i -g @ps-neko/nekowork-cli@alpha
+npm i -g @ps-neko/nekowork
 ```
 
-## Quickstart (once Phase A is complete)
+The fuller legacy and power-user surface lives in the internal
+`@ps-neko/nekowork-harness` package (not separately published). See
+[HANDOFF-PACKAGE-SPLIT.md](./HANDOFF-PACKAGE-SPLIT.md) for the split history.
+
+## Quickstart
 
 ```bash
 # right after your AI tool changes some files:
@@ -39,7 +39,7 @@ whether the change is safe to merge.
 | `check` | Probe environment readiness (Node version, git repo, etc.) |
 | `verify-pr` | Scan working-tree diff. Produce REPORT.md + .nekowork/decision.json |
 | `report` | Render an existing decision.json to a human-readable REPORT.md |
-| `apply` | Apply a stored .diff iff decision.json says `apply_allowed: true` |
+| `apply` | Session-based compatibility apply. Requires a completed work cycle (SHIP_READY marker + cleared Human Gate). NOT driven by verify-pr's decision.json. See [ADVANCED.md](../nekowork-cli/docs/ADVANCED.md). |
 
 Anything else (`ask`, `plan`, `team`, `work`, `ship`, `build`, `auto`,
 `pr-prep`, `review`, ...) belongs to `@ps-neko/nekowork-harness` (legacy and
@@ -50,9 +50,16 @@ power-user surface). The slim package rejects those verbs with a redirect.
 1. Your AI tool writes the code. `nekowork` never writes it for you.
 2. `verify-pr` runs a fixed set of risk rules over the diff — same diff, same
    verdict, every time. **No LLM gets to "vote" the result.**
-3. It saves the evidence into a `REPORT.md` you can read.
+3. It saves the evidence into a `REPORT.md` you can read, and writes
+   `.nekowork/decision.json` with informational verdict fields (`merge_allowed`,
+   `apply_allowed`). **verify-pr itself does not apply changes.**
 4. You decide at the Human Gate — approve, or don't.
-5. Only then can `apply` apply the diff. No auto-commit. No auto-push.
+
+> verify-pr itself does not apply changes. Session-based apply is part of the
+> compatibility workflow and requires SHIP_READY and a cleared Human Gate.
+
+No auto-commit. No auto-push. `apply` is a separate, session-based compatibility
+step — it is not triggered by `decision.json`.
 
 ## Docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ps-neko/nekowork",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.3",
   "description": "Local verification gate for AI-written code diffs. Deterministic rules decide the verdict, never the LLM. No auto-commit, push, or deploy — you decide at the Human Gate.",
   "keywords": [
     "ai-code-review",

package/scripts/cli.js

@@ -4,7 +4,7 @@
 // All 4 public verbs run LOCALLY in this package. No delegation to any other package.
 //
 // Public verbs: check, verify-pr, report, apply
-// Anything else → error with hint to install @ps-neko/nekowork-harness.
+// Anything else → error: harness verbs live in the internal (unpublished) @ps-neko/nekowork-harness; use a source checkout.
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -25,14 +25,7 @@ const META_FLAGS = new Set(['--version', '-v', '--help', '-h']);
 const args = process.argv.slice(2);
 const verb = args[0];
 
-if (args.length === 0 || META_FLAGS.has(verb)) {
-  if (verb === '--version' || verb === '-v') {
-    const pkgPath = path.resolve(__dirname, '..', 'package.json');
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-    console.log(pkg.version);
-    process.exit(0);
-  }
-  console.log(`@ps-neko/nekowork — local verification gate for AI-written code
+const USAGE = `@ps-neko/nekowork — local verification gate for AI-written code
 
 Usage:
   nekowork check                  Probe environment readiness
@@ -52,13 +45,23 @@ verify-pr options:
   --no-write                don't write REPORT.md / decision.json
 
 Need legacy / harness commands (ask / plan / team / work / ship / build / auto / ...)?
-  npm i -g @ps-neko/nekowork-harness
-  nekowork-harness <verb>
+  They live in the internal @ps-neko/nekowork-harness runtime, which is NOT
+  published to npm. Run them from a source checkout:
+  https://github.com/Ps-Neko/NEKOWORK
 
 Docs:
   https://github.com/Ps-Neko/NEKOWORK/blob/main/packages/nekowork-cli/docs/QUICKSTART.md
   https://github.com/Ps-Neko/NEKOWORK/blob/main/packages/nekowork-cli/docs/SCOPE-1.0.md
-  https://github.com/Ps-Neko/NEKOWORK/blob/main/packages/nekowork-cli/docs/BENCHMARK.md`);
+  https://github.com/Ps-Neko/NEKOWORK/blob/main/packages/nekowork-cli/docs/BENCHMARK.md`;
+
+if (args.length === 0 || META_FLAGS.has(verb)) {
+  if (verb === '--version' || verb === '-v') {
+    const pkgPath = path.resolve(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    console.log(pkg.version);
+    process.exit(0);
+  }
+  console.log(USAGE);
   process.exit(0);
 }
 
@@ -70,13 +73,18 @@ if (VERBS_INTERNAL.has(verb)) {
 The slim @ps-neko/nekowork supports:
   check, verify-pr, report, apply
 
-For \`${verb}\` (a harness command), install @ps-neko/nekowork-harness:
-  npm i -g @ps-neko/nekowork-harness
-  nekowork-harness ${verb} ${args.slice(1).join(' ')}`);
+\`${verb}\` is a harness command. The harness runtime (@ps-neko/nekowork-harness)
+is internal and NOT published to npm — run harness verbs from a source checkout:
+  https://github.com/Ps-Neko/NEKOWORK`);
   process.exit(1);
 }
 
 async function runInternal(verb, rest) {
+  if (rest.includes('--help') || rest.includes('-h')) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+
   if (verb === 'check') {
     const { spawnSync } = await import('node:child_process');
     const r = spawnSync(process.execPath, [path.resolve(__dirname, 'check.js'), ...rest], { stdio: 'inherit' });

package/scripts/lib/diff-parser.js

@@ -208,7 +208,7 @@ export function getGitDiff(opts = {}) {
     if (ls.status !== 0) {
       throw new Error(`git ls-files exited ${ls.status}: ${ls.stderr || ''}`);
     }
-    const tracked = (ls.stdout || '').split('\n').map(s => s.trim()).filter(Boolean);
+    const tracked = (ls.stdout || '').split('\n').map(s => s.trim()).filter(Boolean).filter(p => !isSelfOutput(p));
     let stdout = synthesizeFilesAsDiff(cwd, tracked);
     if (includeUntracked) stdout += synthesizeUntrackedDiff(cwd);
     return parseDiff(appendIncluded(stdout));
@@ -248,10 +248,20 @@ export function getGitDiff(opts = {}) {
   return parseDiff(appendIncluded(stdout));
 }
 
+/**
+ * verify-pr writes its own output to `REPORT.md` and `.nekowork/**`. Those are
+ * the tool's product, not "changes to verify" — scanning them would re-flag the
+ * secret/risk text stored in its own evidence on the next run (self-
+ * contamination). Exclude them from every synthesized diff.
+ */
+function isSelfOutput(relPath) {
+  return relPath === 'REPORT.md' || relPath.startsWith('.nekowork/');
+}
+
 function synthesizeUntrackedDiff(cwd) {
   const ls = spawnSync('git', ['ls-files', '--others', '--exclude-standard'], { cwd, encoding: 'utf8', windowsHide: true });
   if (ls.status !== 0 || !ls.stdout) return '';
-  const files = ls.stdout.split('\n').map(s => s.trim()).filter(Boolean);
+  const files = ls.stdout.split('\n').map(s => s.trim()).filter(Boolean).filter(p => !isSelfOutput(p));
   return synthesizeFilesAsDiff(cwd, files);
 }
 

package/scripts/orchestrators/verify-pr.js

@@ -441,7 +441,7 @@ export function parseVerifyPrArgs(rest = []) {
     else if (a === '--no-write') opts.write = false;
     else if (a === '--comment-file') { opts.commentFile = nextArg(rest, ++i, '--comment-file'); }
     else if (a === '--ci-exit-soft') opts.ciExitSoft = true;
-    else if (a === '--run-checks') process.stderr.write('warning: --run-checks is not supported in the slim @ps-neko/nekowork gate; install @ps-neko/nekowork-harness for this feature\n');
+    else if (a === '--run-checks') process.stderr.write('warning: --run-checks is not supported in the slim @ps-neko/nekowork gate; use the @ps-neko/nekowork-harness runtime from a source checkout for this feature\n');
     else if (a === '--include') { (opts.includePaths = opts.includePaths || []).push(nextArg(rest, ++i, '--include')); }
   }
   return opts;