@webpieces/rules-config 0.4.731 → 0.4.733

package/src/stale-bin-sweep.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.staleBinSweeper = exports.StaleBinSweeper = exports.StaleBinRemoval = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const to_error_1 = require("./to-error");
+// ---------------------------------------------------------------------------
+// SWEEP DANGLING `node_modules/.bin/wp-*` SYMLINKS.
+//
+// THE DEFECT. pnpm's linker ADDS a link for every entry in the current manifest's `bin` map, but it never
+// sweeps `.bin` for orphans left behind by a PREVIOUS version of the SAME package. `@webpieces/pr-gate`
+// and `@webpieces/ai-hook-rules` are upgraded, never removed, so nothing ever triggers a delete: every
+// bin either package has EVER shipped stays linked forever, pointing at a script that is no longer on
+// disk. A scan of nine clones on ONE machine found 18 distinct dangling `wp-*` names.
+//
+// THE DEFECT IS ONGOING, AND A ROUTINE RENAME PRODUCES IT. Measured on this repo's own upgrade to
+// 0.4.728, DURING the session that wrote this file: PR #743 hard-renamed one `wp-*` command with no alias,
+// so the new manifest declares `wp-sync-main` and no longer declares its predecessor. One `pnpm install`
+// later, `.bin` held the NEW link created that minute AND the predecessor's link still sitting there from
+// the previous install, dangling — reproduced independently in two separate trees of this repo. So this is
+// not a historical mess left by a deleted feature that a one-time migration could mop up: it is
+// regenerated by the most ordinary change a package can make, on every clone, every time. That is the
+// argument for the call site below — the sweep has to ride a path that runs ROUTINELY, because the defect
+// is created routinely.
+//
+// The predecessor's NAME is deliberately not written here. `no-old-sync-main-name` forbids the dead
+// spelling in tracked source and blocked an earlier draft of this very comment, which is the rule working:
+// a retired command named in source is exactly how a dead name outlives its tooling — the thing this
+// module exists to clean up, one level out. PR #743 and the issue this shipped under carry the literal
+// name; nothing in the code needs it, because the predicate below is structural.
+//
+// WHY IT MATTERS MORE THAN TIDINESS. `ls node_modules/.bin` lists them, so a dangling entry ADVERTISES a
+// capability that does not exist — a human and an AI were both misled by that listing before checking the
+// link target — and the failure it eventually produces is self-referential and useless:
+// `Command "wp-authorize" not found / Did you mean "pnpm wp-authorize"?`. This is `upgrade-shim.ts`'s own
+// governing principle one level out: an entry pointing at a missing file is WORSE than absence.
+//
+// WHY A PREFIX AND NOT A NAME LIST. A hardcoded list of retired bin names would go stale in exactly the
+// way the symlinks did — the list assembled from the two names that prompted this would have caught 2 of
+// the 18, and it would NOT have caught the rename above, which had not happened yet when the list would
+// have been written. That is the general case: the next orphan is always created by a release later than
+// any list. A name list is also unwriteable here on purpose — see the note above about naming dead
+// commands in source. The predicate is structural instead — a `wp-` prefixed entry that is a SYMLINK whose target
+// does not exist — so it needs no maintenance and cannot miss a name nobody has thought of. The prefix is
+// the whole safety story: another package's bins are never touched.
+//
+// WHY NOT A postinstall HOOK. `setupDebugging.md` records the postinstall approach as ABANDONED in this
+// repo. The call site is the `wp-*` startup pass that regenerates `.webpieces/instruct-ai/*` — see
+// TemplateWriter — and that placement is the load-bearing half of the fix. This is not a tidy-up for one
+// repo: every developer's machine has this graveyard, and a cure that only cleans the tree somebody happens
+// to run it in is worthless. Riding the pass EVERY `wp-*` command takes is what makes the RELEASED sweep
+// reach every clone on every machine, healing each one the next time any `wp-*` command runs there.
+//
+// NOT ALSO CALLED FROM `wp-upgrade-shim`, though it would read naturally there (that bin already deletes a
+// retired FILE on the same principle). `upgrade-shim.ts` may import only `fs`/`path` so it still runs on a
+// tree too broken to load the rule engine: this package's barrel would pull in inversify and the config
+// loader, and a subpath import would resolve against the INSTALLED rules-config, which is a release behind
+// the local source — so a spawned `wp-upgrade-shim` would die on module resolution, in the one command an
+// L0-blocked session has left. Its header records that, and points here.
+//
+// DEPENDENCY-FREE ANYWAY: `fs`, `path` and `toError`. No inversify (see StaleBinSweeper), so this module
+// stays cheap for the startup path it runs on and importable by anything that later needs it.
+// ---------------------------------------------------------------------------
+// The one place the prefix is spelled. Everything outside it belongs to some other package.
+const WP_BIN_PREFIX = 'wp-';
+/**
+ * One dangling entry the sweep ACTED ON: what was linked, the target that was not there, and — when the
+ * removal itself failed — why. Data-only (per CLAUDE.md).
+ *
+ * `failure` exists because the removal is an `fs.rmSync`, not just a probe: an unwritable `.bin` (EACCES,
+ * a read-only mount) would otherwise heal silently-never while the tree kept advertising a command that
+ * does not exist, which is the precise defect this module exists to remove. Not thrown — the sweep is a
+ * courtesy and must never fail the `wp-*` command that called it — so the diagnostic rides back here and
+ * {@link StaleBinSweeper.report} states both outcomes.
+ */
+class StaleBinRemoval {
+    name; // the bin name as it appeared in .bin (e.g. 'wp-authorize')
+    target; // the link target that does not exist, as recorded in the symlink
+    failure; // '' = removed; non-empty = still there, and this is why
+    constructor(name, target, failure = '') {
+        this.name = name;
+        this.target = target;
+        this.failure = failure;
+    }
+}
+exports.StaleBinRemoval = StaleBinRemoval;
+/**
+ * Removes `node_modules/.bin/wp-*` entries whose symlink target is gone.
+ *
+ * Deliberately NOT `@injectable`: decorating it would import inversify, and this module must stay loadable
+ * by `wp-upgrade-shim` on a tree that cannot build a DI container (see the header). Callers use the shared
+ * {@link staleBinSweeper} instance, which is also what makes {@link sweepOnce}'s memo process-wide.
+ */
+class StaleBinSweeper {
+    // Roots already swept in THIS process. `writeTemplate` is called several times per `wp-*` command (once
+    // per instruct-ai doc), and a sweep that reported per call would print the same removals repeatedly.
+    swept = new Set();
+    /** Where the bins live for a tree. Public so a test can point at a fixture without guessing the layout. */
+    binDir(repoRoot) {
+        return path.join(repoRoot, 'node_modules', '.bin');
+    }
+    /**
+     * Sweep once per root per process, returning what was removed ([] on every later call for the same
+     * root, and [] when there was nothing to remove — the two are indistinguishable to a caller ON PURPOSE,
+     * because both mean "say nothing").
+     */
+    sweepOnce(repoRoot) {
+        if (this.swept.has(repoRoot))
+            return [];
+        this.swept.add(repoRoot);
+        return this.sweep(repoRoot);
+    }
+    /**
+     * Remove every dangling `wp-*` symlink under the tree's `.bin`, returning what went. [] when the
+     * directory does not exist (a linked worktree with no install of its own is the common case) or when
+     * everything there resolves.
+     *
+     * BEST EFFORT, PER ENTRY. A `.bin` that cannot be read, or one entry that cannot be removed, must never
+     * take down the `wp-*` command that called this — the sweep is a courtesy, not the command's job.
+     */
+    sweep(repoRoot) {
+        const dir = this.binDir(repoRoot);
+        const removed = [];
+        for (const name of this.entries(dir)) {
+            if (!name.startsWith(WP_BIN_PREFIX))
+                continue;
+            const removal = this.removeIfDangling(path.join(dir, name), name);
+            if (removal !== null)
+                removed.push(removal);
+        }
+        return removed;
+    }
+    /**
+     * The lines a caller prints for a sweep. [] for an empty sweep, so REMOVING NOTHING IS SILENT — this
+     * runs on every `wp-*` command and the common case must add no noise at all.
+     *
+     * Rendered here rather than at each call site so the two callers cannot describe the same act
+     * differently; each still chooses its own output channel and its own leading icon convention.
+     */
+    report(removed) {
+        if (removed.length === 0)
+            return [];
+        const gone = removed.filter((r) => r.failure === '');
+        const stuck = removed.filter((r) => r.failure !== '');
+        const lines = [];
+        if (gone.length > 0) {
+            lines.push(`✅ @webpieces: removed ${gone.length} dangling node_modules/.bin/wp-* symlink(s) left by an earlier release:`);
+            for (const r of gone)
+                lines.push(`     ${r.name} -> ${r.target} (target missing)`);
+            lines.push('   They pointed at scripts this release no longer ships, so they could only ever fail on execution.');
+        }
+        // A failed removal is STATED, never quietly dropped: the entry is still there, still advertising a
+        // command that does not exist, and only a human can fix an unwritable .bin.
+        if (stuck.length > 0) {
+            lines.push(`⚠️  @webpieces: ${stuck.length} dangling node_modules/.bin/wp-* symlink(s) could NOT be removed:`);
+            for (const r of stuck)
+                lines.push(`     ${r.name} -> ${r.target} (target missing; ${r.failure})`);
+            lines.push('   They still advertise commands this release does not ship. Nothing else is affected — remove them by hand.');
+        }
+        return lines;
+    }
+    // The directory listing, or [] when there is no .bin (or it cannot be read).
+    entries(dir) {
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable .bin means "nothing to sweep", never a failed wp-* command
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            if (!fs.existsSync(dir))
+                return [];
+            return fs.readdirSync(dir);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error; // best effort: no readable .bin means there is nothing to sweep
+            return [];
+        }
+    }
+    /**
+     * Remove ONE entry if — and only if — it is a symlink whose target does not exist. Returns what was
+     * acted on, with `failure` set when the entry was dangling but could not be removed; `null` when the
+     * entry was not a dangling `wp-*` link at all.
+     */
+    removeIfDangling(full, name) {
+        const target = this.danglingTarget(full);
+        if (target === null)
+            return null;
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unremovable entry is REPORTED, never fatal to the wp-* command that called the sweep
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            fs.rmSync(full, { force: true });
+            return new StaleBinRemoval(name, target);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            return new StaleBinRemoval(name, target, error.message);
+        }
+    }
+    /**
+     * The link target of a DANGLING symlink, or `null` when this entry is not one — a real file, a live
+     * link, or something we cannot stat. `existsSync` FOLLOWS symlinks, so a false answer on a path `lstat`
+     * calls a link is exactly the dangling case, with no need to resolve the target ourselves.
+     *
+     * Split from the removal so the two catches mean different things: an unreadable entry is simply not
+     * ours to touch, while a failed REMOVAL is a fact worth printing.
+     */
+    danglingTarget(full) {
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an entry we cannot stat is not ours to touch
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            if (!fs.lstatSync(full).isSymbolicLink())
+                return null;
+            if (fs.existsSync(full))
+                return null;
+            return fs.readlinkSync(full);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error; // best effort: an entry we cannot read is left exactly as it is
+            return null;
+        }
+    }
+}
+exports.StaleBinSweeper = StaleBinSweeper;
+// The shared instance — the memo in `sweepOnce` is per-instance, so every caller must use this one.
+exports.staleBinSweeper = new StaleBinSweeper();
+//# sourceMappingURL=stale-bin-sweep.js.map

