@webpieces/pr-gate 0.4.564 → 0.4.566

package/src/scripts/workflow/git-exec.d.ts

@@ -1,5 +1,16 @@
 import { RepoRootFinder } from '@webpieces/rules-config';
 import { GitStatusEntry, GitStatusParser } from './git-status';
+/**
+ * The result of a git command that was allowed to fail. Data-only (per CLAUDE.md) so a caller asks
+ * `outcome.ok` rather than re-deriving "did it work" from a status number at every site.
+ */
+export declare class GitOutcome {
+    status: number;
+    stdout: string;
+    stderr: string;
+    constructor(status: number, stdout: string, stderr: string);
+    get ok(): boolean;
+}
 /** Shared git precondition checks + push logic for the PR/merge workflow. */
 export declare class GitExec {
     private readonly repoRootFinder;
@@ -48,6 +59,14 @@ export declare class GitExec {
      * 3-point squash rewrites history) and -u for a brand-new branch.
      */
     ensurePushed(currentBranch: string): void;
-    private gitQuery;
+    /**
+     * Run a git command that MAY legitimately fail and report the outcome instead of aborting — for the
+     * questions whose "no" is an answer rather than an error (does this remote ref exist? did this merge
+     * conflict?). Distinct from {@link runGitChecked}, which exists for the commands where continuing on
+     * failure would operate on wrong state.
+     */
+    tryGit(args: string[], cwd: string): GitOutcome;
+    /** Read-only git query that MUST succeed, trimmed. Public sibling of the private raw form. */
+    gitQuery(args: string[], cwd: string, failMsg: string): string;
     private rawGitQuery;
 }

package/src/scripts/workflow/git-exec.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GitExec = void 0;
+exports.GitExec = exports.GitOutcome = void 0;
 const tslib_1 = require("tslib");
 const child_process_1 = require("child_process");
 const rules_config_1 = require("@webpieces/rules-config");
@@ -10,6 +10,24 @@ const SEP = '━━━━━━━━━━━━━━━━━━━━━━
 // The AI-facing doc the failure messages point at (generated under `.webpieces/instruct-ai`, at the
 // REPO ROOT — resolved absolute so the AI opens it regardless of the cwd it reads the message from).
 const GIT_WORKFLOW_DOC_NAME = 'webpieces.git-workflow.md';
+/**
+ * The result of a git command that was allowed to fail. Data-only (per CLAUDE.md) so a caller asks
+ * `outcome.ok` rather than re-deriving "did it work" from a status number at every site.
+ */
+class GitOutcome {
+    status;
+    stdout;
+    stderr;
+    constructor(status, stdout, stderr) {
+        this.status = status;
+        this.stdout = stdout;
+        this.stderr = stderr;
+    }
+    get ok() {
+        return this.status === 0;
+    }
+}
+exports.GitOutcome = GitOutcome;
 /** Shared git precondition checks + push logic for the PR/merge workflow. */
 let GitExec = class GitExec {
     repoRootFinder;
@@ -106,8 +124,17 @@ let GitExec = class GitExec {
             this.runGitChecked(['push', '-u', 'origin', `HEAD:${currentBranch}`], 'Failed to push new branch');
         }
     }
-    // Run a read-only git query from the repo root; abort if git itself errors. Kept `cwd`-explicit
-    // because `git ls-files --others` is scoped to the cwd subtree.
+    /**
+     * Run a git command that MAY legitimately fail and report the outcome instead of aborting — for the
+     * questions whose "no" is an answer rather than an error (does this remote ref exist? did this merge
+     * conflict?). Distinct from {@link runGitChecked}, which exists for the commands where continuing on
+     * failure would operate on wrong state.
+     */
+    tryGit(args, cwd) {
+        const out = (0, child_process_1.spawnSync)('git', args, { encoding: 'utf8', cwd });
+        return new GitOutcome(out.status ?? 1, (out.stdout ?? '').trim(), (out.stderr ?? '').trim());
+    }
+    /** Read-only git query that MUST succeed, trimmed. Public sibling of the private raw form. */
     gitQuery(args, cwd, failMsg) {
         return this.rawGitQuery(args, cwd, failMsg).trim();
     }

package/src/scripts/workflow/git-exec.js.map

