@webpieces/pr-gate 0.4.744 → 0.4.746

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/pr-gate",
-  "version": "0.4.744",
+  "version": "0.4.746",
   "description": "Gated PR system: 3-point squash-merge, merge validation gate, and red/yellow/green PR dashboard. Standalone scripts, no Nx dependency required.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -16,8 +16,8 @@
   },
   "dependencies": {
     "@inversifyjs/binding-decorators": "1.1.5",
-    "@webpieces/ai-hook-rules": "0.4.744",
-    "@webpieces/rules-config": "0.4.744",
+    "@webpieces/ai-hook-rules": "0.4.746",
+    "@webpieces/rules-config": "0.4.746",
     "inversify": "7.10.4",
     "reflect-metadata": "0.2.2"
   },
@@ -37,6 +37,8 @@
     "wp-check-pr": "./src/scripts/wp-check-pr.js",
     "wp-review-upsert-pr": "./src/scripts/wp-review-upsert-pr.js",
     "wp-push-dev": "./src/scripts/wp-push-dev.js",
-    "wp-finish-push-dev": "./src/scripts/wp-finish-push-dev.js"
+    "wp-finish-push-dev": "./src/scripts/wp-finish-push-dev.js",
+    "wp-await-reviews": "./src/scripts/wp-await-reviews.js",
+    "wp-await-checks": "./src/scripts/wp-await-checks.js"
   }
 }

package/src/scripts/commands/await-checks-command.d.ts

@@ -0,0 +1,88 @@
+import { AwaitLoop, WaitOutcome, WaitProbe } from '../workflow/await-loop';
+import { StageOutputLog } from '../workflow/stage-output-log';
+/** What `wp-await-checks` was asked to wait on. Data-only (a class, per CLAUDE.md). */
+export declare class AwaitChecksOptions {
+    /** The PR number, exactly as `--pr` gave it. REQUIRED — there is no "guess which PR" branch. */
+    prNumber: string;
+    constructor(prNumber: string);
+}
+/**
+ * `wp-await-checks --pr <n>` — BLOCK until GitHub's checks for that PR stop being in flight, then print
+ * where they landed.
+ *
+ * ─── OFFERED, NEVER INSTRUCTED ─────────────────────────────────────────────────────────────────────
+ * This exists for the see-it-land case, and for nothing else. `wp-finish-upsert-pr` still ends with
+ * "Nothing else is owed by the tooling — a person merges it. You can stop here.", and that stays the
+ * DEFAULT: several of this repo's workflows deliberately stop at a green PR, and landing is the
+ * developer's call, not the tooling's. Nothing here or in the finish banner tells an agent to wait —
+ * the banner names this command as an option and says out loud that stopping is still correct.
+ *
+ * What it replaces is not "stopping"; it is `gh pr checks --watch` in a loop, or the `echo .` keep-alive
+ * an agent falls back to when it has decided to see the PR land. See {@link AwaitLoop} for why a
+ * blocking command is the only wait a worktree-isolated subagent can express.
+ *
+ * ─── It reports, it does not judge ─────────────────────────────────────────────────────────────────
+ * A red check is an ANSWER, so the wait ends and the state is printed. Deciding what a failure means is
+ * the caller's, and turning a red check into a non-zero exit here would make "the checks finished" and
+ * "the checks passed" the same signal — which is exactly how a red PR gets reported as landed.
+ */
+export declare class AwaitChecksCommand {
+    private readonly awaitLoop;
+    private readonly stageConsole;
+    constructor(awaitLoop: AwaitLoop, stageConsole: StageOutputLog);
+    run(opts: AwaitChecksOptions): Promise<void>;
+}
+/** One check run's rollup state, as GitHub reports it. Data-only. */
+export declare class ChecksState {
+    /** How many checks GitHub currently lists. 0 means it has not created any yet — QUEUED, not absent. */
+    total: number;
+    pending: number;
+    failed: number;
+    /** True when `gh` could not be asked at all — the wait keeps going rather than claiming an answer. */
+    unreadable: boolean;
+    constructor(total: number, pending: number, failed: number, unreadable: boolean);
+    /**
+     * Settled means GitHub has created checks AND none of them is still running.
+     *
+     * `total === 0` is deliberately NOT settled. An empty rollup seconds after a push means the workflow
+     * has not been created yet — QUEUED — and treating it as "no checks, all clear" is how a PR gets
+     * called green before CI has started. The wait's own ceiling is what ends that case, and it ends it
+     * by saying "still waiting", which is the truth.
+     */
+    get settled(): boolean;
+    describe(): string;
+}
+/**
+ * The CI wait: one `gh pr view` per poll, classified into {@link ChecksState}.
+ *
+ * `gh pr view --json statusCheckRollup` rather than `gh pr checks`, because the rollup field is the
+ * stable JSON surface and returns an EMPTY array — not an error exit — for a PR whose checks have not
+ * been created yet. `gh pr checks` exits non-zero in several distinct "nothing to report" situations,
+ * which would make "queued" and "gh is broken" the same observation.
+ */
+export declare class ChecksWaitProbe implements WaitProbe {
+    private readonly prNumber;
+    readonly label = "CI checks";
+    readonly pollMs = 15000;
+    private state;
+    constructor(prNumber: string);
+    done(): boolean;
+    describe(): string;
+    settledReport(outcome: WaitOutcome): string;
+    stillWaitingReport(outcome: WaitOutcome): string;
+    /**
+     * One read of the rollup. Fails to `unreadable` rather than to "settled": a `gh` that cannot answer
+     * must never be able to end the wait, because the only thing worse than waiting too long is
+     * announcing an outcome nobody observed.
+     */
+    private read;
+    private classify;
+}
+/**
+ * `--pr` is required, and this is where that is enforced — before the loop starts, so a caller that
+ * forgot it is told immediately rather than after a nine-minute wait on nothing.
+ */
+export declare class AwaitChecksArgs {
+    /** The PR number from argv, or a CliExitError naming the flag it needs. */
+    parse(value: string): AwaitChecksOptions;
+}

