@webpieces/ai-hook-rules 0.4.420 → 0.4.422

package/src/core/rules/feature-branch-guard.js

@@ -10,6 +10,7 @@ const to_error_1 = require("../to-error");
 const main_sync_refresh_1 = require("../main-sync-refresh");
 const decision_log_1 = require("../decision-log");
 const merged_branch_message_1 = require("./merged-branch-message");
+const tree_recovery_1 = require("./tree-recovery");
 /**
  * Comprehensive "are you on a proper feature branch?" guard — the single rule that blocks edits when
  * the branch isn't a healthy place to work. Four states, in priority order:
@@ -64,7 +65,8 @@ class FeatureBranchGuardRule extends rule_base_1.FileRuleBase {
         // State 2: this feature branch was already merged into main.
         if (status.branchAlreadyMerged) {
             const pr = status.mergedPr !== '' ? status.mergedPr : '?';
-            return this.block(ctx, branch, `already-merged PR#${pr}`, this.alreadyMergedMessage(branch, status.mergedPr), cache);
+            const merged = this.alreadyMergedMessage(ctx.workspaceRoot, branch, status.mergedPr);
+            return this.block(ctx, branch, `already-merged PR#${pr}`, merged, cache);
         }
         // State 3: no fork point — main was merged into the branch.
         if (!status.hasForkPoint) {
@@ -121,8 +123,10 @@ class FeatureBranchGuardRule extends rule_base_1.FileRuleBase {
         ].join('\n');
     }
     // Shared with read-stale-guard, which blocks READS in this same state — see MergedBranchMessage.
-    alreadyMergedMessage(branch, mergedPr) {
-        return new merged_branch_message_1.MergedBranchMessage().forEdits(branch, mergedPr);
+    // The tree kind picks the flavour of the cure: a dead LINKED WORKTREE is told to open a new
+    // worktree off origin/main and reap this one; the primary clone is told to branch off origin/main.
+    alreadyMergedMessage(workspaceRoot, branch, mergedPr) {
+        return new merged_branch_message_1.MergedBranchMessage().forEdits(branch, mergedPr, new tree_recovery_1.TreeRecovery().kindOf(workspaceRoot), workspaceRoot);
     }
     conflictMessage(conflictFiles, openPr) {
         const files = conflictFiles.length > 0

package/src/core/rules/feature-branch-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"feature-branch-guard.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/feature-branch-guard.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync } from 'child_process';\n\nimport {\n    FeatureBranchGuardConfig,\n    DEFAULT_HANG_TIMEOUT_MINUTES,\n    readMainSyncStatus,\n    squashRecoverySteps,\n    MainSyncStatus,\n} from '@webpieces/rules-config';\n\nimport type { FileContext, Violation } from '../types';\nimport { Violation as V } from '../types';\nimport { FileRuleBase } from '../rule-base';\nimport { FixHint, Option } from '../fix-hint';\nimport { toError } from '../to-error';\nimport { triggerMainSyncRefresh } from '../main-sync-refresh';\nimport { logGuardDecision, GuardDecision } from '../decision-log';\nimport { MergedBranchMessage } from './merged-branch-message';\n\n/**\n * Comprehensive \"are you on a proper feature branch?\" guard — the single rule that blocks edits when\n * the branch isn't a healthy place to work. Four states, in priority order:\n *   1. On main (checked SYNCHRONOUSLY here)          → block: create a feature branch.\n *   2. Branch already merged into main (merged PR)   → block: your work is in main, branch off fresh.\n *   3. No fork point with origin/main                → block: squash onto a new branch.\n *   4. origin/main moved & touches your files        → block: merge main first.\n * States 2–4 are PRECOMPUTED into `.webpieces/main-sync-status.json` by the detached refresher, so\n * this check does NO network git (only a fast local `git rev-parse` for state 1). On every call it\n * fire-and-forget spawns the refresher so the NEXT call is fresh. Runs in the GUARDS hook (it's a\n * hookGuard); file-scoped, so only Write/Edit/MultiEdit are guarded — Bash passes through so the AI\n * can still run `pnpm wp-start-upsert-pr` and the rest of the recovery flow.\n */\nexport class FeatureBranchGuardRule extends FileRuleBase<FeatureBranchGuardConfig> {\n    constructor(config: FeatureBranchGuardConfig) { super(config, 'feature-branch-guard'); }\n\n    readonly description = 'Block edits unless you are on a proper feature branch (not main, not already-merged, forked, in sync with main).';\n    override readonly files = ['**/*'];\n    override readonly defaultOptions = {\n        branchNamingConvention: '{whoami}/{featurename}',\n        hangTimeoutMinutes: DEFAULT_HANG_TIMEOUT_MINUTES,\n    };\n    readonly fixHint = new FixHint(\n        'You are not on a clean, up-to-date feature branch.',\n        'You must be on a clean, up-to-date feature branch to edit code. Pick one:',\n        [\n            new Option('On main → create a feature branch. Already merged → branch off fresh main.', true),\n            new Option('main moved/conflicts (mid-work) → `pnpm wp-start-update` (merge), `/wp-merge` (resolve), `pnpm wp-finish-update`. Have an OPEN PR? use `pnpm wp-start-upsert-pr` → `/wp-merge` → `pnpm wp-finish-upsert-pr`.'),\n            new Option('Disable in webpieces.config.json under feature-branch-guard (mode OFF) if intentional.'),\n        ],\n    );\n\n    check(ctx: FileContext): readonly Violation[] {\n        // Only files inside the workspace root — guard has no jurisdiction, nothing worth logging.\n        if (ctx.relativePath.startsWith('..')) return [];\n\n        const branch = this.currentBranch(ctx.workspaceRoot);\n        // Can't determine branch (e.g. not a git repo) → don't block. Fail-open.\n        if (branch === null) return this.allow(ctx, branch, 'branch-undeterminable (fail-open)');\n\n        // State 1: on main — synchronous, no cache needed.\n        if (branch === 'main') {\n            return this.block(ctx, branch, 'on-main', this.onMainMessage());\n        }\n\n        // Keep the cache warm for the next call. Detached; never blocks this edit.\n        triggerMainSyncRefresh(ctx.workspaceRoot, this.config.hangTimeoutMinutes ?? DEFAULT_HANG_TIMEOUT_MINUTES);\n\n        const status = readMainSyncStatus(ctx.workspaceRoot);\n        // No cache yet (first edit of the session) → allow; the refresh we just spawned populates it\n        // for the next call. Fail-open: never block on missing data.\n        if (status === null) return this.allow(ctx, branch, 'no-sync-cache (fail-open)', 'cache=none');\n\n        const cache = this.cacheSummary(status);\n        // Stale cross-branch cache: the cached status is for a DIFFERENT branch (e.g. you just\n        // switched branches and the refresh for this one hasn't landed yet). Never block on another\n        // branch's signals — fail open; the refresh we just spawned rewrites it for this branch.\n        if (status.branch !== branch) return this.allow(ctx, branch, 'stale-cross-branch-cache (fail-open)', cache);\n\n        // State 2: this feature branch was already merged into main.\n        if (status.branchAlreadyMerged) {\n            const pr = status.mergedPr !== '' ? status.mergedPr : '?';\n            return this.block(ctx, branch, `already-merged PR#${pr}`, this.alreadyMergedMessage(branch, status.mergedPr), cache);\n        }\n        // State 3: no fork point — main was merged into the branch.\n        if (!status.hasForkPoint) {\n            return this.block(ctx, branch, 'no-fork-point', this.noForkPointMessage(branch), cache);\n        }\n        // State 4: origin/main moved and touches files you changed.\n        if (status.conflict) {\n            return this.block(ctx, branch, 'main-moved-conflict', this.conflictMessage(status.conflictFiles, status.openPr), cache);\n        }\n        return this.allow(ctx, branch, 'clean-feature-branch', cache);\n    }\n\n    // One-line summary of the async-written cache that drove this decision, for the SYNC log — so a\n    // wrong allow/block is traceable to the exact (possibly stale) main-sync-status.json read.\n    private cacheSummary(status: MainSyncStatus): string {\n        const merged = status.branchAlreadyMerged ? `PR#${status.mergedPr !== '' ? status.mergedPr : '?'}` : 'no';\n        return `cache=${status.branch} merged=${merged} fork=${String(status.hasForkPoint)} conflict=${String(status.conflict)} ts=${status.timestamp}`;\n    }\n\n    // Log + return for the allow path. Centralizes the decision-log call so every exit of check()\n    // is recorded with its reason + the async cache it read (this is the audit trail for \"why didn't\n    // the guard fire?\"). `cache` is the summary of the main-sync-status.json that drove the decision.\n    private allow(ctx: FileContext, branch: string | null, reason: string, cache: string = '-'): readonly Violation[] {\n        this.logDecision(ctx, branch, 'ALLOW', reason, cache);\n        return [];\n    }\n\n    private block(ctx: FileContext, branch: string, reason: string, message: string, cache: string = '-'): readonly Violation[] {\n        this.logDecision(ctx, branch, 'BLOCK', reason, cache);\n        return [new V(1, ctx.relativePath, message)];\n    }\n\n    private logDecision(ctx: FileContext, branch: string | null, verdict: 'ALLOW' | 'BLOCK', reason: string, cache: string): void {\n        logGuardDecision(\n            ctx.workspaceRoot,\n            new GuardDecision('feature-branch-guard', ctx.tool, ctx.relativePath, branch ?? 'unknown', verdict, reason, cache),\n        );\n    }\n\n    private currentBranch(workspaceRoot: string): string | null {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return execSync('git rev-parse --abbrev-ref HEAD', {\n                cwd: workspaceRoot,\n                encoding: 'utf8',\n                stdio: ['pipe', 'pipe', 'pipe'],\n            }).trim();\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n\n    private onMainMessage(): string {\n        const convention = this.config.branchNamingConvention ?? '{whoami}/{featurename}';\n        return [\n            'You should not be working on main.',\n            'Do a `git pull origin main` to get latest, then create a feature branch based on the naming convention.',\n            `Branch naming convention (from webpieces.config.json): ${convention}`,\n            'Example: git checkout -b ' + convention.replace(/<[^>]+>/g, 'value'),\n        ].join('\\n');\n    }\n\n    // Shared with read-stale-guard, which blocks READS in this same state — see MergedBranchMessage.\n    private alreadyMergedMessage(branch: string, mergedPr: string): string {\n        return new MergedBranchMessage().forEdits(branch, mergedPr);\n    }\n\n    private conflictMessage(conflictFiles: readonly string[], openPr: string): string {\n        const files = conflictFiles.length > 0\n            ? conflictFiles.map((f: string): string => `  - ${f}`).join('\\n')\n            : '  (see git diff)';\n        const header = [\n            'origin/main moved and touched files you also changed since your fork point:',\n            files,\n            '',\n        ];\n        // Steer EARLY: if a PR already tracks this branch, the update-only flow would just fail-fast\n        // (a 3-point update strands the PR on the old branch generation), so recommend ONLY the PR\n        // flow and don't waste the AI's tokens on wp-start-update.\n        if (openPr !== '') {\n            return header.concat([\n                `An OPEN PR (#${openPr}) already tracks this branch, so you MUST use the PR flow (it`,\n                're-merges main AND updates the PR — the update-only flow would strand the PR on the',\n                'old branch generation):',\n                '  1. pnpm wp-start-upsert-pr   ← merges main + writes 3-point context',\n                '  2. /wp-merge                 ← resolve each conflicted file (only if conflicts)',\n                '  3. pnpm wp-finish-upsert-pr  ← validate, build, push, upsert the PR',\n            ]).join('\\n');\n        }\n        return header.concat([\n            'You must merge main in before editing further. If you are mid-work and just want to keep',\n            'editing (no PR yet), use the UPDATE-ONLY flow:',\n            '  1. pnpm wp-start-update   ← merges main (auto-finalizes if clean; renames <branch>wpN → wpN+1)',\n            '  2. /wp-merge              ← resolve each conflicted file (only if there are conflicts)',\n            '  3. pnpm wp-finish-update  ← finalize the merge (only after resolving)',\n            '',\n            'If you already have an OPEN PR for this branch, use the PR flow instead (wp-start-update',\n            'refuses when a PR exists — it would strand the PR on the old branch generation):',\n            '  1. pnpm wp-start-upsert-pr   ← merges main + writes 3-point context',\n            '  2. /wp-merge                 ← resolve each conflicted file',\n            '  3. pnpm wp-finish-upsert-pr  ← validate, build, push, upsert the PR',\n        ]).join('\\n');\n    }\n\n    private noForkPointMessage(branch: string): string {\n        return [\n            'No fork point with origin/main — main appears to have been merged into this branch,',\n            'so a clean squash-merge is impossible. A human must redo the work on a fresh branch:',\n            '',\n            ...squashRecoverySteps(branch),\n        ].join('\\n');\n    }\n}\n"]}
+{"version":3,"file":"feature-branch-guard.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/feature-branch-guard.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync } from 'child_process';\n\nimport {\n    FeatureBranchGuardConfig,\n    DEFAULT_HANG_TIMEOUT_MINUTES,\n    readMainSyncStatus,\n    squashRecoverySteps,\n    MainSyncStatus,\n} from '@webpieces/rules-config';\n\nimport type { FileContext, Violation } from '../types';\nimport { Violation as V } from '../types';\nimport { FileRuleBase } from '../rule-base';\nimport { FixHint, Option } from '../fix-hint';\nimport { toError } from '../to-error';\nimport { triggerMainSyncRefresh } from '../main-sync-refresh';\nimport { logGuardDecision, GuardDecision } from '../decision-log';\nimport { MergedBranchMessage } from './merged-branch-message';\nimport { TreeRecovery } from './tree-recovery';\n\n/**\n * Comprehensive \"are you on a proper feature branch?\" guard — the single rule that blocks edits when\n * the branch isn't a healthy place to work. Four states, in priority order:\n *   1. On main (checked SYNCHRONOUSLY here)          → block: create a feature branch.\n *   2. Branch already merged into main (merged PR)   → block: your work is in main, branch off fresh.\n *   3. No fork point with origin/main                → block: squash onto a new branch.\n *   4. origin/main moved & touches your files        → block: merge main first.\n * States 2–4 are PRECOMPUTED into `.webpieces/main-sync-status.json` by the detached refresher, so\n * this check does NO network git (only a fast local `git rev-parse` for state 1). On every call it\n * fire-and-forget spawns the refresher so the NEXT call is fresh. Runs in the GUARDS hook (it's a\n * hookGuard); file-scoped, so only Write/Edit/MultiEdit are guarded — Bash passes through so the AI\n * can still run `pnpm wp-start-upsert-pr` and the rest of the recovery flow.\n */\nexport class FeatureBranchGuardRule extends FileRuleBase<FeatureBranchGuardConfig> {\n    constructor(config: FeatureBranchGuardConfig) { super(config, 'feature-branch-guard'); }\n\n    readonly description = 'Block edits unless you are on a proper feature branch (not main, not already-merged, forked, in sync with main).';\n    override readonly files = ['**/*'];\n    override readonly defaultOptions = {\n        branchNamingConvention: '{whoami}/{featurename}',\n        hangTimeoutMinutes: DEFAULT_HANG_TIMEOUT_MINUTES,\n    };\n    readonly fixHint = new FixHint(\n        'You are not on a clean, up-to-date feature branch.',\n        'You must be on a clean, up-to-date feature branch to edit code. Pick one:',\n        [\n            new Option('On main → create a feature branch. Already merged → branch off fresh main.', true),\n            new Option('main moved/conflicts (mid-work) → `pnpm wp-start-update` (merge), `/wp-merge` (resolve), `pnpm wp-finish-update`. Have an OPEN PR? use `pnpm wp-start-upsert-pr` → `/wp-merge` → `pnpm wp-finish-upsert-pr`.'),\n            new Option('Disable in webpieces.config.json under feature-branch-guard (mode OFF) if intentional.'),\n        ],\n    );\n\n    check(ctx: FileContext): readonly Violation[] {\n        // Only files inside the workspace root — guard has no jurisdiction, nothing worth logging.\n        if (ctx.relativePath.startsWith('..')) return [];\n\n        const branch = this.currentBranch(ctx.workspaceRoot);\n        // Can't determine branch (e.g. not a git repo) → don't block. Fail-open.\n        if (branch === null) return this.allow(ctx, branch, 'branch-undeterminable (fail-open)');\n\n        // State 1: on main — synchronous, no cache needed.\n        if (branch === 'main') {\n            return this.block(ctx, branch, 'on-main', this.onMainMessage());\n        }\n\n        // Keep the cache warm for the next call. Detached; never blocks this edit.\n        triggerMainSyncRefresh(ctx.workspaceRoot, this.config.hangTimeoutMinutes ?? DEFAULT_HANG_TIMEOUT_MINUTES);\n\n        const status = readMainSyncStatus(ctx.workspaceRoot);\n        // No cache yet (first edit of the session) → allow; the refresh we just spawned populates it\n        // for the next call. Fail-open: never block on missing data.\n        if (status === null) return this.allow(ctx, branch, 'no-sync-cache (fail-open)', 'cache=none');\n\n        const cache = this.cacheSummary(status);\n        // Stale cross-branch cache: the cached status is for a DIFFERENT branch (e.g. you just\n        // switched branches and the refresh for this one hasn't landed yet). Never block on another\n        // branch's signals — fail open; the refresh we just spawned rewrites it for this branch.\n        if (status.branch !== branch) return this.allow(ctx, branch, 'stale-cross-branch-cache (fail-open)', cache);\n\n        // State 2: this feature branch was already merged into main.\n        if (status.branchAlreadyMerged) {\n            const pr = status.mergedPr !== '' ? status.mergedPr : '?';\n            const merged = this.alreadyMergedMessage(ctx.workspaceRoot, branch, status.mergedPr);\n            return this.block(ctx, branch, `already-merged PR#${pr}`, merged, cache);\n        }\n        // State 3: no fork point — main was merged into the branch.\n        if (!status.hasForkPoint) {\n            return this.block(ctx, branch, 'no-fork-point', this.noForkPointMessage(branch), cache);\n        }\n        // State 4: origin/main moved and touches files you changed.\n        if (status.conflict) {\n            return this.block(ctx, branch, 'main-moved-conflict', this.conflictMessage(status.conflictFiles, status.openPr), cache);\n        }\n        return this.allow(ctx, branch, 'clean-feature-branch', cache);\n    }\n\n    // One-line summary of the async-written cache that drove this decision, for the SYNC log — so a\n    // wrong allow/block is traceable to the exact (possibly stale) main-sync-status.json read.\n    private cacheSummary(status: MainSyncStatus): string {\n        const merged = status.branchAlreadyMerged ? `PR#${status.mergedPr !== '' ? status.mergedPr : '?'}` : 'no';\n        return `cache=${status.branch} merged=${merged} fork=${String(status.hasForkPoint)} conflict=${String(status.conflict)} ts=${status.timestamp}`;\n    }\n\n    // Log + return for the allow path. Centralizes the decision-log call so every exit of check()\n    // is recorded with its reason + the async cache it read (this is the audit trail for \"why didn't\n    // the guard fire?\"). `cache` is the summary of the main-sync-status.json that drove the decision.\n    private allow(ctx: FileContext, branch: string | null, reason: string, cache: string = '-'): readonly Violation[] {\n        this.logDecision(ctx, branch, 'ALLOW', reason, cache);\n        return [];\n    }\n\n    private block(ctx: FileContext, branch: string, reason: string, message: string, cache: string = '-'): readonly Violation[] {\n        this.logDecision(ctx, branch, 'BLOCK', reason, cache);\n        return [new V(1, ctx.relativePath, message)];\n    }\n\n    private logDecision(ctx: FileContext, branch: string | null, verdict: 'ALLOW' | 'BLOCK', reason: string, cache: string): void {\n        logGuardDecision(\n            ctx.workspaceRoot,\n            new GuardDecision('feature-branch-guard', ctx.tool, ctx.relativePath, branch ?? 'unknown', verdict, reason, cache),\n        );\n    }\n\n    private currentBranch(workspaceRoot: string): string | null {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return execSync('git rev-parse --abbrev-ref HEAD', {\n                cwd: workspaceRoot,\n                encoding: 'utf8',\n                stdio: ['pipe', 'pipe', 'pipe'],\n            }).trim();\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n\n    private onMainMessage(): string {\n        const convention = this.config.branchNamingConvention ?? '{whoami}/{featurename}';\n        return [\n            'You should not be working on main.',\n            'Do a `git pull origin main` to get latest, then create a feature branch based on the naming convention.',\n            `Branch naming convention (from webpieces.config.json): ${convention}`,\n            'Example: git checkout -b ' + convention.replace(/<[^>]+>/g, 'value'),\n        ].join('\\n');\n    }\n\n    // Shared with read-stale-guard, which blocks READS in this same state — see MergedBranchMessage.\n    // The tree kind picks the flavour of the cure: a dead LINKED WORKTREE is told to open a new\n    // worktree off origin/main and reap this one; the primary clone is told to branch off origin/main.\n    private alreadyMergedMessage(workspaceRoot: string, branch: string, mergedPr: string): string {\n        return new MergedBranchMessage().forEdits(\n            branch, mergedPr, new TreeRecovery().kindOf(workspaceRoot), workspaceRoot,\n        );\n    }\n\n    private conflictMessage(conflictFiles: readonly string[], openPr: string): string {\n        const files = conflictFiles.length > 0\n            ? conflictFiles.map((f: string): string => `  - ${f}`).join('\\n')\n            : '  (see git diff)';\n        const header = [\n            'origin/main moved and touched files you also changed since your fork point:',\n            files,\n            '',\n        ];\n        // Steer EARLY: if a PR already tracks this branch, the update-only flow would just fail-fast\n        // (a 3-point update strands the PR on the old branch generation), so recommend ONLY the PR\n        // flow and don't waste the AI's tokens on wp-start-update.\n        if (openPr !== '') {\n            return header.concat([\n                `An OPEN PR (#${openPr}) already tracks this branch, so you MUST use the PR flow (it`,\n                're-merges main AND updates the PR — the update-only flow would strand the PR on the',\n                'old branch generation):',\n                '  1. pnpm wp-start-upsert-pr   ← merges main + writes 3-point context',\n                '  2. /wp-merge                 ← resolve each conflicted file (only if conflicts)',\n                '  3. pnpm wp-finish-upsert-pr  ← validate, build, push, upsert the PR',\n            ]).join('\\n');\n        }\n        return header.concat([\n            'You must merge main in before editing further. If you are mid-work and just want to keep',\n            'editing (no PR yet), use the UPDATE-ONLY flow:',\n            '  1. pnpm wp-start-update   ← merges main (auto-finalizes if clean; renames <branch>wpN → wpN+1)',\n            '  2. /wp-merge              ← resolve each conflicted file (only if there are conflicts)',\n            '  3. pnpm wp-finish-update  ← finalize the merge (only after resolving)',\n            '',\n            'If you already have an OPEN PR for this branch, use the PR flow instead (wp-start-update',\n            'refuses when a PR exists — it would strand the PR on the old branch generation):',\n            '  1. pnpm wp-start-upsert-pr   ← merges main + writes 3-point context',\n            '  2. /wp-merge                 ← resolve each conflicted file',\n            '  3. pnpm wp-finish-upsert-pr  ← validate, build, push, upsert the PR',\n        ]).join('\\n');\n    }\n\n    private noForkPointMessage(branch: string): string {\n        return [\n            'No fork point with origin/main — main appears to have been merged into this branch,',\n            'so a clean squash-merge is impossible. A human must redo the work on a fresh branch:',\n            '',\n            ...squashRecoverySteps(branch),\n        ].join('\\n');\n    }\n}\n"]}

package/src/core/rules/merged-branch-message.d.ts

@@ -1,3 +1,4 @@
+import { TreeKind } from './tree-recovery';
 /**
  * The "this branch is already merged, start fresh" text, shared by the TWO guards that detect the
  * state from the same cached signal (`MainSyncStatus.branchAlreadyMerged`):
@@ -5,18 +6,23 @@
  *   - feature-branch-guard blocks Write/Edit  → {@link MergedBranchMessage.forEdits}
  *   - read-stale-guard     blocks Read        → {@link MergedBranchMessage.forReads}
  *
- * One source of truth on purpose: the recovery steps (`git checkout -b <new> origin/main`, never
- * `git checkout main` — it fatals inside a worktree) are instructions the AI follows LITERALLY, so
+ * One source of truth on purpose: the recovery steps are instructions the AI follows LITERALLY, so
  * two drifting copies would mean two different behaviors for the same repo state. Only the
  * "what is still allowed" tail differs, because the two guards block different tools.
+ *
+ * The steps themselves come from {@link TreeRecovery}, which renders them in the flavour of the tree
+ * we are actually standing in — a merged LINKED WORKTREE is told to open a new worktree and remove
+ * this dead one, a merged branch in the primary clone is told to `git checkout -b … origin/main`.
+ * Neither is ever told to `git checkout main`, which fatals in a worktree.
  */
 export declare class MergedBranchMessage {
+    private readonly recovery;
     private common;
-    forEdits(branch: string, mergedPr: string): string;
+    forEdits(branch: string, mergedPr: string, kind?: TreeKind, worktreePath?: string): string;
     /**
      * The Read variant. Says WHY a read (not an edit) is blocked — reading this branch feeds the AI a
      * pre-merge snapshot of the codebase and every plan built on it is built on code main has already
      * moved past — and spells out the escape valves so the agent never believes it is stuck.
      */
-    forReads(branch: string, mergedPr: string): string;
+    forReads(branch: string, mergedPr: string, kind?: TreeKind, worktreePath?: string): string;
 }

package/src/core/rules/merged-branch-message.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MergedBranchMessage = void 0;
+const tree_recovery_1 = require("./tree-recovery");
 /**
  * The "this branch is already merged, start fresh" text, shared by the TWO guards that detect the
  * state from the same cached signal (`MainSyncStatus.branchAlreadyMerged`):
@@ -8,27 +9,38 @@ exports.MergedBranchMessage = void 0;
  *   - feature-branch-guard blocks Write/Edit  → {@link MergedBranchMessage.forEdits}
  *   - read-stale-guard     blocks Read        → {@link MergedBranchMessage.forReads}
  *
- * One source of truth on purpose: the recovery steps (`git checkout -b <new> origin/main`, never
- * `git checkout main` — it fatals inside a worktree) are instructions the AI follows LITERALLY, so
+ * One source of truth on purpose: the recovery steps are instructions the AI follows LITERALLY, so
  * two drifting copies would mean two different behaviors for the same repo state. Only the
  * "what is still allowed" tail differs, because the two guards block different tools.
+ *
+ * The steps themselves come from {@link TreeRecovery}, which renders them in the flavour of the tree
+ * we are actually standing in — a merged LINKED WORKTREE is told to open a new worktree and remove
+ * this dead one, a merged branch in the primary clone is told to `git checkout -b … origin/main`.
+ * Neither is ever told to `git checkout main`, which fatals in a worktree.
  */
 class MergedBranchMessage {
+    recovery = new tree_recovery_1.TreeRecovery();
     // The diagnosis + cure. Identical for both guards — this is the part that must never drift.
-    common(branch, mergedPr) {
+    common(branch, mergedPr, kind, worktreePath) {
         const pr = mergedPr !== '' ? ` (merged PR #${mergedPr})` : '';
-        return [
-            `It looks like you forgot to switch to main and delete this branch "${branch}" — its PR is already merged into main${pr}.`,
-            'Your work is in main — do NOT keep editing this stale branch (you will reconflict with main).',
-            'Start fresh — branch off origin/main (works on the primary repo AND inside a worktree; never',
-            '`git checkout main`, which fatals in a worktree):',
-            '  1. git fetch origin main',
-            '  2. git checkout -b <new-feature-branch> origin/main',
+        const where = kind === 'worktree' ? 'worktree' : 'branch';
+        const lines = [
+            `It looks like you forgot to clean up this ${where} "${branch}" — its PR is already merged into main${pr}.`,
+            'Your work is in main — do NOT keep working here (you will reconflict with main).',
+            '',
+            ...this.recovery.freshStartSteps(kind, '<new-feature-branch>'),
         ];
+        // Only when we KNOW we are in a dead worktree: the branch cure alone leaves the worktree
+        // sitting there, spending the worktree budget (branch-creation-guard.maxWorktrees) forever.
+        if (kind === 'worktree') {
+            lines.push('', 'Then reap this dead worktree:', ...this.recovery.cleanupSteps(kind, branch, worktreePath).slice(-1));
+        }
+        return lines;
     }
-    forEdits(branch, mergedPr) {
-        return this.common(branch, mergedPr).concat([
-            'Please add to memory: start a new branch off origin/main after a PR is merged.',
+    forEdits(branch, mergedPr, kind = 'unknown', worktreePath = '<worktree-dir>') {
+        return this.common(branch, mergedPr, kind, worktreePath).concat([
+            '',
+            'Please add to memory: start a new branch/worktree off origin/main after a PR is merged.',
         ]).join('\n');
     }
     /**
@@ -36,10 +48,10 @@ class MergedBranchMessage {
      * pre-merge snapshot of the codebase and every plan built on it is built on code main has already
      * moved past — and spells out the escape valves so the agent never believes it is stuck.
      */
-    forReads(branch, mergedPr) {
-        return this.common(branch, mergedPr).concat([
+    forReads(branch, mergedPr, kind = 'unknown', worktreePath = '<worktree-dir>') {
+        return this.common(branch, mergedPr, kind, worktreePath).concat([
             '',
-            'Reads are blocked here because this branch is a PRE-MERGE snapshot: anything you read is',
+            'Reads are blocked here because this tree is a PRE-MERGE snapshot: anything you read is',
             'stale relative to origin/main, and a plan built on it is built on code that has moved.',
             '',
             'Still allowed while this block is up:',
@@ -47,7 +59,7 @@ class MergedBranchMessage {
             '  - All Write/Edit (feature-branch-guard governs those separately)',
             '  - Reading and editing webpieces.config.json (set read-stale-guard mode OFF to disable)',
             '',
-            'Please add to memory: start a new branch off origin/main after a PR is merged.',
+            'Please add to memory: start a new branch/worktree off origin/main after a PR is merged.',
         ]).join('\n');
     }
 }

package/src/core/rules/merged-branch-message.js.map

@@ -1 +1 @@
-{"version":3,"file":"merged-branch-message.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/merged-branch-message.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;GAWG;AACH,MAAa,mBAAmB;IAC5B,4FAA4F;IACpF,MAAM,CAAC,MAAc,EAAE,QAAgB;QAC3C,MAAM,EAAE,GAAG,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,gBAAgB,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,OAAO;YACH,sEAAsE,MAAM,yCAAyC,EAAE,GAAG;YAC1H,+FAA+F;YAC/F,8FAA8F;YAC9F,mDAAmD;YACnD,4BAA4B;YAC5B,uDAAuD;SAC1D,CAAC;IACN,CAAC;IAED,QAAQ,CAAC,MAAc,EAAE,QAAgB;QACrC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,MAAM,CAAC;YACxC,gFAAgF;SACnF,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,MAAc,EAAE,QAAgB;QACrC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,MAAM,CAAC;YACxC,EAAE;YACF,0FAA0F;YAC1F,wFAAwF;YACxF,EAAE;YACF,uCAAuC;YACvC,+EAA+E;YAC/E,oEAAoE;YACpE,0FAA0F;YAC1F,EAAE;YACF,gFAAgF;SACnF,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;CACJ;AAvCD,kDAuCC","sourcesContent":["/**\n * The \"this branch is already merged, start fresh\" text, shared by the TWO guards that detect the\n * state from the same cached signal (`MainSyncStatus.branchAlreadyMerged`):\n *\n *   - feature-branch-guard blocks Write/Edit  → {@link MergedBranchMessage.forEdits}\n *   - read-stale-guard     blocks Read        → {@link MergedBranchMessage.forReads}\n *\n * One source of truth on purpose: the recovery steps (`git checkout -b <new> origin/main`, never\n * `git checkout main` — it fatals inside a worktree) are instructions the AI follows LITERALLY, so\n * two drifting copies would mean two different behaviors for the same repo state. Only the\n * \"what is still allowed\" tail differs, because the two guards block different tools.\n */\nexport class MergedBranchMessage {\n    // The diagnosis + cure. Identical for both guards — this is the part that must never drift.\n    private common(branch: string, mergedPr: string): string[] {\n        const pr = mergedPr !== '' ? ` (merged PR #${mergedPr})` : '';\n        return [\n            `It looks like you forgot to switch to main and delete this branch \"${branch}\" — its PR is already merged into main${pr}.`,\n            'Your work is in main — do NOT keep editing this stale branch (you will reconflict with main).',\n            'Start fresh — branch off origin/main (works on the primary repo AND inside a worktree; never',\n            '`git checkout main`, which fatals in a worktree):',\n            '  1. git fetch origin main',\n            '  2. git checkout -b <new-feature-branch> origin/main',\n        ];\n    }\n\n    forEdits(branch: string, mergedPr: string): string {\n        return this.common(branch, mergedPr).concat([\n            'Please add to memory: start a new branch off origin/main after a PR is merged.',\n        ]).join('\\n');\n    }\n\n    /**\n     * The Read variant. Says WHY a read (not an edit) is blocked — reading this branch feeds the AI a\n     * pre-merge snapshot of the codebase and every plan built on it is built on code main has already\n     * moved past — and spells out the escape valves so the agent never believes it is stuck.\n     */\n    forReads(branch: string, mergedPr: string): string {\n        return this.common(branch, mergedPr).concat([\n            '',\n            'Reads are blocked here because this branch is a PRE-MERGE snapshot: anything you read is',\n            'stale relative to origin/main, and a plan built on it is built on code that has moved.',\n            '',\n            'Still allowed while this block is up:',\n            '  - EVERY Bash command (the git commands above, installs, builds, all git/gh)',\n            '  - All Write/Edit (feature-branch-guard governs those separately)',\n            '  - Reading and editing webpieces.config.json (set read-stale-guard mode OFF to disable)',\n            '',\n            'Please add to memory: start a new branch off origin/main after a PR is merged.',\n        ]).join('\\n');\n    }\n}\n"]}
+{"version":3,"file":"merged-branch-message.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/merged-branch-message.ts"],"names":[],"mappings":";;;AAAA,mDAAyD;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,MAAa,mBAAmB;IACX,QAAQ,GAAG,IAAI,4BAAY,EAAE,CAAC;IAE/C,4FAA4F;IACpF,MAAM,CAAC,MAAc,EAAE,QAAgB,EAAE,IAAc,EAAE,YAAoB;QACjF,MAAM,EAAE,GAAG,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,gBAAgB,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,MAAM,KAAK,GAAG,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC1D,MAAM,KAAK,GAAG;YACV,6CAA6C,KAAK,KAAK,MAAM,yCAAyC,EAAE,GAAG;YAC3G,kFAAkF;YAClF,EAAE;YACF,GAAG,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,EAAE,sBAAsB,CAAC;SACjE,CAAC;QAEF,yFAAyF;QACzF,4FAA4F;QAC5F,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,+BAA+B,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACzH,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,QAAQ,CAAC,MAAc,EAAE,QAAgB,EAAE,OAAiB,SAAS,EAAE,eAAuB,gBAAgB;QAC1G,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,MAAM,CAAC;YAC5D,EAAE;YACF,yFAAyF;SAC5F,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,MAAc,EAAE,QAAgB,EAAE,OAAiB,SAAS,EAAE,eAAuB,gBAAgB;QAC1G,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,MAAM,CAAC;YAC5D,EAAE;YACF,wFAAwF;YACxF,wFAAwF;YACxF,EAAE;YACF,uCAAuC;YACvC,+EAA+E;YAC/E,oEAAoE;YACpE,0FAA0F;YAC1F,EAAE;YACF,yFAAyF;SAC5F,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;CACJ;AAhDD,kDAgDC","sourcesContent":["import { TreeRecovery, TreeKind } from './tree-recovery';\n\n/**\n * The \"this branch is already merged, start fresh\" text, shared by the TWO guards that detect the\n * state from the same cached signal (`MainSyncStatus.branchAlreadyMerged`):\n *\n *   - feature-branch-guard blocks Write/Edit  → {@link MergedBranchMessage.forEdits}\n *   - read-stale-guard     blocks Read        → {@link MergedBranchMessage.forReads}\n *\n * One source of truth on purpose: the recovery steps are instructions the AI follows LITERALLY, so\n * two drifting copies would mean two different behaviors for the same repo state. Only the\n * \"what is still allowed\" tail differs, because the two guards block different tools.\n *\n * The steps themselves come from {@link TreeRecovery}, which renders them in the flavour of the tree\n * we are actually standing in — a merged LINKED WORKTREE is told to open a new worktree and remove\n * this dead one, a merged branch in the primary clone is told to `git checkout -b … origin/main`.\n * Neither is ever told to `git checkout main`, which fatals in a worktree.\n */\nexport class MergedBranchMessage {\n    private readonly recovery = new TreeRecovery();\n\n    // The diagnosis + cure. Identical for both guards — this is the part that must never drift.\n    private common(branch: string, mergedPr: string, kind: TreeKind, worktreePath: string): string[] {\n        const pr = mergedPr !== '' ? ` (merged PR #${mergedPr})` : '';\n        const where = kind === 'worktree' ? 'worktree' : 'branch';\n        const lines = [\n            `It looks like you forgot to clean up this ${where} \"${branch}\" — its PR is already merged into main${pr}.`,\n            'Your work is in main — do NOT keep working here (you will reconflict with main).',\n            '',\n            ...this.recovery.freshStartSteps(kind, '<new-feature-branch>'),\n        ];\n\n        // Only when we KNOW we are in a dead worktree: the branch cure alone leaves the worktree\n        // sitting there, spending the worktree budget (branch-creation-guard.maxWorktrees) forever.\n        if (kind === 'worktree') {\n            lines.push('', 'Then reap this dead worktree:', ...this.recovery.cleanupSteps(kind, branch, worktreePath).slice(-1));\n        }\n        return lines;\n    }\n\n    forEdits(branch: string, mergedPr: string, kind: TreeKind = 'unknown', worktreePath: string = '<worktree-dir>'): string {\n        return this.common(branch, mergedPr, kind, worktreePath).concat([\n            '',\n            'Please add to memory: start a new branch/worktree off origin/main after a PR is merged.',\n        ]).join('\\n');\n    }\n\n    /**\n     * The Read variant. Says WHY a read (not an edit) is blocked — reading this branch feeds the AI a\n     * pre-merge snapshot of the codebase and every plan built on it is built on code main has already\n     * moved past — and spells out the escape valves so the agent never believes it is stuck.\n     */\n    forReads(branch: string, mergedPr: string, kind: TreeKind = 'unknown', worktreePath: string = '<worktree-dir>'): string {\n        return this.common(branch, mergedPr, kind, worktreePath).concat([\n            '',\n            'Reads are blocked here because this tree is a PRE-MERGE snapshot: anything you read is',\n            'stale relative to origin/main, and a plan built on it is built on code that has moved.',\n            '',\n            'Still allowed while this block is up:',\n            '  - EVERY Bash command (the git commands above, installs, builds, all git/gh)',\n            '  - All Write/Edit (feature-branch-guard governs those separately)',\n            '  - Reading and editing webpieces.config.json (set read-stale-guard mode OFF to disable)',\n            '',\n            'Please add to memory: start a new branch/worktree off origin/main after a PR is merged.',\n        ]).join('\\n');\n    }\n}\n"]}

package/src/core/rules/pr-merge-guard.d.ts

@@ -6,6 +6,14 @@ export declare class PrMergeGuardRule extends BashRuleBase<PrMergeGuardConfig> {
     constructor(config: PrMergeGuardConfig);
     readonly description = "After merging a PR, require switching to main, pulling, and deleting the local branch.";
     private currentBranch;
+    private treeKind;
+    private worktreePath;
+    private readonly recovery;
     get fixHint(): FixHint;
+    /**
+     * The accepted cleanups differ by tree, so the "already cleaning up" detection has to as well:
+     * in a linked worktree `git checkout main` FATALS, so demanding it there would be demanding an
+     * impossible command. A worktree is cleaned up by `git worktree remove` + `git branch -D`.
+     */
     check(ctx: BashContext): readonly Violation[];
 }

package/src/core/rules/pr-merge-guard.js

@@ -5,6 +5,7 @@ const child_process_1 = require("child_process");
 const types_1 = require("../types");
 const rule_base_1 = require("../rule-base");
 const fix_hint_1 = require("../fix-hint");
+const tree_recovery_1 = require("./tree-recovery");
 function truncate(s) {
     const MAX = 120;
     return s.length <= MAX ? s : s.slice(0, MAX) + '…';
@@ -14,23 +15,51 @@ class PrMergeGuardRule extends rule_base_1.BashRuleBase {
     description = 'After merging a PR, require switching to main, pulling, and deleting the local branch.';
     // Substituted with the real branch name in check(); the getter reads it. Placeholder until then.
     currentBranch = '<current-branch>';
+    // The tree we are standing in, resolved in check() so fixHint renders the ONE cleanup that
+    // actually works here. 'unknown' until check() runs (fixHint is also read before/without it).
+    treeKind = 'unknown';
+    worktreePath = '<worktree-dir>';
+    recovery = new tree_recovery_1.TreeRecovery();
     // Single fix, no distinct options — the whole guidance lives in mainMessage so it renders as
     // one coherent block (never split into fake "Fix Option 1/2/3").
+    //
+    // `pnpm wp-cleanup` rather than `git branch -d <branch>`: a raw `-d` reads as destructive, so
+    // agents ask permission and stop, and the branch survives. wp-cleanup is one named command that
+    // deletes ONLY provably-dead branches — and it reaps every OTHER dead branch at the same time,
+    // which is the moment that actually keeps the local branch list bounded.
     get fixHint() {
-        return new fix_hint_1.FixHint('After merging a PR you must clean up the local branch.', `Run gh pr merge --squash && git checkout main && git pull && git branch -d ${this.currentBranch}.\n`
-            + "Add this to your memory so you don't forget next time and waste tokens.");
+        return new fix_hint_1.FixHint('After merging a PR you must clean up the branch (and the worktree, if it has one).', ['Run `gh pr merge --squash`, then:', '']
+            .concat(this.recovery.cleanupSteps(this.treeKind, this.currentBranch, this.worktreePath))
+            .concat(['', "Add this to your memory so you don't forget next time and waste tokens."])
+            .join('\n'));
     }
+    /**
+     * The accepted cleanups differ by tree, so the "already cleaning up" detection has to as well:
+     * in a linked worktree `git checkout main` FATALS, so demanding it there would be demanding an
+     * impossible command. A worktree is cleaned up by `git worktree remove` + `git branch -D`.
+     */
     check(ctx) {
         if (!/gh\s+pr\s+merge/.test(ctx.command))
             return [];
+        // `wp-cleanup` counts as a delete: it is the command the branch-flavoured cleanupSteps now
+        // hand out, and it deletes the just-merged branch (plus every other dead one). A literal
+        // `git branch -d` still satisfies the guard too — narrower, but not wrong.
+        const hasDelete = /git\s+branch\s+-[dD]|wp-cleanup/.test(ctx.command);
         const hasCheckout = /git\s+(checkout|switch)\s+main/.test(ctx.command);
-        const hasDelete = /git\s+branch\s+-[dD]/.test(ctx.command);
-        if (hasCheckout && hasDelete)
+        const hasWorktreeRemove = /git\s+worktree\s+remove\b/.test(ctx.command);
+        this.treeKind = this.recovery.kindOf(ctx.workspaceRoot);
+        if (this.treeKind === 'worktree') {
+            if (hasWorktreeRemove && hasDelete)
+                return [];
+        }
+        else if (hasCheckout && hasDelete) {
             return [];
+        }
         this.currentBranch = (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD', {
             cwd: ctx.workspaceRoot,
             encoding: 'utf8',
         }).trim();
+        this.worktreePath = ctx.workspaceRoot;
         return [new types_1.Violation(1, truncate(ctx.command))];
     }
 }

package/src/core/rules/pr-merge-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"pr-merge-guard.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/pr-merge-guard.ts"],"names":[],"mappings":";;;AAAA,iDAAyC;AAKzC,oCAA0C;AAC1C,4CAA4C;AAC5C,0CAAsC;AAEtC,SAAS,QAAQ,CAAC,CAAS;IACvB,MAAM,GAAG,GAAG,GAAG,CAAC;IAChB,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC;AACvD,CAAC;AAED,MAAa,gBAAiB,SAAQ,wBAAgC;IAClE,YAAY,MAA0B,IAAI,KAAK,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAEnE,WAAW,GAAG,wFAAwF,CAAC;IAEhH,iGAAiG;IACzF,aAAa,GAAG,kBAAkB,CAAC;IAE3C,6FAA6F;IAC7F,iEAAiE;IACjE,IAAI,OAAO;QACP,OAAO,IAAI,kBAAO,CACd,wDAAwD,EACxD,8EAA8E,IAAI,CAAC,aAAa,KAAK;cACnG,yEAAyE,CAC9E,CAAC;IACN,CAAC;IAED,KAAK,CAAC,GAAgB;QAClB,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,OAAO,EAAE,CAAC;QAEpD,MAAM,WAAW,GAAG,gCAAgC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvE,MAAM,SAAS,GAAG,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAE3D,IAAI,WAAW,IAAI,SAAS;YAAE,OAAO,EAAE,CAAC;QAExC,IAAI,CAAC,aAAa,GAAG,IAAA,wBAAQ,EAAC,iCAAiC,EAAE;YAC7D,GAAG,EAAE,GAAG,CAAC,aAAa;YACtB,QAAQ,EAAE,MAAM;SACnB,CAAC,CAAC,IAAI,EAAE,CAAC;QAEV,OAAO,CAAC,IAAI,iBAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7C,CAAC;CACJ;AAjCD,4CAiCC","sourcesContent":["import { execSync } from 'child_process';\n\nimport { PrMergeGuardConfig } from '@webpieces/rules-config';\n\nimport type { BashContext, Violation } from '../types';\nimport { Violation as V } from '../types';\nimport { BashRuleBase } from '../rule-base';\nimport { FixHint } from '../fix-hint';\n\nfunction truncate(s: string): string {\n    const MAX = 120;\n    return s.length <= MAX ? s : s.slice(0, MAX) + '…';\n}\n\nexport class PrMergeGuardRule extends BashRuleBase<PrMergeGuardConfig> {\n    constructor(config: PrMergeGuardConfig) { super(config, 'pr-merge-guard'); }\n\n    readonly description = 'After merging a PR, require switching to main, pulling, and deleting the local branch.';\n\n    // Substituted with the real branch name in check(); the getter reads it. Placeholder until then.\n    private currentBranch = '<current-branch>';\n\n    // Single fix, no distinct options — the whole guidance lives in mainMessage so it renders as\n    // one coherent block (never split into fake \"Fix Option 1/2/3\").\n    get fixHint(): FixHint {\n        return new FixHint(\n            'After merging a PR you must clean up the local branch.',\n            `Run gh pr merge --squash && git checkout main && git pull && git branch -d ${this.currentBranch}.\\n`\n            + \"Add this to your memory so you don't forget next time and waste tokens.\",\n        );\n    }\n\n    check(ctx: BashContext): readonly Violation[] {\n        if (!/gh\\s+pr\\s+merge/.test(ctx.command)) return [];\n\n        const hasCheckout = /git\\s+(checkout|switch)\\s+main/.test(ctx.command);\n        const hasDelete = /git\\s+branch\\s+-[dD]/.test(ctx.command);\n\n        if (hasCheckout && hasDelete) return [];\n\n        this.currentBranch = execSync('git rev-parse --abbrev-ref HEAD', {\n            cwd: ctx.workspaceRoot,\n            encoding: 'utf8',\n        }).trim();\n\n        return [new V(1, truncate(ctx.command))];\n    }\n}\n"]}
+{"version":3,"file":"pr-merge-guard.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/pr-merge-guard.ts"],"names":[],"mappings":";;;AAAA,iDAAyC;AAKzC,oCAA0C;AAC1C,4CAA4C;AAC5C,0CAAsC;AACtC,mDAAyD;AAEzD,SAAS,QAAQ,CAAC,CAAS;IACvB,MAAM,GAAG,GAAG,GAAG,CAAC;IAChB,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC;AACvD,CAAC;AAED,MAAa,gBAAiB,SAAQ,wBAAgC;IAClE,YAAY,MAA0B,IAAI,KAAK,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAEnE,WAAW,GAAG,wFAAwF,CAAC;IAEhH,iGAAiG;IACzF,aAAa,GAAG,kBAAkB,CAAC;IAE3C,2FAA2F;IAC3F,8FAA8F;IACtF,QAAQ,GAAa,SAAS,CAAC;IAC/B,YAAY,GAAG,gBAAgB,CAAC;IAEvB,QAAQ,GAAG,IAAI,4BAAY,EAAE,CAAC;IAE/C,6FAA6F;IAC7F,iEAAiE;IACjE,EAAE;IACF,8FAA8F;IAC9F,gGAAgG;IAChG,+FAA+F;IAC/F,yEAAyE;IACzE,IAAI,OAAO;QACP,OAAO,IAAI,kBAAO,CACd,oFAAoF,EACpF,CAAC,mCAAmC,EAAE,EAAE,CAAC;aACpC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;aACxF,MAAM,CAAC,CAAC,EAAE,EAAE,yEAAyE,CAAC,CAAC;aACvF,IAAI,CAAC,IAAI,CAAC,CAClB,CAAC;IACN,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAgB;QAClB,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,OAAO,EAAE,CAAC;QAEpD,2FAA2F;QAC3F,yFAAyF;QACzF,2EAA2E;QAC3E,MAAM,SAAS,GAAG,iCAAiC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACtE,MAAM,WAAW,GAAG,gCAAgC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvE,MAAM,iBAAiB,GAAG,2BAA2B,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAExE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACxD,IAAI,IAAI,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;YAC/B,IAAI,iBAAiB,IAAI,SAAS;gBAAE,OAAO,EAAE,CAAC;QAClD,CAAC;aAAM,IAAI,WAAW,IAAI,SAAS,EAAE,CAAC;YAClC,OAAO,EAAE,CAAC;QACd,CAAC;QAED,IAAI,CAAC,aAAa,GAAG,IAAA,wBAAQ,EAAC,iCAAiC,EAAE;YAC7D,GAAG,EAAE,GAAG,CAAC,aAAa;YACtB,QAAQ,EAAE,MAAM;SACnB,CAAC,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,CAAC,YAAY,GAAG,GAAG,CAAC,aAAa,CAAC;QAEtC,OAAO,CAAC,IAAI,iBAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7C,CAAC;CACJ;AA9DD,4CA8DC","sourcesContent":["import { execSync } from 'child_process';\n\nimport { PrMergeGuardConfig } from '@webpieces/rules-config';\n\nimport type { BashContext, Violation } from '../types';\nimport { Violation as V } from '../types';\nimport { BashRuleBase } from '../rule-base';\nimport { FixHint } from '../fix-hint';\nimport { TreeRecovery, TreeKind } from './tree-recovery';\n\nfunction truncate(s: string): string {\n    const MAX = 120;\n    return s.length <= MAX ? s : s.slice(0, MAX) + '…';\n}\n\nexport class PrMergeGuardRule extends BashRuleBase<PrMergeGuardConfig> {\n    constructor(config: PrMergeGuardConfig) { super(config, 'pr-merge-guard'); }\n\n    readonly description = 'After merging a PR, require switching to main, pulling, and deleting the local branch.';\n\n    // Substituted with the real branch name in check(); the getter reads it. Placeholder until then.\n    private currentBranch = '<current-branch>';\n\n    // The tree we are standing in, resolved in check() so fixHint renders the ONE cleanup that\n    // actually works here. 'unknown' until check() runs (fixHint is also read before/without it).\n    private treeKind: TreeKind = 'unknown';\n    private worktreePath = '<worktree-dir>';\n\n    private readonly recovery = new TreeRecovery();\n\n    // Single fix, no distinct options — the whole guidance lives in mainMessage so it renders as\n    // one coherent block (never split into fake \"Fix Option 1/2/3\").\n    //\n    // `pnpm wp-cleanup` rather than `git branch -d <branch>`: a raw `-d` reads as destructive, so\n    // agents ask permission and stop, and the branch survives. wp-cleanup is one named command that\n    // deletes ONLY provably-dead branches — and it reaps every OTHER dead branch at the same time,\n    // which is the moment that actually keeps the local branch list bounded.\n    get fixHint(): FixHint {\n        return new FixHint(\n            'After merging a PR you must clean up the branch (and the worktree, if it has one).',\n            ['Run `gh pr merge --squash`, then:', '']\n                .concat(this.recovery.cleanupSteps(this.treeKind, this.currentBranch, this.worktreePath))\n                .concat(['', \"Add this to your memory so you don't forget next time and waste tokens.\"])\n                .join('\\n'),\n        );\n    }\n\n    /**\n     * The accepted cleanups differ by tree, so the \"already cleaning up\" detection has to as well:\n     * in a linked worktree `git checkout main` FATALS, so demanding it there would be demanding an\n     * impossible command. A worktree is cleaned up by `git worktree remove` + `git branch -D`.\n     */\n    check(ctx: BashContext): readonly Violation[] {\n        if (!/gh\\s+pr\\s+merge/.test(ctx.command)) return [];\n\n        // `wp-cleanup` counts as a delete: it is the command the branch-flavoured cleanupSteps now\n        // hand out, and it deletes the just-merged branch (plus every other dead one). A literal\n        // `git branch -d` still satisfies the guard too — narrower, but not wrong.\n        const hasDelete = /git\\s+branch\\s+-[dD]|wp-cleanup/.test(ctx.command);\n        const hasCheckout = /git\\s+(checkout|switch)\\s+main/.test(ctx.command);\n        const hasWorktreeRemove = /git\\s+worktree\\s+remove\\b/.test(ctx.command);\n\n        this.treeKind = this.recovery.kindOf(ctx.workspaceRoot);\n        if (this.treeKind === 'worktree') {\n            if (hasWorktreeRemove && hasDelete) return [];\n        } else if (hasCheckout && hasDelete) {\n            return [];\n        }\n\n        this.currentBranch = execSync('git rev-parse --abbrev-ref HEAD', {\n            cwd: ctx.workspaceRoot,\n            encoding: 'utf8',\n        }).trim();\n        this.worktreePath = ctx.workspaceRoot;\n\n        return [new V(1, truncate(ctx.command))];\n    }\n}\n"]}

package/src/core/rules/read-stale-guard.d.ts

@@ -68,10 +68,15 @@ export declare class ReadStaleGuardRule extends FileRuleBase<ReadStaleGuardConfi
      * merged`), so this path spawns nothing. No `gh` / offline → `mergedPr` is '' → not merged → allow,
      * which is the fail-open direction for free.
      *
-     * NOTE the missing dirty-tree check: unlike state A, we block a dirty tree too. `git checkout -b
-     * <new> origin/main` carries uncommitted work across, so the agent is never trapped here.
+     * The DIRTY-TREE escape valve is the same one state A has, for the same reason: uncommitted work
+     * on a merged branch is work that exists nowhere else, and rescuing it means READING the files it
+     * touches. `git checkout -b <new> origin/main` usually carries those changes across — but when it
+     * does not (an overlapping change landed in main), a blocked read is an agent that cannot even
+     * see what it is about to lose. feature-branch-guard still blocks the EDITS, so the state is
+     * surfaced loudly either way; we just refuse to cut off the rescue path.
      */
     private checkMergedBranch;
+    private mergedMessage;
     private contains;
     private isDirty;
     private isConfigFile;

package/src/core/rules/read-stale-guard.js

@@ -13,6 +13,7 @@ const to_error_1 = require("../to-error");
 const main_sync_refresh_1 = require("../main-sync-refresh");
 const decision_log_1 = require("../decision-log");
 const merged_branch_message_1 = require("./merged-branch-message");
+const tree_recovery_1 = require("./tree-recovery");
 /**
  * Blocks READS while the checked-out branch is a stale place to read from. TWO states:
  *
@@ -121,8 +122,12 @@ class ReadStaleGuardRule extends rule_base_1.FileRuleBase {
      * merged`), so this path spawns nothing. No `gh` / offline → `mergedPr` is '' → not merged → allow,
      * which is the fail-open direction for free.
      *
-     * NOTE the missing dirty-tree check: unlike state A, we block a dirty tree too. `git checkout -b
-     * <new> origin/main` carries uncommitted work across, so the agent is never trapped here.
+     * The DIRTY-TREE escape valve is the same one state A has, for the same reason: uncommitted work
+     * on a merged branch is work that exists nowhere else, and rescuing it means READING the files it
+     * touches. `git checkout -b <new> origin/main` usually carries those changes across — but when it
+     * does not (an overlapping change landed in main), a blocked read is an agent that cannot even
+     * see what it is about to lose. feature-branch-guard still blocks the EDITS, so the state is
+     * surfaced loudly either way; we just refuse to cut off the rescue path.
      */
     checkMergedBranch(ctx, branch) {
         const status = (0, rules_config_1.readMainSyncStatus)(ctx.workspaceRoot);
@@ -136,8 +141,19 @@ class ReadStaleGuardRule extends rule_base_1.FileRuleBase {
             return this.allow(ctx, branch, 'stale-cross-branch-cache (fail-open)', cache);
         if (!status.branchAlreadyMerged)
             return this.allow(ctx, branch, 'clean-feature-branch', cache);
+        if (this.isDirty(ctx.workspaceRoot)) {
+            return this.allow(ctx, branch, 'dirty-merged-branch (fail-open)', cache);
+        }
         const pr = status.mergedPr !== '' ? status.mergedPr : '?';
-        return this.block(ctx, branch, `already-merged PR#${pr}`, new merged_branch_message_1.MergedBranchMessage().forReads(branch, status.mergedPr), cache);
+        return this.block(ctx, branch, `already-merged PR#${pr}`, this.mergedMessage(ctx.workspaceRoot, branch, status.mergedPr), cache);
+    }
+    // The merged-branch text, told in the flavour of the tree we are standing in: a linked worktree
+    // is told to open a NEW worktree off origin/main and reap this dead one; the primary clone is
+    // told to branch off origin/main. Neither is ever told to `git checkout main` (fatal in a
+    // worktree). Detection is one statSync — see WorktreeService.isLinkedWorktree.
+    mergedMessage(workspaceRoot, branch, mergedPr) {
+        const recovery = new tree_recovery_1.TreeRecovery();
+        return new merged_branch_message_1.MergedBranchMessage().forReads(branch, mergedPr, recovery.kindOf(workspaceRoot), workspaceRoot);
     }
     // Is `commit` an ancestor of (i.e. already contained in) HEAD? Local-only and fast — no network.
     //

package/src/core/rules/read-stale-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"read-stale-guard.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/read-stale-guard.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync, spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\nimport {\n    ReadStaleGuardConfig,\n    DEFAULT_HANG_TIMEOUT_MINUTES,\n    readMainSyncStatus,\n    MainSyncStatus,\n} from '@webpieces/rules-config';\n\nimport type { FileContext, Violation } from '../types';\nimport { Violation as V } from '../types';\nimport { FileRuleBase } from '../rule-base';\nimport { FixHint, Option } from '../fix-hint';\nimport { toError } from '../to-error';\nimport { triggerMainSyncRefresh } from '../main-sync-refresh';\nimport { logGuardDecision, GuardDecision } from '../decision-log';\nimport { MergedBranchMessage } from './merged-branch-message';\n\n/**\n * Blocks READS while the checked-out branch is a stale place to read from. TWO states:\n *\n *   A. on `main`, and local main is BEHIND origin/main\n *   B. on a feature branch whose PR is ALREADY MERGED (a pre-merge snapshot; origin/main has moved\n *      past it and a squash merge means its HEAD is not even an ancestor of main)\n *\n * WHY READ, of all tools: either state means the AI reads stale FILE CONTENT and then reasons,\n * plans and writes against code that no longer exists upstream. Blocking the write is too late —\n * the bad premise is already in context. So the block lands on the read. (feature-branch-guard\n * blocks the WRITE in state B; this guard is the read-side half of that same protection, and the\n * two share one recovery message via MergedBranchMessage.)\n *\n * THE DIRTY-TREE ASYMMETRY is deliberate. State A fails OPEN on a dirty tree because `git pull` is\n * then not a guaranteed fast-forward and the agent would be trapped away from the files it needs to\n * resolve the conflict. State B blocks ANYWAY, because its cure — `git checkout -b <new>\n * origin/main` — carries uncommitted changes onto the fresh branch, so there is nothing to resolve\n * and nothing to be trapped by.\n *\n * WHY THIS CANNOT WEDGE: the block is scoped to Read ONLY. Every cure — `git pull origin main`,\n * `pnpm install`, any webpieces upgrade — is a Bash command, and this guard never looks at Bash.\n * So there is no command allowlist to maintain and no way to lock the agent out of its own fix.\n * (`git pull origin main` is explicitly permitted on main by redirect-how-to-merge-main, which\n * returns null when the branch IS main — the two guards are complementary, not stacked.)\n *\n * Everything here is FAIL-OPEN. A guard that blocks reads on bad data is far worse than one that\n * misses; every unknown resolves to \"allow\". The four deliberate escape valves:\n *\n *   1. DIRTY TREE  — uncommitted work on main means `git pull` is not a guaranteed fast-forward.\n *                    Blocking reads there would trap the agent: it could not read the files it\n *                    needs to resolve the very conflict blocking it. Allow. (State A ONLY — see\n *                    the dirty-tree asymmetry above.)\n *   2. CACHE LAG   — we do NOT compare hashes for equality. The cached `originMain` is written by\n *                    the detached refresher and is arbitrarily old, so `local !== origin` stays\n *                    true for a while AFTER a successful pull, which would spin the agent forever.\n *                    Instead: is the cached origin/main an ANCESTOR of local main? If local main\n *                    already contains it, we are not behind. That flips the instant the pull lands,\n *                    with no refresher round-trip. This is the single most important line here.\n *   3. CONFIG READ — webpieces.config.json stays readable so the agent can always read-then-edit\n *                    it to set `mode: OFF`. Its EDIT is already bypassed in runner.ts + hook-core;\n *                    this closes the read half of that same escape hatch.\n *   4. NO DATA     — no cache, cache for another branch, empty originMain (offline), or no local\n *                    main at all (fresh clone / worktree) → allow.\n *\n * Runs from the Read fast path in hook-core (Read is neither a file-edit nor a bash payload, so it\n * never reaches the runner's rule loop). Fires the detached refresher on every call, which is also\n * what makes reads keep the shared main-sync cache warm for feature-branch-guard.\n */\nexport class ReadStaleGuardRule extends FileRuleBase<ReadStaleGuardConfig> {\n    constructor(config: ReadStaleGuardConfig) { super(config, 'read-stale-guard'); }\n\n    readonly description = 'Block reads on a branch that is stale to read from — a `main` behind origin/main, or a feature branch whose PR is already merged.';\n    override readonly files = ['**/*'];\n    override readonly defaultOptions = {\n        hangTimeoutMinutes: DEFAULT_HANG_TIMEOUT_MINUTES,\n    };\n    readonly fixHint = new FixHint(\n        'This branch is stale to read from — reading it would give you pre-merge/out-of-date content.',\n        'Get onto current code before reading anything else:',\n        [\n            new Option('On main, behind origin/main → git pull origin main. On an already-merged branch → git fetch origin main && git checkout -b <new-branch> origin/main. Then retry the read.', true),\n            new Option('Still allowed right now: EVERY Bash command (installs, upgrades, builds), all Write/Edit, and reading webpieces.config.json.'),\n            new Option('Disable in webpieces.config.json under hookGuards → read-stale-guard (mode OFF) if intentional.'),\n        ],\n    );\n\n    check(ctx: FileContext): readonly Violation[] {\n        // Outside the workspace root — no jurisdiction.\n        if (ctx.relativePath.startsWith('..')) return [];\n\n        const branch = this.currentBranch(ctx.workspaceRoot);\n        if (branch === null) return this.allow(ctx, branch, 'branch-undeterminable (fail-open)');\n\n        // Keep the shared cache warm for the next call. Detached; never blocks this read. Fired for\n        // BOTH states — the merged-branch signal comes out of that same cache.\n        triggerMainSyncRefresh(ctx.workspaceRoot, this.config.hangTimeoutMinutes ?? DEFAULT_HANG_TIMEOUT_MINUTES);\n\n        // Escape valve 3 — the read half of the config escape hatch. Ahead of BOTH states' blocks so\n        // the agent can always read-then-edit the file that turns this guard off.\n        if (this.isConfigFile(ctx.relativePath)) return this.allow(ctx, branch, 'webpieces-config-read (escape hatch)');\n\n        return branch === 'main'\n            ? this.checkStaleMain(ctx, branch)\n            : this.checkMergedBranch(ctx, branch);\n    }\n\n    // State A — on main, possibly behind origin/main.\n    private checkStaleMain(ctx: FileContext, branch: string): readonly Violation[] {\n        const status = readMainSyncStatus(ctx.workspaceRoot);\n        if (status === null) return this.allow(ctx, branch, 'no-sync-cache (fail-open)', 'cache=none');\n\n        const cache = this.cacheSummary(status);\n        if (status.branch !== 'main') return this.allow(ctx, branch, 'stale-cross-branch-cache (fail-open)', cache);\n        // Offline / origin unresolvable, or no local main to compare against.\n        if (status.originMain === '') return this.allow(ctx, branch, 'origin-main-unknown (fail-open)', cache);\n\n        // Escape valve 2 — ancestry, NOT equality. See the class comment.\n        if (this.contains(ctx.workspaceRoot, status.originMain)) {\n            return this.allow(ctx, branch, 'local-main-contains-origin (up to date)', cache);\n        }\n\n        // Escape valve 1 — a dirty tree means the pull is not a clean fast-forward; do not trap\n        // the agent away from the files it needs to resolve it.\n        if (this.isDirty(ctx.workspaceRoot)) {\n            return this.allow(ctx, branch, 'dirty-tree-on-main (fail-open)', cache);\n        }\n\n        return this.block(ctx, branch, 'on-stale-main', this.staleMainMessage(ctx.workspaceRoot), cache);\n    }\n\n    /**\n     * State B — a feature branch whose PR is already merged. Reads a PRE-MERGE snapshot, so every\n     * plan built from it is built on code origin/main has moved past.\n     *\n     * `branchAlreadyMerged` comes straight from the shared cache (the refresher's `gh pr list --state\n     * merged`), so this path spawns nothing. No `gh` / offline → `mergedPr` is '' → not merged → allow,\n     * which is the fail-open direction for free.\n     *\n     * NOTE the missing dirty-tree check: unlike state A, we block a dirty tree too. `git checkout -b\n     * <new> origin/main` carries uncommitted work across, so the agent is never trapped here.\n     */\n    private checkMergedBranch(ctx: FileContext, branch: string): readonly Violation[] {\n        const status = readMainSyncStatus(ctx.workspaceRoot);\n        if (status === null) return this.allow(ctx, branch, 'no-sync-cache (fail-open)', 'cache=none');\n\n        const cache = this.cacheSummary(status);\n        // Cache written for a DIFFERENT branch (just switched; the refresh for this one hasn't landed).\n        // Never block on another branch's signals — this is also what un-blocks the instant the agent\n        // follows the cure and checks out a fresh branch.\n        if (status.branch !== branch) return this.allow(ctx, branch, 'stale-cross-branch-cache (fail-open)', cache);\n        if (!status.branchAlreadyMerged) return this.allow(ctx, branch, 'clean-feature-branch', cache);\n\n        const pr = status.mergedPr !== '' ? status.mergedPr : '?';\n        return this.block(\n            ctx,\n            branch,\n            `already-merged PR#${pr}`,\n            new MergedBranchMessage().forReads(branch, status.mergedPr),\n            cache,\n        );\n    }\n\n    // Is `commit` an ancestor of (i.e. already contained in) HEAD? Local-only and fast — no network.\n    //\n    // spawnSync, not execSync, precisely because the EXIT CODE is the answer and we must tell three\n    // outcomes apart: 0 = ancestor (up to date), 1 = cleanly NOT an ancestor (genuinely behind),\n    // anything else = git could not answer (bad/pruned object, not a repo) which must fail OPEN.\n    // execSync collapses 1 and \"git broke\" into the same thrown Error, so it cannot make that call.\n    // Arg-array form also means the commit hash is never parsed by a shell.\n    private contains(workspaceRoot: string, commit: string): boolean {\n        const result = spawnSync('git', ['merge-base', '--is-ancestor', commit, 'HEAD'], {\n            cwd: workspaceRoot,\n            encoding: 'utf8',\n        });\n        if (result.status === 0) return true;\n        if (result.status === 1) return false;\n        return true; // unknown/failed → treat as \"contained\" so the guard allows\n    }\n\n    private isDirty(workspaceRoot: string): boolean {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const out = execSync('git status --porcelain', {\n                cwd: workspaceRoot,\n                encoding: 'utf8',\n                stdio: ['pipe', 'pipe', 'pipe'],\n            });\n            return out.trim().length > 0;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            // Cannot tell → assume dirty, which is the fail-OPEN direction for this guard.\n            return true;\n        }\n    }\n\n    private isConfigFile(relativePath: string): boolean {\n        return relativePath === 'webpieces.config.json';\n    }\n\n    // How far behind we are, for the message. Best-effort — a bare \"behind\" reads fine without it.\n    private behindCount(workspaceRoot: string): string {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const out = execSync('git rev-list --count HEAD..origin/main', {\n                cwd: workspaceRoot,\n                encoding: 'utf8',\n                stdio: ['pipe', 'pipe', 'pipe'],\n            }).trim();\n            return /^\\d+$/.test(out) ? out : '?';\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return '?';\n        }\n    }\n\n    private staleMainMessage(workspaceRoot: string): string {\n        return [\n            `You are on main and main is ${this.behindCount(workspaceRoot)} commit(s) behind origin/main.`,\n            'Reading files right now would give you STALE content and everything you plan from it',\n            'would be built on code that no longer exists upstream. Reads are blocked until you update.',\n            '',\n            'Run exactly this, then retry the read:',\n            '  git pull origin main',\n            '',\n            'Still allowed while this block is up:',\n            '  - EVERY Bash command (pnpm install, any webpieces upgrade, builds, all git/gh)',\n            '  - All Write/Edit (feature-branch-guard governs those separately)',\n            '  - Reading and editing webpieces.config.json (set read-stale-guard mode OFF to disable)',\n        ].join('\\n');\n    }\n\n    private cacheSummary(status: MainSyncStatus): string {\n        const merged = status.branchAlreadyMerged ? `PR#${status.mergedPr !== '' ? status.mergedPr : '?'}` : 'no';\n        return `cache=${status.branch} localMain=${status.localMain.slice(0, 8)} originMain=${status.originMain.slice(0, 8)} merged=${merged} ts=${status.timestamp}`;\n    }\n\n    private allow(ctx: FileContext, branch: string | null, reason: string, cache: string = '-'): readonly Violation[] {\n        this.logDecision(ctx, branch, 'ALLOW', reason, cache);\n        return [];\n    }\n\n    private block(ctx: FileContext, branch: string, reason: string, message: string, cache: string = '-'): readonly Violation[] {\n        this.logDecision(ctx, branch, 'BLOCK', reason, cache);\n        return [new V(1, ctx.relativePath, message)];\n    }\n\n    private logDecision(ctx: FileContext, branch: string | null, verdict: 'ALLOW' | 'BLOCK', reason: string, cache: string): void {\n        logGuardDecision(\n            ctx.workspaceRoot,\n            new GuardDecision('read-stale-guard', ctx.tool, ctx.relativePath, branch ?? 'unknown', verdict, reason, cache),\n        );\n    }\n\n    /**\n     * The current branch, WITHOUT spawning git on the common path.\n     *\n     * This runs on EVERY read, so it is the one call whose cost actually matters. Spawning\n     * `git rev-parse --abbrev-ref HEAD` measures ~12ms — essentially all process-spawn overhead —\n     * whereas `.git/HEAD` is a single tiny file whose read is microseconds. On a feature branch\n     * (the overwhelmingly common case) that file read is the ONLY work this guard does before\n     * short-circuiting, so reads stay effectively free.\n     *\n     * Falls back to spawning git whenever `.git/HEAD` cannot answer authoritatively:\n     *   - `.git` is a FILE, not a dir → we are in a worktree and HEAD lives elsewhere\n     *   - detached HEAD → the file holds a raw sha, not a `ref:` line\n     *   - anything unreadable/unexpected\n     * The fallback is correct in all those cases; it is just slower, and they are rare.\n     */\n    private currentBranch(workspaceRoot: string): string | null {\n        const fromHead = this.branchFromGitHead(workspaceRoot);\n        if (fromHead !== null) return fromHead;\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return execSync('git rev-parse --abbrev-ref HEAD', {\n                cwd: workspaceRoot,\n                encoding: 'utf8',\n                stdio: ['pipe', 'pipe', 'pipe'],\n            }).trim();\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n\n    // Parse `.git/HEAD` (\"ref: refs/heads/<branch>\"). null = cannot answer, caller must fall back.\n    private branchFromGitHead(workspaceRoot: string): string | null {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const gitPath = path.join(workspaceRoot, '.git');\n            // A worktree/submodule has `.git` as a file pointing at the real gitdir — HEAD is not here.\n            if (!fs.statSync(gitPath).isDirectory()) return null;\n            const head = fs.readFileSync(path.join(gitPath, 'HEAD'), 'utf8').trim();\n            const match = /^ref:\\s*refs\\/heads\\/(.+)$/.exec(head);\n            return match ? match[1] : null; // no match = detached HEAD → fall back\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n}\n"]}
+{"version":3,"file":"read-stale-guard.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/read-stale-guard.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync, spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\nimport {\n    ReadStaleGuardConfig,\n    DEFAULT_HANG_TIMEOUT_MINUTES,\n    readMainSyncStatus,\n    MainSyncStatus,\n} from '@webpieces/rules-config';\n\nimport type { FileContext, Violation } from '../types';\nimport { Violation as V } from '../types';\nimport { FileRuleBase } from '../rule-base';\nimport { FixHint, Option } from '../fix-hint';\nimport { toError } from '../to-error';\nimport { triggerMainSyncRefresh } from '../main-sync-refresh';\nimport { logGuardDecision, GuardDecision } from '../decision-log';\nimport { MergedBranchMessage } from './merged-branch-message';\nimport { TreeRecovery } from './tree-recovery';\n\n/**\n * Blocks READS while the checked-out branch is a stale place to read from. TWO states:\n *\n *   A. on `main`, and local main is BEHIND origin/main\n *   B. on a feature branch whose PR is ALREADY MERGED (a pre-merge snapshot; origin/main has moved\n *      past it and a squash merge means its HEAD is not even an ancestor of main)\n *\n * WHY READ, of all tools: either state means the AI reads stale FILE CONTENT and then reasons,\n * plans and writes against code that no longer exists upstream. Blocking the write is too late —\n * the bad premise is already in context. So the block lands on the read. (feature-branch-guard\n * blocks the WRITE in state B; this guard is the read-side half of that same protection, and the\n * two share one recovery message via MergedBranchMessage.)\n *\n * THE DIRTY-TREE ASYMMETRY is deliberate. State A fails OPEN on a dirty tree because `git pull` is\n * then not a guaranteed fast-forward and the agent would be trapped away from the files it needs to\n * resolve the conflict. State B blocks ANYWAY, because its cure — `git checkout -b <new>\n * origin/main` — carries uncommitted changes onto the fresh branch, so there is nothing to resolve\n * and nothing to be trapped by.\n *\n * WHY THIS CANNOT WEDGE: the block is scoped to Read ONLY. Every cure — `git pull origin main`,\n * `pnpm install`, any webpieces upgrade — is a Bash command, and this guard never looks at Bash.\n * So there is no command allowlist to maintain and no way to lock the agent out of its own fix.\n * (`git pull origin main` is explicitly permitted on main by redirect-how-to-merge-main, which\n * returns null when the branch IS main — the two guards are complementary, not stacked.)\n *\n * Everything here is FAIL-OPEN. A guard that blocks reads on bad data is far worse than one that\n * misses; every unknown resolves to \"allow\". The four deliberate escape valves:\n *\n *   1. DIRTY TREE  — uncommitted work on main means `git pull` is not a guaranteed fast-forward.\n *                    Blocking reads there would trap the agent: it could not read the files it\n *                    needs to resolve the very conflict blocking it. Allow. (State A ONLY — see\n *                    the dirty-tree asymmetry above.)\n *   2. CACHE LAG   — we do NOT compare hashes for equality. The cached `originMain` is written by\n *                    the detached refresher and is arbitrarily old, so `local !== origin` stays\n *                    true for a while AFTER a successful pull, which would spin the agent forever.\n *                    Instead: is the cached origin/main an ANCESTOR of local main? If local main\n *                    already contains it, we are not behind. That flips the instant the pull lands,\n *                    with no refresher round-trip. This is the single most important line here.\n *   3. CONFIG READ — webpieces.config.json stays readable so the agent can always read-then-edit\n *                    it to set `mode: OFF`. Its EDIT is already bypassed in runner.ts + hook-core;\n *                    this closes the read half of that same escape hatch.\n *   4. NO DATA     — no cache, cache for another branch, empty originMain (offline), or no local\n *                    main at all (fresh clone / worktree) → allow.\n *\n * Runs from the Read fast path in hook-core (Read is neither a file-edit nor a bash payload, so it\n * never reaches the runner's rule loop). Fires the detached refresher on every call, which is also\n * what makes reads keep the shared main-sync cache warm for feature-branch-guard.\n */\nexport class ReadStaleGuardRule extends FileRuleBase<ReadStaleGuardConfig> {\n    constructor(config: ReadStaleGuardConfig) { super(config, 'read-stale-guard'); }\n\n    readonly description = 'Block reads on a branch that is stale to read from — a `main` behind origin/main, or a feature branch whose PR is already merged.';\n    override readonly files = ['**/*'];\n    override readonly defaultOptions = {\n        hangTimeoutMinutes: DEFAULT_HANG_TIMEOUT_MINUTES,\n    };\n    readonly fixHint = new FixHint(\n        'This branch is stale to read from — reading it would give you pre-merge/out-of-date content.',\n        'Get onto current code before reading anything else:',\n        [\n            new Option('On main, behind origin/main → git pull origin main. On an already-merged branch → git fetch origin main && git checkout -b <new-branch> origin/main. Then retry the read.', true),\n            new Option('Still allowed right now: EVERY Bash command (installs, upgrades, builds), all Write/Edit, and reading webpieces.config.json.'),\n            new Option('Disable in webpieces.config.json under hookGuards → read-stale-guard (mode OFF) if intentional.'),\n        ],\n    );\n\n    check(ctx: FileContext): readonly Violation[] {\n        // Outside the workspace root — no jurisdiction.\n        if (ctx.relativePath.startsWith('..')) return [];\n\n        const branch = this.currentBranch(ctx.workspaceRoot);\n        if (branch === null) return this.allow(ctx, branch, 'branch-undeterminable (fail-open)');\n\n        // Keep the shared cache warm for the next call. Detached; never blocks this read. Fired for\n        // BOTH states — the merged-branch signal comes out of that same cache.\n        triggerMainSyncRefresh(ctx.workspaceRoot, this.config.hangTimeoutMinutes ?? DEFAULT_HANG_TIMEOUT_MINUTES);\n\n        // Escape valve 3 — the read half of the config escape hatch. Ahead of BOTH states' blocks so\n        // the agent can always read-then-edit the file that turns this guard off.\n        if (this.isConfigFile(ctx.relativePath)) return this.allow(ctx, branch, 'webpieces-config-read (escape hatch)');\n\n        return branch === 'main'\n            ? this.checkStaleMain(ctx, branch)\n            : this.checkMergedBranch(ctx, branch);\n    }\n\n    // State A — on main, possibly behind origin/main.\n    private checkStaleMain(ctx: FileContext, branch: string): readonly Violation[] {\n        const status = readMainSyncStatus(ctx.workspaceRoot);\n        if (status === null) return this.allow(ctx, branch, 'no-sync-cache (fail-open)', 'cache=none');\n\n        const cache = this.cacheSummary(status);\n        if (status.branch !== 'main') return this.allow(ctx, branch, 'stale-cross-branch-cache (fail-open)', cache);\n        // Offline / origin unresolvable, or no local main to compare against.\n        if (status.originMain === '') return this.allow(ctx, branch, 'origin-main-unknown (fail-open)', cache);\n\n        // Escape valve 2 — ancestry, NOT equality. See the class comment.\n        if (this.contains(ctx.workspaceRoot, status.originMain)) {\n            return this.allow(ctx, branch, 'local-main-contains-origin (up to date)', cache);\n        }\n\n        // Escape valve 1 — a dirty tree means the pull is not a clean fast-forward; do not trap\n        // the agent away from the files it needs to resolve it.\n        if (this.isDirty(ctx.workspaceRoot)) {\n            return this.allow(ctx, branch, 'dirty-tree-on-main (fail-open)', cache);\n        }\n\n        return this.block(ctx, branch, 'on-stale-main', this.staleMainMessage(ctx.workspaceRoot), cache);\n    }\n\n    /**\n     * State B — a feature branch whose PR is already merged. Reads a PRE-MERGE snapshot, so every\n     * plan built from it is built on code origin/main has moved past.\n     *\n     * `branchAlreadyMerged` comes straight from the shared cache (the refresher's `gh pr list --state\n     * merged`), so this path spawns nothing. No `gh` / offline → `mergedPr` is '' → not merged → allow,\n     * which is the fail-open direction for free.\n     *\n     * The DIRTY-TREE escape valve is the same one state A has, for the same reason: uncommitted work\n     * on a merged branch is work that exists nowhere else, and rescuing it means READING the files it\n     * touches. `git checkout -b <new> origin/main` usually carries those changes across — but when it\n     * does not (an overlapping change landed in main), a blocked read is an agent that cannot even\n     * see what it is about to lose. feature-branch-guard still blocks the EDITS, so the state is\n     * surfaced loudly either way; we just refuse to cut off the rescue path.\n     */\n    private checkMergedBranch(ctx: FileContext, branch: string): readonly Violation[] {\n        const status = readMainSyncStatus(ctx.workspaceRoot);\n        if (status === null) return this.allow(ctx, branch, 'no-sync-cache (fail-open)', 'cache=none');\n\n        const cache = this.cacheSummary(status);\n        // Cache written for a DIFFERENT branch (just switched; the refresh for this one hasn't landed).\n        // Never block on another branch's signals — this is also what un-blocks the instant the agent\n        // follows the cure and checks out a fresh branch.\n        if (status.branch !== branch) return this.allow(ctx, branch, 'stale-cross-branch-cache (fail-open)', cache);\n        if (!status.branchAlreadyMerged) return this.allow(ctx, branch, 'clean-feature-branch', cache);\n        if (this.isDirty(ctx.workspaceRoot)) {\n            return this.allow(ctx, branch, 'dirty-merged-branch (fail-open)', cache);\n        }\n\n        const pr = status.mergedPr !== '' ? status.mergedPr : '?';\n        return this.block(\n            ctx,\n            branch,\n            `already-merged PR#${pr}`,\n            this.mergedMessage(ctx.workspaceRoot, branch, status.mergedPr),\n            cache,\n        );\n    }\n\n    // The merged-branch text, told in the flavour of the tree we are standing in: a linked worktree\n    // is told to open a NEW worktree off origin/main and reap this dead one; the primary clone is\n    // told to branch off origin/main. Neither is ever told to `git checkout main` (fatal in a\n    // worktree). Detection is one statSync — see WorktreeService.isLinkedWorktree.\n    private mergedMessage(workspaceRoot: string, branch: string, mergedPr: string): string {\n        const recovery = new TreeRecovery();\n        return new MergedBranchMessage().forReads(\n            branch, mergedPr, recovery.kindOf(workspaceRoot), workspaceRoot,\n        );\n    }\n\n    // Is `commit` an ancestor of (i.e. already contained in) HEAD? Local-only and fast — no network.\n    //\n    // spawnSync, not execSync, precisely because the EXIT CODE is the answer and we must tell three\n    // outcomes apart: 0 = ancestor (up to date), 1 = cleanly NOT an ancestor (genuinely behind),\n    // anything else = git could not answer (bad/pruned object, not a repo) which must fail OPEN.\n    // execSync collapses 1 and \"git broke\" into the same thrown Error, so it cannot make that call.\n    // Arg-array form also means the commit hash is never parsed by a shell.\n    private contains(workspaceRoot: string, commit: string): boolean {\n        const result = spawnSync('git', ['merge-base', '--is-ancestor', commit, 'HEAD'], {\n            cwd: workspaceRoot,\n            encoding: 'utf8',\n        });\n        if (result.status === 0) return true;\n        if (result.status === 1) return false;\n        return true; // unknown/failed → treat as \"contained\" so the guard allows\n    }\n\n    private isDirty(workspaceRoot: string): boolean {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const out = execSync('git status --porcelain', {\n                cwd: workspaceRoot,\n                encoding: 'utf8',\n                stdio: ['pipe', 'pipe', 'pipe'],\n            });\n            return out.trim().length > 0;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            // Cannot tell → assume dirty, which is the fail-OPEN direction for this guard.\n            return true;\n        }\n    }\n\n    private isConfigFile(relativePath: string): boolean {\n        return relativePath === 'webpieces.config.json';\n    }\n\n    // How far behind we are, for the message. Best-effort — a bare \"behind\" reads fine without it.\n    private behindCount(workspaceRoot: string): string {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const out = execSync('git rev-list --count HEAD..origin/main', {\n                cwd: workspaceRoot,\n                encoding: 'utf8',\n                stdio: ['pipe', 'pipe', 'pipe'],\n            }).trim();\n            return /^\\d+$/.test(out) ? out : '?';\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return '?';\n        }\n    }\n\n    private staleMainMessage(workspaceRoot: string): string {\n        return [\n            `You are on main and main is ${this.behindCount(workspaceRoot)} commit(s) behind origin/main.`,\n            'Reading files right now would give you STALE content and everything you plan from it',\n            'would be built on code that no longer exists upstream. Reads are blocked until you update.',\n            '',\n            'Run exactly this, then retry the read:',\n            '  git pull origin main',\n            '',\n            'Still allowed while this block is up:',\n            '  - EVERY Bash command (pnpm install, any webpieces upgrade, builds, all git/gh)',\n            '  - All Write/Edit (feature-branch-guard governs those separately)',\n            '  - Reading and editing webpieces.config.json (set read-stale-guard mode OFF to disable)',\n        ].join('\\n');\n    }\n\n    private cacheSummary(status: MainSyncStatus): string {\n        const merged = status.branchAlreadyMerged ? `PR#${status.mergedPr !== '' ? status.mergedPr : '?'}` : 'no';\n        return `cache=${status.branch} localMain=${status.localMain.slice(0, 8)} originMain=${status.originMain.slice(0, 8)} merged=${merged} ts=${status.timestamp}`;\n    }\n\n    private allow(ctx: FileContext, branch: string | null, reason: string, cache: string = '-'): readonly Violation[] {\n        this.logDecision(ctx, branch, 'ALLOW', reason, cache);\n        return [];\n    }\n\n    private block(ctx: FileContext, branch: string, reason: string, message: string, cache: string = '-'): readonly Violation[] {\n        this.logDecision(ctx, branch, 'BLOCK', reason, cache);\n        return [new V(1, ctx.relativePath, message)];\n    }\n\n    private logDecision(ctx: FileContext, branch: string | null, verdict: 'ALLOW' | 'BLOCK', reason: string, cache: string): void {\n        logGuardDecision(\n            ctx.workspaceRoot,\n            new GuardDecision('read-stale-guard', ctx.tool, ctx.relativePath, branch ?? 'unknown', verdict, reason, cache),\n        );\n    }\n\n    /**\n     * The current branch, WITHOUT spawning git on the common path.\n     *\n     * This runs on EVERY read, so it is the one call whose cost actually matters. Spawning\n     * `git rev-parse --abbrev-ref HEAD` measures ~12ms — essentially all process-spawn overhead —\n     * whereas `.git/HEAD` is a single tiny file whose read is microseconds. On a feature branch\n     * (the overwhelmingly common case) that file read is the ONLY work this guard does before\n     * short-circuiting, so reads stay effectively free.\n     *\n     * Falls back to spawning git whenever `.git/HEAD` cannot answer authoritatively:\n     *   - `.git` is a FILE, not a dir → we are in a worktree and HEAD lives elsewhere\n     *   - detached HEAD → the file holds a raw sha, not a `ref:` line\n     *   - anything unreadable/unexpected\n     * The fallback is correct in all those cases; it is just slower, and they are rare.\n     */\n    private currentBranch(workspaceRoot: string): string | null {\n        const fromHead = this.branchFromGitHead(workspaceRoot);\n        if (fromHead !== null) return fromHead;\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return execSync('git rev-parse --abbrev-ref HEAD', {\n                cwd: workspaceRoot,\n                encoding: 'utf8',\n                stdio: ['pipe', 'pipe', 'pipe'],\n            }).trim();\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n\n    // Parse `.git/HEAD` (\"ref: refs/heads/<branch>\"). null = cannot answer, caller must fall back.\n    private branchFromGitHead(workspaceRoot: string): string | null {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const gitPath = path.join(workspaceRoot, '.git');\n            // A worktree/submodule has `.git` as a file pointing at the real gitdir — HEAD is not here.\n            if (!fs.statSync(gitPath).isDirectory()) return null;\n            const head = fs.readFileSync(path.join(gitPath, 'HEAD'), 'utf8').trim();\n            const match = /^ref:\\s*refs\\/heads\\/(.+)$/.exec(head);\n            return match ? match[1] : null; // no match = detached HEAD → fall back\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n}\n"]}

package/src/core/rules/redirect-how-to-merge-main.d.ts

@@ -4,6 +4,7 @@ import { BashRuleBase } from '../rule-base';
 import { FixHint } from '../fix-hint';
 export declare class RedirectHowToMergeMainRule extends BashRuleBase<RedirectHowToMergeMainConfig> {
     private readonly scanner;
+    private readonly recovery;
     constructor(config: RedirectHowToMergeMainConfig);
     readonly description = "Block ALL `git merge`/`git rebase` (any branch, any form) and `git pull origin main` on a feature branch. Use the squash-update process instead.";
     readonly fixHint: FixHint;