@@ -1 +1 @@
-{"version":3,"file":"git-exec.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/git-exec.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport { CliExitError, RepoRootFinder } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { GitStatusEntry, GitStatusParser } from './git-status';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n// The AI-facing doc the failure messages point at (generated under `.webpieces/instruct-ai`, at the\n// REPO ROOT — resolved absolute so the AI opens it regardless of the cwd it reads the message from).\nconst GIT_WORKFLOW_DOC_NAME = 'webpieces.git-workflow.md';\n\n/** Shared git precondition checks + push logic for the PR/merge workflow. */\n@injectable(bindingScopeValues.Singleton)\nexport class GitExec {\n    constructor(\n        private readonly repoRootFinder: RepoRootFinder,\n        private readonly statusParser: GitStatusParser,\n    ) {}\n\n    /**\n     * Raw `git status --porcelain` with ONLY the trailing newline(s) stripped — never `.trim()`.\n     *\n     * There used to be a trimmed sibling here (`uncommittedFiles`) and it was a data-destroying trap:\n     * porcelain column 1 is the index state and column 2 the worktree state, so an unstaged\n     * modification is \" M path\"; `trim()` eats that leading space and the line then reads \"M path\",\n     * i.e. STAGED — the exact inverse of the truth. It is deleted. This method is for EMPTINESS\n     * (\"is the tree dirty at all?\") and for PRINTING; anything that reasons about the two columns\n     * calls {@link statusEntries} and reads booleans instead of re-parsing a string.\n     *\n     * Tracked changes (staged + unstaged) AND untracked files, EXCLUDING gitignored paths — so\n     * `.webpieces/` tooling artifacts never count. Empty string = fully committed.\n     */\n    porcelainStatus(cwd: string): string {\n        return this.rawGitQuery(['status', '--porcelain'], cwd,\n            'Failed to run `git status --porcelain` to check the working tree.').replace(/\\n+$/, '');\n    }\n\n    /**\n     * The same status, PARSED: two status columns, an unquoted path, and explicit\n     * `isStaged()`/`isUnstaged()`/`isUntracked()` answers. Use this for every semantic question.\n     */\n    statusEntries(cwd: string): GitStatusEntry[] {\n        return this.statusParser.parse(this.porcelainStatus(cwd));\n    }\n\n    // Untracked files only (respects .gitignore). Empty string = none.\n    untrackedFiles(cwd: string): string {\n        return this.gitQuery(['ls-files', '--others', '--exclude-standard'], cwd, 'Failed to list untracked files (git ls-files --others).');\n    }\n\n    /**\n     * Precondition for every PR/merge entry point: the working tree must be fully committed. The\n     * webpieces tooling deliberately does NOT `git add`/`commit` the developer's work for them. Aborts\n     * with instructions if anything is uncommitted (tracked or untracked, excluding gitignored).\n     */\n    assertCleanTree(cwd: string): void {\n        const dirty = this.porcelainStatus(cwd);\n        if (dirty === '') return;\n        throw new CliExitError(1,\n            '\\n' + SEP +\n            '❌ ERROR: You have uncommitted or untracked changes\\n' +\n            SEP + '\\n' +\n            'The webpieces PR tooling will NOT commit your work for you. Commit your\\n' +\n            'changes, and either commit or delete any untracked files, then re-run.\\n\\n' +\n            'Working tree (git status --porcelain):\\n' +\n            dirty + '\\n\\n' +\n            `See ${this.repoRootFinder.docPathFrom(cwd, GIT_WORKFLOW_DOC_NAME)} for the full merge + PR process.\\n` +\n            SEP,\n        );\n    }\n\n    /**\n     * Narrower guard for the merge-resolve commit point, where tracked resolutions are legitimately in\n     * the tree but untracked files must NOT be swept into the squash commit. Lists any untracked files\n     * and aborts so the AI commits or deletes them explicitly.\n     */\n    assertNoUntracked(cwd: string): void {\n        const untracked = this.untrackedFiles(cwd);\n        if (untracked === '') return;\n        throw new CliExitError(1,\n            '\\n' + SEP +\n            '❌ ERROR: Untracked files present during merge finalize\\n' +\n            SEP + '\\n' +\n            'The tooling will not sweep untracked files into the squash commit. Commit\\n' +\n            'or delete these, then re-run:\\n\\n' +\n            untracked + '\\n\\n' +\n            `See ${this.repoRootFinder.docPathFrom(cwd, GIT_WORKFLOW_DOC_NAME)} for the full merge + PR process.\\n` +\n            SEP,\n        );\n    }\n\n    /**\n     * Run a git command that is expected to succeed; abort the process with a clear message if it\n     * fails. Used for fetch/pull/checkout/commit where silently continuing on failure would operate on\n     * stale or wrong state.\n     */\n    runGitChecked(args: string[], errMsg: string): void {\n        const result = spawnSync('git', args, { stdio: 'inherit' });\n        if (result.status !== 0) {\n            throw new CliExitError(1, `❌ ${errMsg} (git ${args.join(' ')} exited ${String(result.status)})`);\n        }\n    }\n\n    /**\n     * Push HEAD to origin/<currentBranch>. Uses --force-with-lease for an existing remote branch (the\n     * 3-point squash rewrites history) and -u for a brand-new branch.\n     */\n    ensurePushed(currentBranch: string): void {\n        const remoteExists = spawnSync('git', ['ls-remote', '--exit-code', '--heads', 'origin', currentBranch]).status === 0;\n        if (remoteExists) {\n            this.runGitChecked(['push', '--force-with-lease', 'origin', `HEAD:${currentBranch}`], 'Failed to push branch');\n        } else {\n            this.runGitChecked(['push', '-u', 'origin', `HEAD:${currentBranch}`], 'Failed to push new branch');\n        }\n    }\n\n    // Run a read-only git query from the repo root; abort if git itself errors. Kept `cwd`-explicit\n    // because `git ls-files --others` is scoped to the cwd subtree.\n    private gitQuery(args: string[], cwd: string, failMsg: string): string {\n        return this.rawGitQuery(args, cwd, failMsg).trim();\n    }\n\n    // The untrimmed sibling — see porcelainStatus for why trimming is not always safe.\n    private rawGitQuery(args: string[], cwd: string, failMsg: string): string {\n        const out = spawnSync('git', args, { encoding: 'utf8', cwd });\n        if (out.status !== 0) {\n            throw new CliExitError(1, `❌ ${failMsg}`);\n        }\n        return out.stdout;\n    }\n}\n"]}
+{"version":3,"file":"git-exec.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/git-exec.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport { CliExitError, RepoRootFinder } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { GitStatusEntry, GitStatusParser } from './git-status';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n// The AI-facing doc the failure messages point at (generated under `.webpieces/instruct-ai`, at the\n// REPO ROOT — resolved absolute so the AI opens it regardless of the cwd it reads the message from).\nconst GIT_WORKFLOW_DOC_NAME = 'webpieces.git-workflow.md';\n\n/**\n * The result of a git command that was allowed to fail. Data-only (per CLAUDE.md) so a caller asks\n * `outcome.ok` rather than re-deriving \"did it work\" from a status number at every site.\n */\nexport class GitOutcome {\n    status: number;\n    stdout: string;\n    stderr: string;\n\n    constructor(status: number, stdout: string, stderr: string) {\n        this.status = status;\n        this.stdout = stdout;\n        this.stderr = stderr;\n    }\n\n    get ok(): boolean {\n        return this.status === 0;\n    }\n}\n\n/** Shared git precondition checks + push logic for the PR/merge workflow. */\n@injectable(bindingScopeValues.Singleton)\nexport class GitExec {\n    constructor(\n        private readonly repoRootFinder: RepoRootFinder,\n        private readonly statusParser: GitStatusParser,\n    ) {}\n\n    /**\n     * Raw `git status --porcelain` with ONLY the trailing newline(s) stripped — never `.trim()`.\n     *\n     * There used to be a trimmed sibling here (`uncommittedFiles`) and it was a data-destroying trap:\n     * porcelain column 1 is the index state and column 2 the worktree state, so an unstaged\n     * modification is \" M path\"; `trim()` eats that leading space and the line then reads \"M path\",\n     * i.e. STAGED — the exact inverse of the truth. It is deleted. This method is for EMPTINESS\n     * (\"is the tree dirty at all?\") and for PRINTING; anything that reasons about the two columns\n     * calls {@link statusEntries} and reads booleans instead of re-parsing a string.\n     *\n     * Tracked changes (staged + unstaged) AND untracked files, EXCLUDING gitignored paths — so\n     * `.webpieces/` tooling artifacts never count. Empty string = fully committed.\n     */\n    porcelainStatus(cwd: string): string {\n        return this.rawGitQuery(['status', '--porcelain'], cwd,\n            'Failed to run `git status --porcelain` to check the working tree.').replace(/\\n+$/, '');\n    }\n\n    /**\n     * The same status, PARSED: two status columns, an unquoted path, and explicit\n     * `isStaged()`/`isUnstaged()`/`isUntracked()` answers. Use this for every semantic question.\n     */\n    statusEntries(cwd: string): GitStatusEntry[] {\n        return this.statusParser.parse(this.porcelainStatus(cwd));\n    }\n\n    // Untracked files only (respects .gitignore). Empty string = none.\n    untrackedFiles(cwd: string): string {\n        return this.gitQuery(['ls-files', '--others', '--exclude-standard'], cwd, 'Failed to list untracked files (git ls-files --others).');\n    }\n\n    /**\n     * Precondition for every PR/merge entry point: the working tree must be fully committed. The\n     * webpieces tooling deliberately does NOT `git add`/`commit` the developer's work for them. Aborts\n     * with instructions if anything is uncommitted (tracked or untracked, excluding gitignored).\n     */\n    assertCleanTree(cwd: string): void {\n        const dirty = this.porcelainStatus(cwd);\n        if (dirty === '') return;\n        throw new CliExitError(1,\n            '\\n' + SEP +\n            '❌ ERROR: You have uncommitted or untracked changes\\n' +\n            SEP + '\\n' +\n            'The webpieces PR tooling will NOT commit your work for you. Commit your\\n' +\n            'changes, and either commit or delete any untracked files, then re-run.\\n\\n' +\n            'Working tree (git status --porcelain):\\n' +\n            dirty + '\\n\\n' +\n            `See ${this.repoRootFinder.docPathFrom(cwd, GIT_WORKFLOW_DOC_NAME)} for the full merge + PR process.\\n` +\n            SEP,\n        );\n    }\n\n    /**\n     * Narrower guard for the merge-resolve commit point, where tracked resolutions are legitimately in\n     * the tree but untracked files must NOT be swept into the squash commit. Lists any untracked files\n     * and aborts so the AI commits or deletes them explicitly.\n     */\n    assertNoUntracked(cwd: string): void {\n        const untracked = this.untrackedFiles(cwd);\n        if (untracked === '') return;\n        throw new CliExitError(1,\n            '\\n' + SEP +\n            '❌ ERROR: Untracked files present during merge finalize\\n' +\n            SEP + '\\n' +\n            'The tooling will not sweep untracked files into the squash commit. Commit\\n' +\n            'or delete these, then re-run:\\n\\n' +\n            untracked + '\\n\\n' +\n            `See ${this.repoRootFinder.docPathFrom(cwd, GIT_WORKFLOW_DOC_NAME)} for the full merge + PR process.\\n` +\n            SEP,\n        );\n    }\n\n    /**\n     * Run a git command that is expected to succeed; abort the process with a clear message if it\n     * fails. Used for fetch/pull/checkout/commit where silently continuing on failure would operate on\n     * stale or wrong state.\n     */\n    runGitChecked(args: string[], errMsg: string): void {\n        const result = spawnSync('git', args, { stdio: 'inherit' });\n        if (result.status !== 0) {\n            throw new CliExitError(1, `❌ ${errMsg} (git ${args.join(' ')} exited ${String(result.status)})`);\n        }\n    }\n\n    /**\n     * Push HEAD to origin/<currentBranch>. Uses --force-with-lease for an existing remote branch (the\n     * 3-point squash rewrites history) and -u for a brand-new branch.\n     */\n    ensurePushed(currentBranch: string): void {\n        const remoteExists = spawnSync('git', ['ls-remote', '--exit-code', '--heads', 'origin', currentBranch]).status === 0;\n        if (remoteExists) {\n            this.runGitChecked(['push', '--force-with-lease', 'origin', `HEAD:${currentBranch}`], 'Failed to push branch');\n        } else {\n            this.runGitChecked(['push', '-u', 'origin', `HEAD:${currentBranch}`], 'Failed to push new branch');\n        }\n    }\n\n    /**\n     * Run a git command that MAY legitimately fail and report the outcome instead of aborting — for the\n     * questions whose \"no\" is an answer rather than an error (does this remote ref exist? did this merge\n     * conflict?). Distinct from {@link runGitChecked}, which exists for the commands where continuing on\n     * failure would operate on wrong state.\n     */\n    tryGit(args: string[], cwd: string): GitOutcome {\n        const out = spawnSync('git', args, { encoding: 'utf8', cwd });\n        return new GitOutcome(out.status ?? 1, (out.stdout ?? '').trim(), (out.stderr ?? '').trim());\n    }\n\n    /** Read-only git query that MUST succeed, trimmed. Public sibling of the private raw form. */\n    gitQuery(args: string[], cwd: string, failMsg: string): string {\n        return this.rawGitQuery(args, cwd, failMsg).trim();\n    }\n\n    // The untrimmed sibling — see porcelainStatus for why trimming is not always safe.\n    private rawGitQuery(args: string[], cwd: string, failMsg: string): string {\n        const out = spawnSync('git', args, { encoding: 'utf8', cwd });\n        if (out.status !== 0) {\n            throw new CliExitError(1, `❌ ${failMsg}`);\n        }\n        return out.stdout;\n    }\n}\n"]}