package/src/stale-bin-sweep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-bin-sweep.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/stale-bin-sweep.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\nimport { toError } from './to-error';\n\n// ---------------------------------------------------------------------------\n// SWEEP DANGLING `node_modules/.bin/wp-*` SYMLINKS.\n//\n// THE DEFECT. pnpm's linker ADDS a link for every entry in the current manifest's `bin` map, but it never\n// sweeps `.bin` for orphans left behind by a PREVIOUS version of the SAME package. `@webpieces/pr-gate`\n// and `@webpieces/ai-hook-rules` are upgraded, never removed, so nothing ever triggers a delete: every\n// bin either package has EVER shipped stays linked forever, pointing at a script that is no longer on\n// disk. A scan of nine clones on ONE machine found 18 distinct dangling `wp-*` names.\n//\n// THE DEFECT IS ONGOING, AND A ROUTINE RENAME PRODUCES IT. Measured on this repo's own upgrade to\n// 0.4.728, DURING the session that wrote this file: PR #743 hard-renamed one `wp-*` command with no alias,\n// so the new manifest declares `wp-sync-main` and no longer declares its predecessor. One `pnpm install`\n// later, `.bin` held the NEW link created that minute AND the predecessor's link still sitting there from\n// the previous install, dangling — reproduced independently in two separate trees of this repo. So this is\n// not a historical mess left by a deleted feature that a one-time migration could mop up: it is\n// regenerated by the most ordinary change a package can make, on every clone, every time. That is the\n// argument for the call site below — the sweep has to ride a path that runs ROUTINELY, because the defect\n// is created routinely.\n//\n// The predecessor's NAME is deliberately not written here. `no-old-sync-main-name` forbids the dead\n// spelling in tracked source and blocked an earlier draft of this very comment, which is the rule working:\n// a retired command named in source is exactly how a dead name outlives its tooling — the thing this\n// module exists to clean up, one level out. PR #743 and the issue this shipped under carry the literal\n// name; nothing in the code needs it, because the predicate below is structural.\n//\n// WHY IT MATTERS MORE THAN TIDINESS. `ls node_modules/.bin` lists them, so a dangling entry ADVERTISES a\n// capability that does not exist — a human and an AI were both misled by that listing before checking the\n// link target — and the failure it eventually produces is self-referential and useless:\n// `Command \"wp-authorize\" not found / Did you mean \"pnpm wp-authorize\"?`. This is `upgrade-shim.ts`'s own\n// governing principle one level out: an entry pointing at a missing file is WORSE than absence.\n//\n// WHY A PREFIX AND NOT A NAME LIST. A hardcoded list of retired bin names would go stale in exactly the\n// way the symlinks did — the list assembled from the two names that prompted this would have caught 2 of\n// the 18, and it would NOT have caught the rename above, which had not happened yet when the list would\n// have been written. That is the general case: the next orphan is always created by a release later than\n// any list. A name list is also unwriteable here on purpose — see the note above about naming dead\n// commands in source. The predicate is structural instead — a `wp-` prefixed entry that is a SYMLINK whose target\n// does not exist — so it needs no maintenance and cannot miss a name nobody has thought of. The prefix is\n// the whole safety story: another package's bins are never touched.\n//\n// WHY NOT A postinstall HOOK. `setupDebugging.md` records the postinstall approach as ABANDONED in this\n// repo. The call site is the `wp-*` startup pass that regenerates `.webpieces/instruct-ai/*` — see\n// TemplateWriter — and that placement is the load-bearing half of the fix. This is not a tidy-up for one\n// repo: every developer's machine has this graveyard, and a cure that only cleans the tree somebody happens\n// to run it in is worthless. Riding the pass EVERY `wp-*` command takes is what makes the RELEASED sweep\n// reach every clone on every machine, healing each one the next time any `wp-*` command runs there.\n//\n// NOT ALSO CALLED FROM `wp-upgrade-shim`, though it would read naturally there (that bin already deletes a\n// retired FILE on the same principle). `upgrade-shim.ts` may import only `fs`/`path` so it still runs on a\n// tree too broken to load the rule engine: this package's barrel would pull in inversify and the config\n// loader, and a subpath import would resolve against the INSTALLED rules-config, which is a release behind\n// the local source — so a spawned `wp-upgrade-shim` would die on module resolution, in the one command an\n// L0-blocked session has left. Its header records that, and points here.\n//\n// DEPENDENCY-FREE ANYWAY: `fs`, `path` and `toError`. No inversify (see StaleBinSweeper), so this module\n// stays cheap for the startup path it runs on and importable by anything that later needs it.\n// ---------------------------------------------------------------------------\n\n// The one place the prefix is spelled. Everything outside it belongs to some other package.\nconst WP_BIN_PREFIX = 'wp-';\n\n/**\n * One dangling entry the sweep ACTED ON: what was linked, the target that was not there, and — when the\n * removal itself failed — why. Data-only (per CLAUDE.md).\n *\n * `failure` exists because the removal is an `fs.rmSync`, not just a probe: an unwritable `.bin` (EACCES,\n * a read-only mount) would otherwise heal silently-never while the tree kept advertising a command that\n * does not exist, which is the precise defect this module exists to remove. Not thrown — the sweep is a\n * courtesy and must never fail the `wp-*` command that called it — so the diagnostic rides back here and\n * {@link StaleBinSweeper.report} states both outcomes.\n */\nexport class StaleBinRemoval {\n    name: string;    // the bin name as it appeared in .bin (e.g. 'wp-authorize')\n    target: string;  // the link target that does not exist, as recorded in the symlink\n    failure: string; // '' = removed; non-empty = still there, and this is why\n\n    constructor(name: string, target: string, failure = '') {\n        this.name = name;\n        this.target = target;\n        this.failure = failure;\n    }\n}\n\n/**\n * Removes `node_modules/.bin/wp-*` entries whose symlink target is gone.\n *\n * Deliberately NOT `@injectable`: decorating it would import inversify, and this module must stay loadable\n * by `wp-upgrade-shim` on a tree that cannot build a DI container (see the header). Callers use the shared\n * {@link staleBinSweeper} instance, which is also what makes {@link sweepOnce}'s memo process-wide.\n */\nexport class StaleBinSweeper {\n    // Roots already swept in THIS process. `writeTemplate` is called several times per `wp-*` command (once\n    // per instruct-ai doc), and a sweep that reported per call would print the same removals repeatedly.\n    private readonly swept = new Set<string>();\n\n    /** Where the bins live for a tree. Public so a test can point at a fixture without guessing the layout. */\n    binDir(repoRoot: string): string {\n        return path.join(repoRoot, 'node_modules', '.bin');\n    }\n\n    /**\n     * Sweep once per root per process, returning what was removed ([] on every later call for the same\n     * root, and [] when there was nothing to remove — the two are indistinguishable to a caller ON PURPOSE,\n     * because both mean \"say nothing\").\n     */\n    sweepOnce(repoRoot: string): StaleBinRemoval[] {\n        if (this.swept.has(repoRoot)) return [];\n        this.swept.add(repoRoot);\n        return this.sweep(repoRoot);\n    }\n\n    /**\n     * Remove every dangling `wp-*` symlink under the tree's `.bin`, returning what went. [] when the\n     * directory does not exist (a linked worktree with no install of its own is the common case) or when\n     * everything there resolves.\n     *\n     * BEST EFFORT, PER ENTRY. A `.bin` that cannot be read, or one entry that cannot be removed, must never\n     * take down the `wp-*` command that called this — the sweep is a courtesy, not the command's job.\n     */\n    sweep(repoRoot: string): StaleBinRemoval[] {\n        const dir = this.binDir(repoRoot);\n        const removed: StaleBinRemoval[] = [];\n        for (const name of this.entries(dir)) {\n            if (!name.startsWith(WP_BIN_PREFIX)) continue;\n            const removal = this.removeIfDangling(path.join(dir, name), name);\n            if (removal !== null) removed.push(removal);\n        }\n        return removed;\n    }\n\n    /**\n     * The lines a caller prints for a sweep. [] for an empty sweep, so REMOVING NOTHING IS SILENT — this\n     * runs on every `wp-*` command and the common case must add no noise at all.\n     *\n     * Rendered here rather than at each call site so the two callers cannot describe the same act\n     * differently; each still chooses its own output channel and its own leading icon convention.\n     */\n    report(removed: readonly StaleBinRemoval[]): string[] {\n        if (removed.length === 0) return [];\n        const gone = removed.filter((r: StaleBinRemoval): boolean => r.failure === '');\n        const stuck = removed.filter((r: StaleBinRemoval): boolean => r.failure !== '');\n        const lines: string[] = [];\n        if (gone.length > 0) {\n            lines.push(`✅ @webpieces: removed ${gone.length} dangling node_modules/.bin/wp-* symlink(s) left by an earlier release:`);\n            for (const r of gone) lines.push(`     ${r.name} -> ${r.target} (target missing)`);\n            lines.push('   They pointed at scripts this release no longer ships, so they could only ever fail on execution.');\n        }\n        // A failed removal is STATED, never quietly dropped: the entry is still there, still advertising a\n        // command that does not exist, and only a human can fix an unwritable .bin.\n        if (stuck.length > 0) {\n            lines.push(`⚠️  @webpieces: ${stuck.length} dangling node_modules/.bin/wp-* symlink(s) could NOT be removed:`);\n            for (const r of stuck) lines.push(`     ${r.name} -> ${r.target} (target missing; ${r.failure})`);\n            lines.push('   They still advertise commands this release does not ship. Nothing else is affected — remove them by hand.');\n        }\n        return lines;\n    }\n\n    // The directory listing, or [] when there is no .bin (or it cannot be read).\n    private entries(dir: string): string[] {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable .bin means \"nothing to sweep\", never a failed wp-* command\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            if (!fs.existsSync(dir)) return [];\n            return fs.readdirSync(dir);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error; // best effort: no readable .bin means there is nothing to sweep\n            return [];\n        }\n    }\n\n    /**\n     * Remove ONE entry if — and only if — it is a symlink whose target does not exist. Returns what was\n     * acted on, with `failure` set when the entry was dangling but could not be removed; `null` when the\n     * entry was not a dangling `wp-*` link at all.\n     */\n    private removeIfDangling(full: string, name: string): StaleBinRemoval | null {\n        const target = this.danglingTarget(full);\n        if (target === null) return null;\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unremovable entry is REPORTED, never fatal to the wp-* command that called the sweep\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            fs.rmSync(full, { force: true });\n            return new StaleBinRemoval(name, target);\n        } catch (err: unknown) {\n            const error = toError(err);\n            return new StaleBinRemoval(name, target, error.message);\n        }\n    }\n\n    /**\n     * The link target of a DANGLING symlink, or `null` when this entry is not one — a real file, a live\n     * link, or something we cannot stat. `existsSync` FOLLOWS symlinks, so a false answer on a path `lstat`\n     * calls a link is exactly the dangling case, with no need to resolve the target ourselves.\n     *\n     * Split from the removal so the two catches mean different things: an unreadable entry is simply not\n     * ours to touch, while a failed REMOVAL is a fact worth printing.\n     */\n    private danglingTarget(full: string): string | null {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an entry we cannot stat is not ours to touch\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            if (!fs.lstatSync(full).isSymbolicLink()) return null;\n            if (fs.existsSync(full)) return null;\n            return fs.readlinkSync(full);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error; // best effort: an entry we cannot read is left exactly as it is\n            return null;\n        }\n    }\n}\n\n// The shared instance — the memo in `sweepOnce` is per-instance, so every caller must use this one.\nexport const staleBinSweeper = new StaleBinSweeper();\n"]}