package/src/scripts/commands/await-checks-command.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AwaitChecksArgs = exports.ChecksWaitProbe = exports.ChecksState = exports.AwaitChecksCommand = exports.AwaitChecksOptions = void 0;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const rules_config_1 = require("@webpieces/rules-config");
+const inversify_1 = require("inversify");
+const await_loop_1 = require("../workflow/await-loop");
+const stage_output_log_1 = require("../workflow/stage-output-log");
+/** What `wp-await-checks` was asked to wait on. Data-only (a class, per CLAUDE.md). */
+class AwaitChecksOptions {
+    /** The PR number, exactly as `--pr` gave it. REQUIRED — there is no "guess which PR" branch. */
+    prNumber;
+    // REQUIRED, no default. A defaulted "current branch's PR" would be a second spelling of the one
+    // question this command asks, reachable by typing less, and the failure mode is watching the wrong
+    // PR go green.
+    constructor(prNumber) {
+        this.prNumber = prNumber;
+    }
+}
+exports.AwaitChecksOptions = AwaitChecksOptions;
+/**
+ * `wp-await-checks --pr <n>` — BLOCK until GitHub's checks for that PR stop being in flight, then print
+ * where they landed.
+ *
+ * ─── OFFERED, NEVER INSTRUCTED ─────────────────────────────────────────────────────────────────────
+ * This exists for the see-it-land case, and for nothing else. `wp-finish-upsert-pr` still ends with
+ * "Nothing else is owed by the tooling — a person merges it. You can stop here.", and that stays the
+ * DEFAULT: several of this repo's workflows deliberately stop at a green PR, and landing is the
+ * developer's call, not the tooling's. Nothing here or in the finish banner tells an agent to wait —
+ * the banner names this command as an option and says out loud that stopping is still correct.
+ *
+ * What it replaces is not "stopping"; it is `gh pr checks --watch` in a loop, or the `echo .` keep-alive
+ * an agent falls back to when it has decided to see the PR land. See {@link AwaitLoop} for why a
+ * blocking command is the only wait a worktree-isolated subagent can express.
+ *
+ * ─── It reports, it does not judge ─────────────────────────────────────────────────────────────────
+ * A red check is an ANSWER, so the wait ends and the state is printed. Deciding what a failure means is
+ * the caller's, and turning a red check into a non-zero exit here would make "the checks finished" and
+ * "the checks passed" the same signal — which is exactly how a red PR gets reported as landed.
+ */
+let AwaitChecksCommand = class AwaitChecksCommand {
+    awaitLoop;
+    stageConsole;
+    constructor(awaitLoop, stageConsole) {
+        this.awaitLoop = awaitLoop;
+        this.stageConsole = stageConsole;
+    }
+    async run(opts) {
+        const probe = new ChecksWaitProbe(opts.prNumber);
+        const outcome = await this.awaitLoop.run(probe);
+        this.stageConsole.say(outcome.done ? probe.settledReport(outcome) : probe.stillWaitingReport(outcome));
+    }
+};
+exports.AwaitChecksCommand = AwaitChecksCommand;
+exports.AwaitChecksCommand = AwaitChecksCommand = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [await_loop_1.AwaitLoop,
+        stage_output_log_1.StageOutputLog])
+], AwaitChecksCommand);
+/** One check run's rollup state, as GitHub reports it. Data-only. */
+class ChecksState {
+    /** How many checks GitHub currently lists. 0 means it has not created any yet — QUEUED, not absent. */
+    total;
+    pending;
+    failed;
+    /** True when `gh` could not be asked at all — the wait keeps going rather than claiming an answer. */
+    unreadable;
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(total, pending, failed, unreadable) {
+        this.total = total;
+        this.pending = pending;
+        this.failed = failed;
+        this.unreadable = unreadable;
+    }
+    /**
+     * Settled means GitHub has created checks AND none of them is still running.
+     *
+     * `total === 0` is deliberately NOT settled. An empty rollup seconds after a push means the workflow
+     * has not been created yet — QUEUED — and treating it as "no checks, all clear" is how a PR gets
+     * called green before CI has started. The wait's own ceiling is what ends that case, and it ends it
+     * by saying "still waiting", which is the truth.
+     */
+    get settled() {
+        return !this.unreadable && this.total > 0 && this.pending === 0;
+    }
+    describe() {
+        if (this.unreadable)
+            return 'gh could not be read';
+        if (this.total === 0)
+            return 'no checks reported yet (queued)';
+        return `${String(this.total - this.pending)} of ${String(this.total)} done, `
+            + `${String(this.failed)} failed`;
+    }
+}
+exports.ChecksState = ChecksState;
+/**
+ * The CI wait: one `gh pr view` per poll, classified into {@link ChecksState}.
+ *
+ * `gh pr view --json statusCheckRollup` rather than `gh pr checks`, because the rollup field is the
+ * stable JSON surface and returns an EMPTY array — not an error exit — for a PR whose checks have not
+ * been created yet. `gh pr checks` exits non-zero in several distinct "nothing to report" situations,
+ * which would make "queued" and "gh is broken" the same observation.
+ */
+class ChecksWaitProbe {
+    prNumber;
+    label = 'CI checks';
+    // A network round trip per poll, so this is deliberately slow. CI on this repo runs ~1 minute; a
+    // 15-second poll finds it within a heartbeat of finishing and costs ~36 API calls per full wait.
+    pollMs = 15_000;
+    state = new ChecksState(0, 0, 0, true);
+    constructor(prNumber) {
+        this.prNumber = prNumber;
+    }
+    done() {
+        this.state = this.read();
+        return this.state.settled;
+    }
+    describe() {
+        return this.state.describe();
+    }
+    settledReport(outcome) {
+        const verdict = this.state.failed === 0
+            ? `🟢 All ${String(this.state.total)} check(s) passed`
+            : `🔴 ${String(this.state.failed)} of ${String(this.state.total)} check(s) FAILED`;
+        return `\n${verdict} after ${String(outcome.waitedSeconds)}s.\n`
+            + `   Read the detail with:  gh pr checks ${this.prNumber}\n`;
+    }
+    stillWaitingReport(outcome) {
+        return `\n⏳ Checks are still in flight after ${String(outcome.waitedSeconds)}s (${this.state.describe()})`
+            + ` — run me again:  pnpm wp-await-checks --pr ${this.prNumber}\n`
+            + '   (This is not a failure. The wait returns before the harness kills a quiet command.)\n';
+    }
+    /**
+     * One read of the rollup. Fails to `unreadable` rather than to "settled": a `gh` that cannot answer
+     * must never be able to end the wait, because the only thing worse than waiting too long is
+     * announcing an outcome nobody observed.
+     */
+    read() {
+        const result = (0, child_process_1.spawnSync)('gh', ['pr', 'view', this.prNumber, '--json', 'statusCheckRollup',
+            '--jq', '[.statusCheckRollup[] | (.status // .state)] | @tsv'], { encoding: 'utf8' });
+        if (result.status !== 0)
+            return new ChecksState(0, 0, 0, true);
+        return this.classify((result.stdout ?? '').trim());
+    }
+    // `status` is COMPLETED / IN_PROGRESS / QUEUED for a check run; a plain commit status has no
+    // `status` and its `state` is SUCCESS / PENDING / FAILURE / ERROR. The jq above collapses the two
+    // into one token per check, and everything that is not finished counts as pending.
+    classify(tsv) {
+        const tokens = tsv === '' ? [] : tsv.split(/\s+/);
+        const pending = tokens.filter((t) => PENDING_TOKENS.has(t)).length;
+        const failed = tokens.filter((t) => FAILED_TOKENS.has(t)).length;
+        return new ChecksState(tokens.length, pending, failed, false);
+    }
+}
+exports.ChecksWaitProbe = ChecksWaitProbe;
+const PENDING_TOKENS = new Set(['QUEUED', 'IN_PROGRESS', 'PENDING', 'WAITING', 'REQUESTED']);
+const FAILED_TOKENS = new Set(['FAILURE', 'ERROR', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE']);
+/**
+ * `--pr` is required, and this is where that is enforced — before the loop starts, so a caller that
+ * forgot it is told immediately rather than after a nine-minute wait on nothing.
+ */
+class AwaitChecksArgs {
+    /** The PR number from argv, or a CliExitError naming the flag it needs. */
+    parse(value) {
+        if (!/^\d+$/.test(value.trim())) {
+            throw new rules_config_1.CliExitError(2, '❌ wp-await-checks needs the PR number to wait on:  pnpm wp-await-checks --pr <n>\n'
+                + '   `gh pr view --json number` prints it for the current branch.');
+        }
+        return new AwaitChecksOptions(value.trim());
+    }
+}
+exports.AwaitChecksArgs = AwaitChecksArgs;
+//# sourceMappingURL=await-checks-command.js.map

package/src/scripts/commands/await-checks-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"await-checks-command.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/commands/await-checks-command.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport { CliExitError } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { AwaitLoop, WaitOutcome, WaitProbe } from '../workflow/await-loop';\nimport { StageOutputLog } from '../workflow/stage-output-log';\n\n/** What `wp-await-checks` was asked to wait on. Data-only (a class, per CLAUDE.md). */\nexport class AwaitChecksOptions {\n    /** The PR number, exactly as `--pr` gave it. REQUIRED — there is no \"guess which PR\" branch. */\n    prNumber: string;\n\n    // REQUIRED, no default. A defaulted \"current branch's PR\" would be a second spelling of the one\n    // question this command asks, reachable by typing less, and the failure mode is watching the wrong\n    // PR go green.\n    constructor(prNumber: string) {\n        this.prNumber = prNumber;\n    }\n}\n\n/**\n * `wp-await-checks --pr <n>` — BLOCK until GitHub's checks for that PR stop being in flight, then print\n * where they landed.\n *\n * ─── OFFERED, NEVER INSTRUCTED ─────────────────────────────────────────────────────────────────────\n * This exists for the see-it-land case, and for nothing else. `wp-finish-upsert-pr` still ends with\n * \"Nothing else is owed by the tooling — a person merges it. You can stop here.\", and that stays the\n * DEFAULT: several of this repo's workflows deliberately stop at a green PR, and landing is the\n * developer's call, not the tooling's. Nothing here or in the finish banner tells an agent to wait —\n * the banner names this command as an option and says out loud that stopping is still correct.\n *\n * What it replaces is not \"stopping\"; it is `gh pr checks --watch` in a loop, or the `echo .` keep-alive\n * an agent falls back to when it has decided to see the PR land. See {@link AwaitLoop} for why a\n * blocking command is the only wait a worktree-isolated subagent can express.\n *\n * ─── It reports, it does not judge ─────────────────────────────────────────────────────────────────\n * A red check is an ANSWER, so the wait ends and the state is printed. Deciding what a failure means is\n * the caller's, and turning a red check into a non-zero exit here would make \"the checks finished\" and\n * \"the checks passed\" the same signal — which is exactly how a red PR gets reported as landed.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class AwaitChecksCommand {\n    constructor(\n        private readonly awaitLoop: AwaitLoop,\n        private readonly stageConsole: StageOutputLog,\n    ) {}\n\n    async run(opts: AwaitChecksOptions): Promise<void> {\n        const probe = new ChecksWaitProbe(opts.prNumber);\n        const outcome = await this.awaitLoop.run(probe);\n        this.stageConsole.say(outcome.done ? probe.settledReport(outcome) : probe.stillWaitingReport(outcome));\n    }\n}\n\n/** One check run's rollup state, as GitHub reports it. Data-only. */\nexport class ChecksState {\n    /** How many checks GitHub currently lists. 0 means it has not created any yet — QUEUED, not absent. */\n    total: number;\n    pending: number;\n    failed: number;\n    /** True when `gh` could not be asked at all — the wait keeps going rather than claiming an answer. */\n    unreadable: boolean;\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(total: number, pending: number, failed: number, unreadable: boolean) {\n        this.total = total;\n        this.pending = pending;\n        this.failed = failed;\n        this.unreadable = unreadable;\n    }\n\n    /**\n     * Settled means GitHub has created checks AND none of them is still running.\n     *\n     * `total === 0` is deliberately NOT settled. An empty rollup seconds after a push means the workflow\n     * has not been created yet — QUEUED — and treating it as \"no checks, all clear\" is how a PR gets\n     * called green before CI has started. The wait's own ceiling is what ends that case, and it ends it\n     * by saying \"still waiting\", which is the truth.\n     */\n    get settled(): boolean {\n        return !this.unreadable && this.total > 0 && this.pending === 0;\n    }\n\n    describe(): string {\n        if (this.unreadable) return 'gh could not be read';\n        if (this.total === 0) return 'no checks reported yet (queued)';\n        return `${String(this.total - this.pending)} of ${String(this.total)} done, `\n            + `${String(this.failed)} failed`;\n    }\n}\n\n/**\n * The CI wait: one `gh pr view` per poll, classified into {@link ChecksState}.\n *\n * `gh pr view --json statusCheckRollup` rather than `gh pr checks`, because the rollup field is the\n * stable JSON surface and returns an EMPTY array — not an error exit — for a PR whose checks have not\n * been created yet. `gh pr checks` exits non-zero in several distinct \"nothing to report\" situations,\n * which would make \"queued\" and \"gh is broken\" the same observation.\n */\nexport class ChecksWaitProbe implements WaitProbe {\n    readonly label = 'CI checks';\n    // A network round trip per poll, so this is deliberately slow. CI on this repo runs ~1 minute; a\n    // 15-second poll finds it within a heartbeat of finishing and costs ~36 API calls per full wait.\n    readonly pollMs = 15_000;\n\n    private state: ChecksState = new ChecksState(0, 0, 0, true);\n\n    constructor(private readonly prNumber: string) {}\n\n    done(): boolean {\n        this.state = this.read();\n        return this.state.settled;\n    }\n\n    describe(): string {\n        return this.state.describe();\n    }\n\n    settledReport(outcome: WaitOutcome): string {\n        const verdict = this.state.failed === 0\n            ? `🟢 All ${String(this.state.total)} check(s) passed`\n            : `🔴 ${String(this.state.failed)} of ${String(this.state.total)} check(s) FAILED`;\n        return `\\n${verdict} after ${String(outcome.waitedSeconds)}s.\\n`\n            + `   Read the detail with:  gh pr checks ${this.prNumber}\\n`;\n    }\n\n    stillWaitingReport(outcome: WaitOutcome): string {\n        return `\\n⏳ Checks are still in flight after ${String(outcome.waitedSeconds)}s (${this.state.describe()})`\n            + ` — run me again:  pnpm wp-await-checks --pr ${this.prNumber}\\n`\n            + '   (This is not a failure. The wait returns before the harness kills a quiet command.)\\n';\n    }\n\n    /**\n     * One read of the rollup. Fails to `unreadable` rather than to \"settled\": a `gh` that cannot answer\n     * must never be able to end the wait, because the only thing worse than waiting too long is\n     * announcing an outcome nobody observed.\n     */\n    private read(): ChecksState {\n        const result = spawnSync(\n            'gh',\n            ['pr', 'view', this.prNumber, '--json', 'statusCheckRollup',\n                '--jq', '[.statusCheckRollup[] | (.status // .state)] | @tsv'],\n            { encoding: 'utf8' });\n        if (result.status !== 0) return new ChecksState(0, 0, 0, true);\n        return this.classify((result.stdout ?? '').trim());\n    }\n\n    // `status` is COMPLETED / IN_PROGRESS / QUEUED for a check run; a plain commit status has no\n    // `status` and its `state` is SUCCESS / PENDING / FAILURE / ERROR. The jq above collapses the two\n    // into one token per check, and everything that is not finished counts as pending.\n    private classify(tsv: string): ChecksState {\n        const tokens = tsv === '' ? [] : tsv.split(/\\s+/);\n        const pending = tokens.filter((t: string): boolean => PENDING_TOKENS.has(t)).length;\n        const failed = tokens.filter((t: string): boolean => FAILED_TOKENS.has(t)).length;\n        return new ChecksState(tokens.length, pending, failed, false);\n    }\n}\n\nconst PENDING_TOKENS: ReadonlySet<string> = new Set(['QUEUED', 'IN_PROGRESS', 'PENDING', 'WAITING', 'REQUESTED']);\nconst FAILED_TOKENS: ReadonlySet<string> = new Set(['FAILURE', 'ERROR', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE']);\n\n/**\n * `--pr` is required, and this is where that is enforced — before the loop starts, so a caller that\n * forgot it is told immediately rather than after a nine-minute wait on nothing.\n */\nexport class AwaitChecksArgs {\n    /** The PR number from argv, or a CliExitError naming the flag it needs. */\n    parse(value: string): AwaitChecksOptions {\n        if (!/^\\d+$/.test(value.trim())) {\n            throw new CliExitError(2,\n                '❌ wp-await-checks needs the PR number to wait on:  pnpm wp-await-checks --pr <n>\\n'\n                + '   `gh pr view --json number` prints it for the current branch.');\n        }\n        return new AwaitChecksOptions(value.trim());\n    }\n}\n"]}