package/src/scripts/workflow/push-dev-state.d.ts

@@ -0,0 +1,52 @@
+import { DotWebpieces } from '@webpieces/rules-config';
+/**
+ * The persisted half of the `wp-push-dev --resolve` state machine.
+ *
+ * A single-shot wrapper is IMPOSSIBLE here and that is why this file exists: `git merge` halts on
+ * conflict with markers in the working tree and a non-zero exit, and a human or an AI has to edit files
+ * before anything can be committed. So the command must be able to stop, hand the tree over, and be
+ * resumed by a second command that knows exactly where it left off.
+ *
+ * Data-only (per CLAUDE.md) — the behaviour lives in {@link PushDevStateStore}.
+ */
+export declare class PushDevState {
+    /** The branch to return to when the resolve finishes or aborts. NEVER written to by this flow. */
+    originalBranch: string;
+    /** The local throwaway branch the merges happen on. Deleted on finish and on abort. */
+    tmpBranch: string;
+    /** `<namespace>/<originalBranch>` — the remote copy this resolve republishes. */
+    targetRef: string;
+    /** The copy refs still to merge, in the order CI composes them. */
+    queue: string[];
+    /** The ref currently mid-merge (conflicted), or '' when nothing is halted. */
+    current: string;
+    constructor(originalBranch: string, tmpBranch: string, targetRef: string, queue: string[], current?: string);
+}
+/**
+ * Reads, writes and clears the resolve state file, and refuses the other `wp-*` commands while it
+ * exists.
+ *
+ * LOCAL scope, deliberately: a resolve halts one worktree's checkout on a throwaway branch, and another
+ * worktree has no reason to care. Sharing it would block a colleague's PR flow on state that says
+ * nothing about their tree.
+ */
+export declare class PushDevStateStore {
+    private readonly dotWebpieces;
+    constructor(dotWebpieces: DotWebpieces);
+    path(repoRoot: string): string;
+    exists(repoRoot: string): boolean;
+    /** The in-flight resolve, or null when none is. A corrupt file reads as null rather than crashing. */
+    read(repoRoot: string): PushDevState | null;
+    write(repoRoot: string, state: PushDevState): void;
+    clear(repoRoot: string): void;
+    /** The read that MUST find a resolve — used by `wp-finish-push-dev`, whose whole job is resuming one. */
+    require(repoRoot: string): PushDevState;
+    /**
+     * Refuse `attempted` while a resolve is half-finished. Called from the app root for every command in
+     * {@link BLOCKED_DURING_RESOLVE}, so no individual command has to remember to ask.
+     */
+    assertIdle(repoRoot: string, attempted: string): void;
+    private blockedCommandList;
+    /** Is `command` one of the ones that must refuse mid-resolve? Used by the app root. */
+    isBlockedDuringResolve(command: string): boolean;
+}