package/templates/webpieces.review-checklists.md

@@ -130,8 +130,7 @@ whose `subagent` has no `.claude/agents/<subagent>.md`, so this should surface a
 {
   "id": "<the checklist id / subagent name>",
   "status": "green | yellow | red",
-  "output": "what you checked and what you found",
-  "override": ""
+  "output": "what you checked and what you found"
 }
 ```
 
@@ -139,16 +138,57 @@ whose `subagent` has no `.claude/agents/<subagent>.md`, so this should surface a
 | --- | --- |
 | `green` | 🟢 passes, nothing to flag |
 | `yellow` | 🟡 **passes with concerns.** Blocks nothing; your `output` is published on the PR for a human to read |
-| `red` + empty `override` | 🔴 **`wp-finish` refuses to open the PR** and prints your `output` verbatim |
-| `red` + non-empty `override` | 🟠 ships anyway; the `override` justification is published on the PR |
+| `red` | 🔴 **`wp-finish` refuses to open the PR** and prints your `output` verbatim |
+| `red` + an `override-<id>.json` | 🟠 ships anyway; the human's stated reason is published on the PR |
 
 > **The `success` boolean is REMOVED — there is no compatibility mode.** A verdict file still using it is
 > rejected with a message naming the replacement. It was removed because a boolean gave a reviewer no way
 > to say *"this is fine, but someone should look at X"*: the only route to raising a concern was to fail the
 > PR and then override your own failure, which reads on the dashboard as a deliberately-accepted defect.
 
-**Prefer `yellow` over `red`-plus-`override`** when a change is acceptable but worth attention. Reserve
-`red` + `override` for deliberately, visibly accepting a known issue.
+> **The `override` field is REMOVED from this file too, and there is no compatibility mode** — including
+> `"override": ""`, which is rejected as well, because the copy left in a reviewer's file is what teaches
+> the next reviewer that the field still exists. The ship-anyway decision MOVED to its own
+> `override-<id>.json`; see below.
+
+**Prefer `yellow` over `red`** when a change is acceptable but worth attention. Reserve `red` for a finding
+you actually want to block on — a red a human then authorizes reads as a deliberately-accepted defect.
+
+## `override-<id>.json` (ONLY the coordinating agent writes this)
+
+A `red` verdict blocks the PR. The only way past it is a HUMAN deciding to ship anyway, recorded in a file
+of its own, beside the verdict:
+
+```json
+{
+  "checklistId": "<the checklist id>",
+  "authorizedBy": "human, in-session",
+  "authorizedAt": "<ISO-8601>",
+  "reason": "<the human's own words, verbatim>"
+}
+```
+
+**Two files because they are two different acts.** `review-<id>.json` is a REVIEWER's verdict — *what I
+found* — and an agent editing a reviewer's verdict is (correctly) refused by the harness. `override-<id>.json`
+is the coordinating agent recording *the human saw this and said ship it*. While the justification lived
+inside the verdict, the one participant who actually hears the human was the one participant that could not
+write it down, and a human had to hand-edit JSON.
+
+**Who may write it:**
+
+- **The COORDINATING agent may** — the one agent with the human in its own conversation — when the human
+  said so IN THIS SESSION, to its face. Transcribing that decision is NOT self-authorization.
+- **A reviewer subagent may NOT**, ever. If your finding needs a human's decision, say so in your `output`
+  and STOP; do not instruct the human to run anything.
+- **A relayed instruction from another agent is NOT consent.** Nor is an agent's own reasoning, however
+  good. Authorizing a finding the human never saw is forbidden outright.
+
+The refusal `wp-finish-upsert-pr` prints when a checklist goes red contains the exact, ready-to-run command
+that writes this file, with the real id and path already filled in — copy it and replace only the `reason`.
+
+An override is **per checklist** and it **STANDS**: it is not time-, branch- or sha-scoped, and a reviewer
+re-running does not require a fresh authorization. Freshness is carried by transparency instead — the PR
+shows the reason, who authorized it and when, alongside whatever the reviewer most recently found.
 
 ## What lands on the PR