package/src/scripts/commands/await-reviews-command.d.ts

@@ -0,0 +1,85 @@
+import { RepoRootFinder, RequiredChecklist, ReviewJsonService } from '@webpieces/rules-config';
+import { AwaitLoop, WaitOutcome, WaitProbe } from '../workflow/await-loop';
+import { ChecklistScanner } from '../workflow/checklist-scanner';
+import { StageOutputLog } from '../workflow/stage-output-log';
+/**
+ * `wp-await-reviews` — BLOCK until every reviewer stage ② requested for this branch has written its
+ * verdict, then print what each one said.
+ *
+ * ─── Why a command and not an instruction ──────────────────────────────────────────────────────────
+ * An agent that has just spawned four reviewer subagents has nothing to do until they answer, and a
+ * worktree-isolated subagent cannot simply wait: ending its turn ends its run. See {@link AwaitLoop}
+ * for the full chain and the measurement (18.3% of all fleet tokens in one day spent on `echo .`).
+ * A blocking Bash call is the only wait primitive it has, so webpieces provides one.
+ *
+ * ─── It INVENTS NO STATE ───────────────────────────────────────────────────────────────────────────
+ * The set of reviewers a branch owes is `ChecklistScanner`'s answer — the SAME one `wp-review-upsert-pr`
+ * lists and `wp-finish-upsert-pr` blocks on — and the verdicts are the `review-<id>.json` files those
+ * two already read. Nothing here writes anything, and there is no third opinion about who is owed: a
+ * waiter that computed its own set could finish while finish still refused, which is the one outcome
+ * that would make waiting worse than not waiting.
+ *
+ * The scan runs ONCE. Its `applicable` set is a function of the diff, which does not change while the
+ * agent sits still, so re-scanning per poll would re-run `git diff` every few seconds to re-derive an
+ * unchanged answer. Only the verdict FILES are re-read, which is the only thing a reviewer changes.
+ *
+ * ─── What it does NOT do ───────────────────────────────────────────────────────────────────────────
+ * It does not judge. A red verdict is a completed review, so this command RETURNS on it and prints it;
+ * refusing the PR over it is `wp-finish-upsert-pr`'s job and stays there. It exits non-zero only when it
+ * cannot do its own job at all.
+ */
+export declare class AwaitReviewsCommand {
+    private readonly repoRootFinder;
+    private readonly checklistScanner;
+    private readonly reviewJsonService;
+    private readonly awaitLoop;
+    private readonly stageConsole;
+    constructor(repoRootFinder: RepoRootFinder, checklistScanner: ChecklistScanner, reviewJsonService: ReviewJsonService, awaitLoop: AwaitLoop, stageConsole: StageOutputLog);
+    run(): Promise<void>;
+    private reportNothingOwed;
+    private reportDisabled;
+    private report;
+}
+/**
+ * The reviewer wait itself: which checklists are owed, and what the files on disk say about them right
+ * now. It owns the reporting too, because every line it prints is derived from the same verdict read —
+ * a report that re-read the files could disagree with the answer that ended the wait.
+ */
+export declare class ReviewerWaitProbe implements WaitProbe {
+    private readonly reviewJsonService;
+    private readonly reviewPath;
+    private readonly waitedOn;
+    private readonly applicable;
+    readonly label = "reviewers";
+    readonly pollMs = 3000;
+    private results;
+    constructor(reviewJsonService: ReviewJsonService, reviewPath: string, waitedOn: readonly RequiredChecklist[], applicable: readonly RequiredChecklist[]);
+    /**
+     * Done when every awaited reviewer has ANSWERED — not when every answer is a pass.
+     *
+     * That distinction is the whole contract of a wait, and getting it wrong makes the command useless
+     * in the case it matters most. `ReviewJsonService.pendingChecklists` is finish's GATE predicate and
+     * counts a RED verdict as still owed, correctly: the PR is refused until the finding is fixed. But
+     * a red reviewer has finished; it will never write a different answer on its own, so waiting for it
+     * to stop being red is waiting forever. The wait therefore ends on ARRIVAL — a verdict file that
+     * exists, whatever it says — and `wp-finish-upsert-pr` keeps sole ownership of the gate.
+     *
+     * `CK_BAD_FORMAT` counts as arrived too: the file is there and unreadable, which is a thing to FIX
+     * (four characters of JSON), not a thing to wait longer for.
+     */
+    done(): boolean;
+    describe(): string;
+    /** Every reviewer's answer, printed once the wait is over — the reason to wait rather than sleep. */
+    verdictReport(outcome: WaitOutcome): string;
+    /**
+     * The timeout report. It is a NORMAL exit and says so, because an agent that reads this as a failure
+     * goes hunting for a broken reviewer instead of running one more plain command.
+     */
+    stillWaitingReport(outcome: WaitOutcome): string;
+    private oneVerdict;
+    private detail;
+    private icon;
+    private nextStep;
+    private pending;
+    private reload;
+}