package/src/scripts/workflow/push-dev-state.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PushDevStateStore = exports.PushDevState = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const rules_config_1 = require("@webpieces/rules-config");
+const inversify_1 = require("inversify");
+const SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
+/**
+ * The persisted half of the `wp-push-dev --resolve` state machine.
+ *
+ * A single-shot wrapper is IMPOSSIBLE here and that is why this file exists: `git merge` halts on
+ * conflict with markers in the working tree and a non-zero exit, and a human or an AI has to edit files
+ * before anything can be committed. So the command must be able to stop, hand the tree over, and be
+ * resumed by a second command that knows exactly where it left off.
+ *
+ * Data-only (per CLAUDE.md) — the behaviour lives in {@link PushDevStateStore}.
+ */
+class PushDevState {
+    /** The branch to return to when the resolve finishes or aborts. NEVER written to by this flow. */
+    originalBranch;
+    /** The local throwaway branch the merges happen on. Deleted on finish and on abort. */
+    tmpBranch;
+    /** `<namespace>/<originalBranch>` — the remote copy this resolve republishes. */
+    targetRef;
+    /** The copy refs still to merge, in the order CI composes them. */
+    queue;
+    /** The ref currently mid-merge (conflicted), or '' when nothing is halted. */
+    current;
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(originalBranch, tmpBranch, targetRef, queue, current = '') {
+        this.originalBranch = originalBranch;
+        this.tmpBranch = tmpBranch;
+        this.targetRef = targetRef;
+        this.queue = queue;
+        this.current = current;
+    }
+}
+exports.PushDevState = PushDevState;
+// The wp-* commands that must REFUSE while a resolve is half-finished, and the ONE place that list is
+// written. The blocked-list sentence below RENDERS ITSELF from this array — the same lesson
+// merge-in-progress-guard already learned the hard way: a hand-written "don't run other commands"
+// survives every edit to the actual enforcement and ends up forbidding things the flow requires.
+//
+// Why these and not everything: each one either rewrites the current branch (the two starts), pushes it
+// (the finishes), or deletes branches (cleanup) — and during a resolve the checkout is a throwaway
+// branch, not the feature branch any of them think they are acting on.
+const BLOCKED_DURING_RESOLVE = [
+    'wp-start-update', 'wp-finish-update',
+    'wp-start-upsert-pr', 'wp-review-upsert-pr', 'wp-finish-upsert-pr',
+    'wp-land-pr', 'wp-cleanup',
+];
+/**
+ * Reads, writes and clears the resolve state file, and refuses the other `wp-*` commands while it
+ * exists.
+ *
+ * LOCAL scope, deliberately: a resolve halts one worktree's checkout on a throwaway branch, and another
+ * worktree has no reason to care. Sharing it would block a colleague's PR flow on state that says
+ * nothing about their tree.
+ */
+let PushDevStateStore = class PushDevStateStore {
+    dotWebpieces;
+    constructor(dotWebpieces) {
+        this.dotWebpieces = dotWebpieces;
+    }
+    path(repoRoot) {
+        return this.dotWebpieces.localFile(repoRoot, rules_config_1.PUSH_DEV_STATE_FILE);
+    }
+    exists(repoRoot) {
+        return fs.existsSync(this.path(repoRoot));
+    }
+    /** The in-flight resolve, or null when none is. A corrupt file reads as null rather than crashing. */
+    read(repoRoot) {
+        const file = this.path(repoRoot);
+        if (!fs.existsSync(file))
+            return null;
+        // webpieces-disable no-unmanaged-exceptions -- a truncated/hand-edited state file must degrade to "no resolve in progress" (recoverable via --abort or a fresh --resolve), never crash every wp-* command in the tree
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            // webpieces-disable no-any-unknown -- JSON.parse is untyped until narrowed on the next line
+            const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (typeof raw.originalBranch !== 'string' || typeof raw.tmpBranch !== 'string')
+                return null;
+            return new PushDevState(raw.originalBranch, raw.tmpBranch, raw.targetRef ?? '', Array.isArray(raw.queue) ? raw.queue : [], raw.current ?? '');
+            // The parse error carries nothing a caller could act on: the ONLY meaningful reading of an
+            // unparseable state file is "no resolve in progress", which --abort and a fresh --resolve both
+            // recover from.
+        }
+        catch (err) {
+            const error = (0, rules_config_1.toError)(err);
+            void error;
+            return null;
+        }
+    }
+    write(repoRoot, state) {
+        fs.mkdirSync(this.dotWebpieces.local(repoRoot), { recursive: true });
+        fs.writeFileSync(this.path(repoRoot), JSON.stringify(state, null, 2) + '\n', 'utf8');
+    }
+    clear(repoRoot) {
+        const file = this.path(repoRoot);
+        if (fs.existsSync(file))
+            fs.rmSync(file);
+    }
+    /** The read that MUST find a resolve — used by `wp-finish-push-dev`, whose whole job is resuming one. */
+    require(repoRoot) {
+        const state = this.read(repoRoot);
+        if (state !== null)
+            return state;
+        throw new rules_config_1.CliExitError(2, '\n' + SEP + '⛔ No dev-deploy resolve is in progress\n' + SEP + '\n'
+            + `${rules_config_1.WP_FINISH_PUSH_DEV} resumes a resolve that \`${rules_config_1.WP_PUSH_DEV} --resolve\` started, and there is no\n`
+            + `state file at:\n  ${this.path(repoRoot)}\n\n`
+            + 'If you meant to publish your branch to the shared dev server, that is the one-command form:\n'
+            + `  ${rules_config_1.WP_PUSH_DEV}\n`);
+    }
+    /**
+     * Refuse `attempted` while a resolve is half-finished. Called from the app root for every command in
+     * {@link BLOCKED_DURING_RESOLVE}, so no individual command has to remember to ask.
+     */
+    assertIdle(repoRoot, attempted) {
+        const state = this.read(repoRoot);
+        if (state === null)
+            return;
+        throw new rules_config_1.CliExitError(2, '\n' + SEP + `⛔ A dev-deploy resolve is in progress — \`pnpm ${attempted}\` is blocked\n` + SEP + '\n'
+            + `You are standing on the throwaway branch \`${state.tmpBranch}\`, not on \`${state.originalBranch}\`,\n`
+            + `so ${this.blockedCommandList()} would all act on the wrong branch.\n`
+            + 'That is the whole list; nothing else is blocked.\n\n'
+            + 'EXPECTED of you right now, and NOT blocked: read the conflicted files and edit them until every\n'
+            + 'conflict marker is gone. Then finish or bail out:\n'
+            + `  ${rules_config_1.WP_FINISH_PUSH_DEV}            ← commit the resolution, resume the queue, publish the copy\n`
+            + `  ${rules_config_1.WP_FINISH_PUSH_DEV} --abort    ← throw the resolution away and go back to \`${state.originalBranch}\`\n\n`
+            + `State file: ${this.path(repoRoot)}\n`);
+    }
+    // Rendered from BLOCKED_DURING_RESOLVE, never hand-written — see that constant.
+    blockedCommandList() {
+        return BLOCKED_DURING_RESOLVE.map((c) => `\`pnpm ${c}\``).join(', ');
+    }
+    /** Is `command` one of the ones that must refuse mid-resolve? Used by the app root. */
+    isBlockedDuringResolve(command) {
+        return BLOCKED_DURING_RESOLVE.includes(command);
+    }
+};
+exports.PushDevStateStore = PushDevStateStore;
+exports.PushDevStateStore = PushDevStateStore = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [rules_config_1.DotWebpieces])
+], PushDevStateStore);
+//# sourceMappingURL=push-dev-state.js.map

package/src/scripts/workflow/push-dev-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-dev-state.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/push-dev-state.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\n\nimport {\n    CliExitError,\n    DotWebpieces,\n    PUSH_DEV_STATE_FILE,\n    WP_FINISH_PUSH_DEV,\n    WP_PUSH_DEV,\n    toError,\n} from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/**\n * The persisted half of the `wp-push-dev --resolve` state machine.\n *\n * A single-shot wrapper is IMPOSSIBLE here and that is why this file exists: `git merge` halts on\n * conflict with markers in the working tree and a non-zero exit, and a human or an AI has to edit files\n * before anything can be committed. So the command must be able to stop, hand the tree over, and be\n * resumed by a second command that knows exactly where it left off.\n *\n * Data-only (per CLAUDE.md) — the behaviour lives in {@link PushDevStateStore}.\n */\nexport class PushDevState {\n    /** The branch to return to when the resolve finishes or aborts. NEVER written to by this flow. */\n    originalBranch: string;\n    /** The local throwaway branch the merges happen on. Deleted on finish and on abort. */\n    tmpBranch: string;\n    /** `<namespace>/<originalBranch>` — the remote copy this resolve republishes. */\n    targetRef: string;\n    /** The copy refs still to merge, in the order CI composes them. */\n    queue: string[];\n    /** The ref currently mid-merge (conflicted), or '' when nothing is halted. */\n    current: string;\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(originalBranch: string, tmpBranch: string, targetRef: string, queue: string[], current = '') {\n        this.originalBranch = originalBranch;\n        this.tmpBranch = tmpBranch;\n        this.targetRef = targetRef;\n        this.queue = queue;\n        this.current = current;\n    }\n}\n\n// The wp-* commands that must REFUSE while a resolve is half-finished, and the ONE place that list is\n// written. The blocked-list sentence below RENDERS ITSELF from this array — the same lesson\n// merge-in-progress-guard already learned the hard way: a hand-written \"don't run other commands\"\n// survives every edit to the actual enforcement and ends up forbidding things the flow requires.\n//\n// Why these and not everything: each one either rewrites the current branch (the two starts), pushes it\n// (the finishes), or deletes branches (cleanup) — and during a resolve the checkout is a throwaway\n// branch, not the feature branch any of them think they are acting on.\nconst BLOCKED_DURING_RESOLVE: readonly string[] = [\n    'wp-start-update', 'wp-finish-update',\n    'wp-start-upsert-pr', 'wp-review-upsert-pr', 'wp-finish-upsert-pr',\n    'wp-land-pr', 'wp-cleanup',\n];\n\n/**\n * Reads, writes and clears the resolve state file, and refuses the other `wp-*` commands while it\n * exists.\n *\n * LOCAL scope, deliberately: a resolve halts one worktree's checkout on a throwaway branch, and another\n * worktree has no reason to care. Sharing it would block a colleague's PR flow on state that says\n * nothing about their tree.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class PushDevStateStore {\n    constructor(private readonly dotWebpieces: DotWebpieces) {}\n\n    path(repoRoot: string): string {\n        return this.dotWebpieces.localFile(repoRoot, PUSH_DEV_STATE_FILE);\n    }\n\n    exists(repoRoot: string): boolean {\n        return fs.existsSync(this.path(repoRoot));\n    }\n\n    /** The in-flight resolve, or null when none is. A corrupt file reads as null rather than crashing. */\n    read(repoRoot: string): PushDevState | null {\n        const file = this.path(repoRoot);\n        if (!fs.existsSync(file)) return null;\n        // webpieces-disable no-unmanaged-exceptions -- a truncated/hand-edited state file must degrade to \"no resolve in progress\" (recoverable via --abort or a fresh --resolve), never crash every wp-* command in the tree\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            // webpieces-disable no-any-unknown -- JSON.parse is untyped until narrowed on the next line\n            const raw = JSON.parse(fs.readFileSync(file, 'utf8')) as Partial<PushDevState>;\n            if (typeof raw.originalBranch !== 'string' || typeof raw.tmpBranch !== 'string') return null;\n            return new PushDevState(\n                raw.originalBranch, raw.tmpBranch, raw.targetRef ?? '',\n                Array.isArray(raw.queue) ? raw.queue : [], raw.current ?? '');\n        // The parse error carries nothing a caller could act on: the ONLY meaningful reading of an\n        // unparseable state file is \"no resolve in progress\", which --abort and a fresh --resolve both\n        // recover from.\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n\n    write(repoRoot: string, state: PushDevState): void {\n        fs.mkdirSync(this.dotWebpieces.local(repoRoot), { recursive: true });\n        fs.writeFileSync(this.path(repoRoot), JSON.stringify(state, null, 2) + '\\n', 'utf8');\n    }\n\n    clear(repoRoot: string): void {\n        const file = this.path(repoRoot);\n        if (fs.existsSync(file)) fs.rmSync(file);\n    }\n\n    /** The read that MUST find a resolve — used by `wp-finish-push-dev`, whose whole job is resuming one. */\n    require(repoRoot: string): PushDevState {\n        const state = this.read(repoRoot);\n        if (state !== null) return state;\n        throw new CliExitError(2,\n            '\\n' + SEP + '⛔ No dev-deploy resolve is in progress\\n' + SEP + '\\n'\n            + `${WP_FINISH_PUSH_DEV} resumes a resolve that \\`${WP_PUSH_DEV} --resolve\\` started, and there is no\\n`\n            + `state file at:\\n  ${this.path(repoRoot)}\\n\\n`\n            + 'If you meant to publish your branch to the shared dev server, that is the one-command form:\\n'\n            + `  ${WP_PUSH_DEV}\\n`);\n    }\n\n    /**\n     * Refuse `attempted` while a resolve is half-finished. Called from the app root for every command in\n     * {@link BLOCKED_DURING_RESOLVE}, so no individual command has to remember to ask.\n     */\n    assertIdle(repoRoot: string, attempted: string): void {\n        const state = this.read(repoRoot);\n        if (state === null) return;\n        throw new CliExitError(2,\n            '\\n' + SEP + `⛔ A dev-deploy resolve is in progress — \\`pnpm ${attempted}\\` is blocked\\n` + SEP + '\\n'\n            + `You are standing on the throwaway branch \\`${state.tmpBranch}\\`, not on \\`${state.originalBranch}\\`,\\n`\n            + `so ${this.blockedCommandList()} would all act on the wrong branch.\\n`\n            + 'That is the whole list; nothing else is blocked.\\n\\n'\n            + 'EXPECTED of you right now, and NOT blocked: read the conflicted files and edit them until every\\n'\n            + 'conflict marker is gone. Then finish or bail out:\\n'\n            + `  ${WP_FINISH_PUSH_DEV}            ← commit the resolution, resume the queue, publish the copy\\n`\n            + `  ${WP_FINISH_PUSH_DEV} --abort    ← throw the resolution away and go back to \\`${state.originalBranch}\\`\\n\\n`\n            + `State file: ${this.path(repoRoot)}\\n`);\n    }\n\n    // Rendered from BLOCKED_DURING_RESOLVE, never hand-written — see that constant.\n    private blockedCommandList(): string {\n        return BLOCKED_DURING_RESOLVE.map((c: string): string => `\\`pnpm ${c}\\``).join(', ');\n    }\n\n    /** Is `command` one of the ones that must refuse mid-resolve? Used by the app root. */\n    isBlockedDuringResolve(command: string): boolean {\n        return BLOCKED_DURING_RESOLVE.includes(command);\n    }\n}\n"]}