package/src/scripts/commands/await-reviews-command.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReviewerWaitProbe = exports.AwaitReviewsCommand = void 0;
+const tslib_1 = require("tslib");
+const rules_config_1 = require("@webpieces/rules-config");
+const inversify_1 = require("inversify");
+const await_loop_1 = require("../workflow/await-loop");
+const checklist_scanner_1 = require("../workflow/checklist-scanner");
+const stage_output_log_1 = require("../workflow/stage-output-log");
+/**
+ * `wp-await-reviews` — BLOCK until every reviewer stage ② requested for this branch has written its
+ * verdict, then print what each one said.
+ *
+ * ─── Why a command and not an instruction ──────────────────────────────────────────────────────────
+ * An agent that has just spawned four reviewer subagents has nothing to do until they answer, and a
+ * worktree-isolated subagent cannot simply wait: ending its turn ends its run. See {@link AwaitLoop}
+ * for the full chain and the measurement (18.3% of all fleet tokens in one day spent on `echo .`).
+ * A blocking Bash call is the only wait primitive it has, so webpieces provides one.
+ *
+ * ─── It INVENTS NO STATE ───────────────────────────────────────────────────────────────────────────
+ * The set of reviewers a branch owes is `ChecklistScanner`'s answer — the SAME one `wp-review-upsert-pr`
+ * lists and `wp-finish-upsert-pr` blocks on — and the verdicts are the `review-<id>.json` files those
+ * two already read. Nothing here writes anything, and there is no third opinion about who is owed: a
+ * waiter that computed its own set could finish while finish still refused, which is the one outcome
+ * that would make waiting worse than not waiting.
+ *
+ * The scan runs ONCE. Its `applicable` set is a function of the diff, which does not change while the
+ * agent sits still, so re-scanning per poll would re-run `git diff` every few seconds to re-derive an
+ * unchanged answer. Only the verdict FILES are re-read, which is the only thing a reviewer changes.
+ *
+ * ─── What it does NOT do ───────────────────────────────────────────────────────────────────────────
+ * It does not judge. A red verdict is a completed review, so this command RETURNS on it and prints it;
+ * refusing the PR over it is `wp-finish-upsert-pr`'s job and stays there. It exits non-zero only when it
+ * cannot do its own job at all.
+ */
+let AwaitReviewsCommand = class AwaitReviewsCommand {
+    repoRootFinder;
+    checklistScanner;
+    reviewJsonService;
+    awaitLoop;
+    stageConsole;
+    constructor(repoRootFinder, checklistScanner, reviewJsonService, awaitLoop, stageConsole) {
+        this.repoRootFinder = repoRootFinder;
+        this.checklistScanner = checklistScanner;
+        this.reviewJsonService = reviewJsonService;
+        this.awaitLoop = awaitLoop;
+        this.stageConsole = stageConsole;
+    }
+    async run() {
+        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());
+        const config = (0, rules_config_1.loadAndValidate)(repoRoot).prGate;
+        // contextStage '' — a WAIT must not write pr-context.json. That file records the diff a review
+        // was briefed against, and rewriting it mid-review would restate the briefing under the
+        // reviewers currently reading it.
+        const scan = this.checklistScanner.scan(repoRoot, config.checklists, new checklist_scanner_1.ChecklistScanOptions(true, ''));
+        if (scan.reviewersDisabled)
+            return this.reportDisabled(scan.suppressed);
+        if (scan.applicable.length === 0)
+            return this.reportNothingOwed();
+        // WAIT on the set finish blocks on (`outstanding`), REPORT on everything that applies. The two
+        // sets differ by exactly the optional checklists nobody ran — `required: false` means the PR does
+        // not wait for them, and a wait that did would never end, because nothing is ever going to write
+        // a verdict for a reviewer that was deliberately never spawned. (The SET is shared with finish;
+        // the PREDICATE is not — see `done()` for why a wait ends on arrival and finish does not.)
+        const probe = new ReviewerWaitProbe(this.reviewJsonService, scan.reviewPath, scan.outstanding, scan.applicable);
+        const outcome = await this.awaitLoop.run(probe);
+        this.report(probe, outcome);
+    }
+    // Nothing to wait for, and saying so is the whole value: an agent that got no answer here would
+    // otherwise assume the wait is still owed and start spinning again.
+    reportNothingOwed() {
+        this.stageConsole.say('\n✅ No reviewer was requested for this branch — nothing to wait for.\n');
+    }
+    reportDisabled(suppressed) {
+        this.stageConsole.say(`\n⚫ Every reviewer is switched off on this machine (experimental.turnOffAllReviewers), so `
+            + `${String(suppressed.length)} checklist(s) that would have run are not running. There is `
+            + 'nothing to wait for.\n');
+    }
+    report(probe, outcome) {
+        this.stageConsole.say(outcome.done ? probe.verdictReport(outcome) : probe.stillWaitingReport(outcome));
+    }
+};
+exports.AwaitReviewsCommand = AwaitReviewsCommand;
+exports.AwaitReviewsCommand = AwaitReviewsCommand = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [rules_config_1.RepoRootFinder,
+        checklist_scanner_1.ChecklistScanner,
+        rules_config_1.ReviewJsonService,
+        await_loop_1.AwaitLoop,
+        stage_output_log_1.StageOutputLog])
+], AwaitReviewsCommand);
+/**
+ * The reviewer wait itself: which checklists are owed, and what the files on disk say about them right
+ * now. It owns the reporting too, because every line it prints is derived from the same verdict read —
+ * a report that re-read the files could disagree with the answer that ended the wait.
+ */
+class ReviewerWaitProbe {
+    reviewJsonService;
+    reviewPath;
+    waitedOn;
+    applicable;
+    label = 'reviewers';
+    // Verdict files are local reads, so polling them costs nothing worth economizing on. Fast enough
+    // that the command returns within seconds of the last reviewer finishing, which is the point.
+    pollMs = 3_000;
+    results = [];
+    constructor(reviewJsonService, reviewPath, waitedOn, applicable) {
+        this.reviewJsonService = reviewJsonService;
+        this.reviewPath = reviewPath;
+        this.waitedOn = waitedOn;
+        this.applicable = applicable;
+        this.reload();
+    }
+    /**
+     * Done when every awaited reviewer has ANSWERED — not when every answer is a pass.
+     *
+     * That distinction is the whole contract of a wait, and getting it wrong makes the command useless
+     * in the case it matters most. `ReviewJsonService.pendingChecklists` is finish's GATE predicate and
+     * counts a RED verdict as still owed, correctly: the PR is refused until the finding is fixed. But
+     * a red reviewer has finished; it will never write a different answer on its own, so waiting for it
+     * to stop being red is waiting forever. The wait therefore ends on ARRIVAL — a verdict file that
+     * exists, whatever it says — and `wp-finish-upsert-pr` keeps sole ownership of the gate.
+     *
+     * `CK_BAD_FORMAT` counts as arrived too: the file is there and unreadable, which is a thing to FIX
+     * (four characters of JSON), not a thing to wait longer for.
+     */
+    done() {
+        this.reload();
+        return this.pending().length === 0;
+    }
+    describe() {
+        const owed = this.pending().length;
+        const total = this.waitedOn.length;
+        return `${String(total - owed)} of ${String(total)} verdicts in`;
+    }
+    /** Every reviewer's answer, printed once the wait is over — the reason to wait rather than sleep. */
+    verdictReport(outcome) {
+        // The headline counts what was WAITED ON; the list below covers everything that APPLIES, so an
+        // optional checklist nobody ran shows as ❓ rather than being quietly dropped. Reporting only the
+        // waited-on set would let a shorter list imply the others passed.
+        const lines = [
+            `\n✅ All ${String(this.waitedOn.length)} awaited reviewer verdict(s) are in after `
+                + `${String(outcome.waitedSeconds)}s:\n`,
+        ];
+        for (const req of this.applicable)
+            lines.push(this.oneVerdict(req));
+        lines.push(this.nextStep());
+        return lines.join('\n') + '\n';
+    }
+    /**
+     * The timeout report. It is a NORMAL exit and says so, because an agent that reads this as a failure
+     * goes hunting for a broken reviewer instead of running one more plain command.
+     */
+    stillWaitingReport(outcome) {
+        const owed = this.pending();
+        return `\n⏳ Still waiting after ${String(outcome.waitedSeconds)}s — run me again:  pnpm wp-await-reviews\n`
+            + '   (This is not a failure. The wait returns before the harness kills a quiet command, so a\n'
+            + '    long review costs a handful of calls instead of hundreds of keep-alive turns.)\n\n'
+            + `   ${String(owed.length)} of ${String(this.waitedOn.length)} still owe a verdict: `
+            + `${owed.map((r) => r.id).join(', ')}\n`;
+    }
+    oneVerdict(req) {
+        const verdict = this.reviewJsonService.resolveVerdict(req, this.results);
+        return `   ${this.icon(verdict)} ${verdict.id} — ${verdict.status}${this.detail(verdict)}`;
+    }
+    // Only a NON-passing verdict's detail is printed. A green reviewer's output is already on the PR,
+    // and reprinting four of them here would bury the one line that needs acting on.
+    detail(verdict) {
+        if (verdict.status !== rules_config_1.CK_FAIL || verdict.detail === '')
+            return '';
+        return `\n      ${verdict.detail.split('\n').join('\n      ')}`;
+    }
+    icon(verdict) {
+        if (verdict.status === rules_config_1.CK_FAIL)
+            return '🔴';
+        if (verdict.status === rules_config_1.CK_MISSING || verdict.status === rules_config_1.CK_BAD_FORMAT)
+            return '❓';
+        return '🟢';
+    }
+    // Named because a wait that ends without saying what it unblocked leaves the agent to guess, and
+    // guessing here means spinning again. A red verdict changes the next move, so it is called out.
+    nextStep() {
+        const anyRed = this.applicable.some((req) => this.reviewJsonService.resolveVerdict(req, this.results).status === rules_config_1.CK_FAIL);
+        return anyRed
+            ? '\n   A reviewer REFUSED. Fix what it found — re-spawning it against unchanged code buys the\n'
+                + '   same answer — then re-run the review stage.\n'
+            : '\n   Nothing is owed on the review front.\n';
+    }
+    // The awaited checklists whose verdict file has not appeared yet — see `done()` for why this is
+    // arrival and not the gate's own "still owed".
+    pending() {
+        return this.waitedOn.filter((req) => this.reviewJsonService.resolveVerdict(req, this.results).status === rules_config_1.CK_MISSING);
+    }
+    reload() {
+        this.results = this.reviewJsonService.loadChecklistResults(this.reviewPath, this.applicable);
+    }
+}
+exports.ReviewerWaitProbe = ReviewerWaitProbe;
+//# sourceMappingURL=await-reviews-command.js.map