package/src/scripts/workflow/review-report.d.ts

@@ -33,6 +33,12 @@ export declare class ReviewReportInput {
     formatErrors: string[];
     briefings: ReviewerBriefing[];
     refused: RefusedReviewer[];
+    /**
+     * `--no-optional` was passed: the human has already said to submit without the optional reviews, so the
+     * block that offers them is replaced by a one-line statement that they were skipped. It never suppresses
+     * a REQUIRED reviewer, and it is not a gate — nothing about what blocks the PR changes.
+     */
+    skipOptional: boolean;
     constructor(repoRoot: string, featureName: string, reviewPath: string);
 }
 /**
@@ -50,6 +56,9 @@ export declare class ReviewReportInput {
  *   1. `wp-finish-upsert-pr` is named as a thing to run EXACTLY ONCE in the whole block.
  *   2. The review.json instruction comes BEFORE it — and BEFORE the spawn blocks (see nextSteps).
  *   3. With zero checklists the all-clear precedes any configuration guidance.
+ *   4. REQUIRED reviewers are spawned unasked; OPTIONAL ones are only ever OFFERED, in one batched
+ *      question. The two never share a step, because one instruction says "do it" and the other says
+ *      "ask first", and an agent reading a merged list will act on the stronger of the two.
  *
  * Pure string building, no I/O. `@injectable(bindingScopeValues.Singleton)` so it is injected by type.
  */
@@ -58,6 +67,17 @@ export declare class ReviewReport {
     private readonly reviewerInstructions;
     constructor(checklistNotice: ChecklistNotice, reviewerInstructions: ReviewerInstructionsService);
     render(input: ReviewReportInput): string;
+    /**
+     * Name what this block is actually about. A repo with reviewers owed is being told to SPAWN; a repo with
+     * none is not, and promising subagents it does not have is the same kind of noise as explaining checklist
+     * configuration to a repo that configured none. Keyed on what is actually ACTIONABLE rather than on the
+     * applicable count: every applicable checklist already having a verdict means nothing to spawn, and so
+     * does a branch whose only outstanding reviews are optional ones the human already waved off.
+     *
+     * "spawn" and "ask about" are separate headings because they are separate obligations. A branch owing
+     * only optional reviews has nothing the AI may do unilaterally, and a heading that says SPAWN is the
+     * single line most likely to make it do exactly that.
+     */
     private header;
     /**
      * What the SCAN found: either "nothing applies here" or the already-reviewed / unreadable-verdict lines.
@@ -65,6 +85,13 @@ export declare class ReviewReport {
      * mistaken for the next action.
      */
     private scanVerdict;
+    /**
+     * `--no-optional`, stated as a VERDICT rather than left silent. Named individually, not just counted: the
+     * whole reason the human is allowed to skip these is that they know this diff, and the only way they can
+     * catch "wait, not THAT one" is to see which ones went unreviewed.
+     */
+    private skippedLines;
+    private allClear;
     /**
      * The ONE instruction block, and the last thing the stage prints. Numbered rather than prose-linked
      * ("Then… Finally…") so that skipping step 1 is visibly skipping a step, and worded so no earlier line
@@ -88,14 +115,40 @@ export declare class ReviewReport {
     private nextSteps;
     private writeReviewStep;
     /**
-     * STEP 2 — one copy-paste block per owed reviewer, and nothing at all when none is owed. The prompt is
+     * The REQUIRED reviewers — one copy-paste block each, and nothing at all when none is owed. The prompt is
      * deliberately a POINTER and nothing else: the generated instructions file is the contract, so anything
      * restated here is a second copy that can go stale — which is exactly how a removed `success` field
      * outlived its own removal in print.
+     *
+     * These are spawned WITHOUT asking. They are the checklists the repo declared `required: true`, which is
+     * the repo saying the decision was already made; putting them to the human again would re-open a question
+     * the config exists to settle.
      */
     private spawnStep;
+    /**
+     * STEP n — the OPTIONAL reviewers: listed, never spawned unasked.
+     *
+     * This is the whole point of `required: false`. A one-line bug fix in a repo whose checklists key on a
+     * glob as broad as every TypeScript file otherwise pays for a dozen subagent reviews, and the only party
+     * who can judge whether this particular diff is worth them is the human looking at it.
+     *
+     * ONE batched multi-select question, explicitly. Asked one at a time, a human answering "no" nine times
+     * is being worn down rather than consulted, and by the third question the cheap thing is to say yes to
+     * everything — which is the state this feature exists to leave. The "None" option has to be spelled out
+     * too: an agent that offers a list without an explicit way to decline it has not really offered a choice.
+     *
+     * The blocking consequence is stated because it is the one non-obvious part of the contract: `required`
+     * governs whether a reviewer must RUN, not whether its answer counts. Choosing to run one and then
+     * shrugging off a red verdict would make the whole exercise theater.
+     */
+    private offerStep;
+    private refusedWarning;
     private finishStep;
     private owedReviewers;
+    private requiredOwed;
+    private optionalOwed;
+    private offerableOwed;
+    private actionableOwed;
     /**
      * One reviewer's block. A reviewer that already REFUSED gets the SAME spawn coordinates but a different
      * lead-in, because the action before spawning is different: its own words are printed, and the spawn is
@@ -108,5 +161,13 @@ export declare class ReviewReport {
      */
     private oneSpawnBlock;
     private leadIn;
+    /**
+     * The checklist's guidance doc, for OPTIONAL reviewers only.
+     *
+     * "4 file(s) matched" plus a broad glob does not tell a human what the review would actually look AT,
+     * and they are being asked to decide exactly that. Omitted for required reviewers: there is no decision
+     * to inform there — the reviewer runs either way, and the doc is already in its instructions file.
+     */
+    private docLine;
     private why;
 }