@webpieces/ai-hook-rules 0.4.428 → 0.4.429

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/ai-hook-rules",
-  "version": "0.4.428",
+  "version": "0.4.429",
   "description": "Pluggable write-time validation framework for AI coding agents (@webpieces/ai-hook-rules). Claude Code PreToolUse + openclaw before_tool_call adapters share one rule engine.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -32,7 +32,7 @@
     "directory": "packages/tooling/ai-hook-rules"
   },
   "dependencies": {
-    "@webpieces/rules-config": "0.4.428"
+    "@webpieces/rules-config": "0.4.429"
   },
   "publishConfig": {
     "access": "public"

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

@@ -34,7 +34,7 @@ class FeatureBranchGuardRule extends rule_base_1.FileRuleBase {
     };
     fixHint = new fix_hint_1.FixHint('You are not on a clean, up-to-date feature branch.', 'You must be on a clean, up-to-date feature branch to edit code. Pick one:', [
         new fix_hint_1.Option('On main → create a feature branch. Already merged → branch off fresh main.', true),
-        new fix_hint_1.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`.'),
+        new fix_hint_1.Option('main moved/conflicts, NO PR yet → `pnpm wp-start-update` (merge), `/wp-merge` (resolve), `pnpm wp-finish-update`. An OPEN PR? then you MUST use `pnpm wp-start-upsert-pr` → `/wp-merge` → `pnpm wp-finish-upsert-pr` (the merge rewrites the branch, so the PR must be re-pointed in the same run). Never mix a start from one pair with a finish from the other.'),
         new fix_hint_1.Option('Disable in webpieces.config.json under feature-branch-guard (mode OFF) if intentional.'),
     ]);
     check(ctx) {
@@ -140,29 +140,28 @@ class FeatureBranchGuardRule extends rule_base_1.FileRuleBase {
         // Steer EARLY: if a PR already tracks this branch, the update-only flow would just fail-fast
         // (a 3-point update strands the PR on the old branch generation), so recommend ONLY the PR
         // flow and don't waste the AI's tokens on wp-start-update.
+        const guidance = new rules_config_1.SyncFlowGuidance();
+        // An OPEN PR removes the choice, so print ONLY the PR flow here — showing the update-only flow
+        // as if it were an option just burns tokens on a command that fail-fasts.
         if (openPr !== '') {
-            return header.concat([
-                `An OPEN PR (#${openPr}) already tracks this branch, so you MUST use the PR flow (it`,
-                're-merges main AND updates the PR — the update-only flow would strand the PR on the',
-                'old branch generation):',
-                '  1. pnpm wp-start-upsert-pr   ← merges main + writes 3-point context',
-                '  2. /wp-merge                 ← resolve each conflicted file (only if conflicts)',
-                '  3. pnpm wp-finish-upsert-pr  ← validate, build, push, upsert the PR',
-            ]).join('\n');
+            return header
+                .concat([
+                `An OPEN PR (#${openPr}) already tracks this branch, so the PR flow is the ONLY option`,
+                'here — it re-merges main AND re-points the PR in the same run:',
+                '',
+            ])
+                .concat(guidance.prFlow())
+                .concat(['', ...guidance.whyPrForcesFlowB()])
+                .join('\n');
         }
-        return header.concat([
-            'You must merge main in before editing further. If you are mid-work and just want to keep',
-            'editing (no PR yet), use the UPDATE-ONLY flow:',
-            '  1. pnpm wp-start-update   ← merges main (auto-finalizes if clean; renames <branch>wpN → wpN+1)',
-            '  2. /wp-merge              ← resolve each conflicted file (only if there are conflicts)',
-            '  3. pnpm wp-finish-update  ← finalize the merge (only after resolving)',
+        return header
+            .concat([
+            'You must merge main in before editing further. No PR is open for this branch, so flow A',
+            'below is the one to use — but use flow B the moment a PR exists:',
             '',
-            'If you already have an OPEN PR for this branch, use the PR flow instead (wp-start-update',
-            'refuses when a PR exists — it would strand the PR on the old branch generation):',
-            '  1. pnpm wp-start-upsert-pr   ← merges main + writes 3-point context',
-            '  2. /wp-merge                 ← resolve each conflicted file',
-            '  3. pnpm wp-finish-upsert-pr  ← validate, build, push, upsert the PR',
-        ]).join('\n');
+        ])
+            .concat(guidance.flows())
+            .join('\n');
     }
     noForkPointMessage(branch) {
         return [

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';\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"]}
+{"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    SyncFlowGuidance,\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, NO PR yet → `pnpm wp-start-update` (merge), `/wp-merge` (resolve), `pnpm wp-finish-update`. An OPEN PR? then you MUST use `pnpm wp-start-upsert-pr` → `/wp-merge` → `pnpm wp-finish-upsert-pr` (the merge rewrites the branch, so the PR must be re-pointed in the same run). Never mix a start from one pair with a finish from the other.'),\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        const guidance = new SyncFlowGuidance();\n        // An OPEN PR removes the choice, so print ONLY the PR flow here — showing the update-only flow\n        // as if it were an option just burns tokens on a command that fail-fasts.\n        if (openPr !== '') {\n            return header\n                .concat([\n                    `An OPEN PR (#${openPr}) already tracks this branch, so the PR flow is the ONLY option`,\n                    'here — it re-merges main AND re-points the PR in the same run:',\n                    '',\n                ])\n                .concat(guidance.prFlow())\n                .concat(['', ...guidance.whyPrForcesFlowB()])\n                .join('\\n');\n        }\n        return header\n            .concat([\n                'You must merge main in before editing further. No PR is open for this branch, so flow A',\n                'below is the one to use — but use flow B the moment a PR exists:',\n                '',\n            ])\n            .concat(guidance.flows())\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/redirect-how-to-merge-main.js

@@ -9,21 +9,27 @@ const fix_hint_1 = require("../fix-hint");
 const command_scan_1 = require("../command-scan");
 const tree_recovery_1 = require("./tree-recovery");
 const INSTRUCT_FILE = 'webpieces.git-workflow.md';
-const UPDATE_COMMAND = 'pnpm wp-start-update';
+const GUIDANCE = new rules_config_1.SyncFlowGuidance();
 const FIX_HINT = new fix_hint_1.FixHint('`git merge` / `git rebase` are never run by AI — on any branch, in any form.', 'To bring main\'s changes into your feature branch:\n'
-    + `  ${UPDATE_COMMAND}        (then: pnpm wp-finish-upsert-pr)\n`
-    + 'That does a 3-point merge (fork-point=A, feature-HEAD=B, main-HEAD=C), which is what keeps PR\n'
-    + 'diffs clean. A raw `git merge`/`git rebase` destroys the fork-point system. The gated commands\n'
-    + 'merge internally as child processes this hook never sees, so they are unaffected by this guard.\n'
+    + '\n'
+    + GUIDANCE.flows().join('\n') + '\n'
+    + '\n'
+    + 'Either flow does a 3-point merge (fork-point=A, feature-HEAD=B, main-HEAD=C), which is what\n'
+    + 'keeps PR diffs clean. A raw `git merge`/`git rebase` destroys the fork-point system. The gated\n'
+    + 'commands merge internally as child processes this hook never sees, so they are unaffected by\n'
+    + 'this guard.\n'
+    + '\n'
+    + GUIDANCE.readOnlyChecks().join('\n') + '\n'
     + '\n'
     + 'If you believe a raw merge/rebase is genuinely required, do NOT run it and do NOT work around\n'
     + 'this guard. STOP and ask the HUMAN to run that exact command themselves — and when you ask,\n'
     + 'warn them, in these words:\n'
     + '\n'
     + '  "I am asking you to run a raw git merge/rebase. This is almost always the WRONG call —\n'
-    + `   \`${UPDATE_COMMAND}\` / \`pnpm wp-finish-upsert-pr\` does a 3-point merge and is the correct\n`
-    + '   flow. Please push back and tell me to use the 3-point merge instead, unless you are certain\n'
-    + '   this is a genuine exception."\n'
+    + '   the gated pair for my situation (`wp-start-update` → `wp-finish-update` with no PR, or\n'
+    + '   `wp-start-upsert-pr` → `wp-finish-upsert-pr` when a PR is open) does a 3-point merge and is\n'
+    + '   the correct flow. Please push back and tell me to use the 3-point merge instead, unless you\n'
+    + '   are certain this is a genuine exception."\n'
     + '\n'
     + 'READ the instruct-ai git-workflow doc at the absolute path on the violation line above for the\n'
     + 'full flow (incl. worktrees).\n'
@@ -33,6 +39,8 @@ const FIX_HINT = new fix_hint_1.FixHint('`git merge` / `git rebase` are never ru
 // protects. They stay allowed so a repo left mid-operation (e.g. by a human-run rebase) can still be
 // cleaned up. `--continue` is deliberately NOT here: it COMPLETES the operation.
 const UNDO_FLAG = /--(?:abort|quit)\b/;
+// Typed as a query ("would this fast-forward?"), but a successful --ff-only IS the merge.
+const FF_ONLY = /--ff-only\b/;
 function truncate(s) {
     const MAX = 120;
     return s.length <= MAX ? s : s.slice(0, MAX) + '…';
@@ -66,7 +74,12 @@ class RedirectHowToMergeMainRule extends rule_base_1.BashRuleBase {
         if (this.scanner.invokesGit(segment, 'merge') || this.scanner.invokesGit(segment, 'rebase')) {
             if (UNDO_FLAG.test(segment))
                 return null;
-            return this.block(ctx, segment, 'Direct `git merge`/`git rebase` is blocked — AI never runs it, on any branch.');
+            // `--ff-only` reads like a probe ("can I fast-forward?") but it MUTATES whenever the answer
+            // is yes, so say that here — the AI that typed it was usually only trying to look.
+            const probe = FF_ONLY.test(segment)
+                ? ' `--ff-only` is NOT a read-only check — it moves your branch whenever it succeeds; see the read-only checks below.'
+                : '';
+            return this.block(ctx, segment, 'Direct `git merge`/`git rebase` is blocked — AI never runs it, on any branch.' + probe);
         }
         // 2. pull: unlike merge/rebase this DOES retain a legitimate on-main form
         // (`git checkout main && git pull origin main`), so it must consult the branch — which is
@@ -100,7 +113,7 @@ class RedirectHowToMergeMainRule extends rule_base_1.BashRuleBase {
     }
     block(ctx, segment, what) {
         const docPath = new rules_config_1.RepoRootFinder().instructAiDocPath(ctx.workspaceRoot, INSTRUCT_FILE);
-        return new types_1.Violation(1, truncate(segment), `${what} Use '${UPDATE_COMMAND}' (3-point merge). If you truly need a raw merge/rebase, ask the HUMAN to run it — and warn them to push back. Full flow: READ ${docPath}.`);
+        return new types_1.Violation(1, truncate(segment), `${what} Use the gated 3-point flow instead: 'pnpm wp-start-update' → 'pnpm wp-finish-update' when NO PR is open, or 'pnpm wp-start-upsert-pr' → 'pnpm wp-finish-upsert-pr' when a PR IS open (required then — the merge rewrites the branch and the PR must be re-pointed in the same run). If you truly need a raw merge/rebase, ask the HUMAN to run it — and warn them to push back. Full flow: READ ${docPath}.`);
     }
 }
 exports.RedirectHowToMergeMainRule = RedirectHowToMergeMainRule;

package/src/core/rules/redirect-how-to-merge-main.js.map

@@ -1 +1 @@
-{"version":3,"file":"redirect-how-to-merge-main.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/redirect-how-to-merge-main.ts"],"names":[],"mappings":";;;AAAA,iDAAyC;AAEzC,0DAAuF;AAGvF,oCAA0C;AAC1C,4CAA4C;AAC5C,0CAAsC;AACtC,kDAAiD;AACjD,mDAA+C;AAE/C,MAAM,aAAa,GAAG,2BAA2B,CAAC;AAClD,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAE9C,MAAM,QAAQ,GAAG,IAAI,kBAAO,CACxB,8EAA8E,EAC9E,sDAAsD;MACpD,KAAK,cAAc,4CAA4C;MAC/D,iGAAiG;MACjG,kGAAkG;MAClG,mGAAmG;MACnG,IAAI;MACJ,iGAAiG;MACjG,+FAA+F;MAC/F,8BAA8B;MAC9B,IAAI;MACJ,4FAA4F;MAC5F,QAAQ,cAAc,6EAA6E;MACnG,kGAAkG;MAClG,oCAAoC;MACpC,IAAI;MACJ,kGAAkG;MAClG,gCAAgC;MAChC,oDAAoD,CACzD,CAAC;AAEF,uGAAuG;AACvG,+FAA+F;AAC/F,qGAAqG;AACrG,iFAAiF;AACjF,MAAM,SAAS,GAAG,oBAAoB,CAAC;AAEvC,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,kGAAkG;AAClG,gGAAgG;AAChG,MAAM,oBAAoB,GAAG,kDAAkD,CAAC;AAEhF,MAAa,0BAA2B,SAAQ,wBAA0C;IACrE,OAAO,GAAG,IAAI,6BAAc,EAAE,CAAC;IAC/B,QAAQ,GAAG,IAAI,4BAAY,EAAE,CAAC;IAE/C,YAAY,MAAoC,IAAI,KAAK,CAAC,MAAM,EAAE,4BAA4B,CAAC,CAAC,CAAC,CAAC;IAEzF,WAAW,GAAG,kJAAkJ,CAAC;IACjK,OAAO,GAAG,QAAQ,CAAC;IAE5B,KAAK,CAAC,GAAgB;QAClB,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9D,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAClD,IAAI,SAAS,KAAK,IAAI;gBAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,EAAE,CAAC;IACd,CAAC;IAEO,YAAY,CAAC,GAAgB,EAAE,OAAe;QAClD,uEAAuE;QACvE,EAAE;QACF,+FAA+F;QAC/F,0FAA0F;QAC1F,4FAA4F;QAC5F,0FAA0F;QAC1F,6FAA6F;QAC7F,uEAAuE;QACvE,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC;YAC1F,IAAI,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC;gBAAE,OAAO,IAAI,CAAC;YACzC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,+EAA+E,CAAC,CAAC;QACrH,CAAC;QAED,0EAA0E;QAC1E,0FAA0F;QAC1F,iFAAiF;QACjF,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAChF,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACxC,CAAC;QAED,OAAO,IAAI,CAAC;IAChB,CAAC;IAEO,SAAS,CAAC,GAAgB,EAAE,OAAe;QAC/C,IAAI,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACzC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,iFAAiF,CAAC,CAAC;QACvH,CAAC;QACD,wFAAwF;QACxF,0FAA0F;QAC1F,2FAA2F;QAC3F,4EAA4E;QAC5E,IAAI,oCAAoC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACzD,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,KAAK,UAAU;gBAAE,OAAO,IAAI,CAAC;YACxE,sFAAsF;YACtF,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3G,CAAC;QAED,MAAM,aAAa,GAAG,IAAA,wBAAQ,EAAC,iCAAiC,EAAE;YAC9D,GAAG,EAAE,GAAG,CAAC,aAAa;YACtB,QAAQ,EAAE,MAAM;SACnB,CAAC,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,aAAa,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;QAE1C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,qCAAqC,aAAa,eAAe,CAAC,CAAC;IACvG,CAAC;IAEO,KAAK,CAAC,GAAgB,EAAE,OAAe,EAAE,IAAY;QACzD,MAAM,OAAO,GAAG,IAAI,6BAAc,EAAE,CAAC,iBAAiB,CAAC,GAAG,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;QACzF,OAAO,IAAI,iBAAC,CACR,CAAC,EACD,QAAQ,CAAC,OAAO,CAAC,EACjB,GAAG,IAAI,SAAS,cAAc,kIAAkI,OAAO,GAAG,CAC7K,CAAC;IACN,CAAC;CACJ;AAxED,gEAwEC","sourcesContent":["import { execSync } from 'child_process';\n\nimport { RedirectHowToMergeMainConfig, RepoRootFinder } 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 { CommandScanner } from '../command-scan';\nimport { TreeRecovery } from './tree-recovery';\n\nconst INSTRUCT_FILE = 'webpieces.git-workflow.md';\nconst UPDATE_COMMAND = 'pnpm wp-start-update';\n\nconst FIX_HINT = new FixHint(\n    '`git merge` / `git rebase` are never run by AI — on any branch, in any form.',\n    'To bring main\\'s changes into your feature branch:\\n'\n    + `  ${UPDATE_COMMAND}        (then: pnpm wp-finish-upsert-pr)\\n`\n    + 'That does a 3-point merge (fork-point=A, feature-HEAD=B, main-HEAD=C), which is what keeps PR\\n'\n    + 'diffs clean. A raw `git merge`/`git rebase` destroys the fork-point system. The gated commands\\n'\n    + 'merge internally as child processes this hook never sees, so they are unaffected by this guard.\\n'\n    + '\\n'\n    + 'If you believe a raw merge/rebase is genuinely required, do NOT run it and do NOT work around\\n'\n    + 'this guard. STOP and ask the HUMAN to run that exact command themselves — and when you ask,\\n'\n    + 'warn them, in these words:\\n'\n    + '\\n'\n    + '  \"I am asking you to run a raw git merge/rebase. This is almost always the WRONG call —\\n'\n    + `   \\`${UPDATE_COMMAND}\\` / \\`pnpm wp-finish-upsert-pr\\` does a 3-point merge and is the correct\\n`\n    + '   flow. Please push back and tell me to use the 3-point merge instead, unless you are certain\\n'\n    + '   this is a genuine exception.\"\\n'\n    + '\\n'\n    + 'READ the instruct-ai git-workflow doc at the absolute path on the violation line above for the\\n'\n    + 'full flow (incl. worktrees).\\n'\n    + 'Add that info to memory so you remember next time.',\n);\n\n// `git merge --abort` / `git rebase --abort|--quit` UNDO an in-progress operation — they cannot create\n// a merge commit or rewrite history, so they cannot violate the fork-point invariant this rule\n// protects. They stay allowed so a repo left mid-operation (e.g. by a human-run rebase) can still be\n// cleaned up. `--continue` is deliberately NOT here: it COMPLETES the operation.\nconst UNDO_FLAG = /--(?:abort|quit)\\b/;\n\nfunction truncate(s: string): string {\n    const MAX = 120;\n    return s.length <= MAX ? s : s.slice(0, MAX) + '…';\n}\n\n// Switches to a branch OTHER than main. `git branch -D <x>` is not a checkout so it does not trip\n// this; `checkout main` and flag-only forms like `checkout -` do not count as a feature switch.\nconst SWITCHES_TO_NON_MAIN = /git\\s+(?:checkout|switch)\\s+(?!main\\b|-\\s|-$)\\S+/;\n\nexport class RedirectHowToMergeMainRule extends BashRuleBase<RedirectHowToMergeMainConfig> {\n    private readonly scanner = new CommandScanner();\n    private readonly recovery = new TreeRecovery();\n\n    constructor(config: RedirectHowToMergeMainConfig) { super(config, 'redirect-how-to-merge-main'); }\n\n    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.';\n    readonly fixHint = FIX_HINT;\n\n    check(ctx: BashContext): readonly Violation[] {\n        for (const segment of this.scanner.commandSegments(ctx.command)) {\n            const violation = this.checkSegment(ctx, segment);\n            if (violation !== null) return [violation];\n        }\n        return [];\n    }\n\n    private checkSegment(ctx: BashContext, segment: string): Violation | null {\n        // 1. merge/rebase: unconditional block. Deliberately NO branch lookup.\n        //\n        // This rule used to read hook-time HEAD and bail out when it was `main`. But a PreToolUse hook\n        // runs BEFORE the command, so HEAD-at-hook-time is a value the command itself is about to\n        // change: `git checkout feat && git rebase main`, issued while HEAD was still `main` from a\n        // prior cleanup, read as \"we're on main, this is fine\" and was waved through. That is the\n        // incident this rule exists to prevent. Since merge/rebase have no legitimate AI-run form on\n        // ANY branch, there is no branch to consult — and so no HEAD to spoof.\n        if (this.scanner.invokesGit(segment, 'merge') || this.scanner.invokesGit(segment, 'rebase')) {\n            if (UNDO_FLAG.test(segment)) return null;\n            return this.block(ctx, segment, 'Direct `git merge`/`git rebase` is blocked — AI never runs it, on any branch.');\n        }\n\n        // 2. pull: unlike merge/rebase this DOES retain a legitimate on-main form\n        // (`git checkout main && git pull origin main`), so it must consult the branch — which is\n        // exactly why it also needs the branch-switch check that (1) no longer requires.\n        if (this.scanner.invokesGit(segment, 'pull') && /\\borigin\\s+main\\b/.test(segment)) {\n            return this.checkPull(ctx, segment);\n        }\n\n        return null;\n    }\n\n    private checkPull(ctx: BashContext, segment: string): Violation | null {\n        if (SWITCHES_TO_NON_MAIN.test(ctx.command)) {\n            return this.block(ctx, segment, 'Blocked: this command switches to a feature branch and then pulls main into it.');\n        }\n        // The recommended `git checkout main && git pull origin main` — but ONLY in the primary\n        // clone. Inside a linked worktree that checkout FATALS (\"'main' is already checked out at\n        // <primary>\"), so waving it through here hands the AI a command that cannot work and costs\n        // it a turn to discover. Steer to the fetch, which is all a worktree needs.\n        if (/git\\s+(?:checkout|switch)\\s+main\\b/.test(ctx.command)) {\n            if (this.recovery.kindOf(ctx.workspaceRoot) !== 'worktree') return null;\n            // updateMainSteps already explains the worktree/fatal reasoning — don't say it twice.\n            return this.block(ctx, segment, ['Blocked.', ...this.recovery.updateMainSteps('worktree')].join('\\n'));\n        }\n\n        const currentBranch = execSync('git rev-parse --abbrev-ref HEAD', {\n            cwd: ctx.workspaceRoot,\n            encoding: 'utf8',\n        }).trim();\n        if (currentBranch === 'main') return null;\n\n        return this.block(ctx, segment, `Pulling main into feature branch '${currentBranch}' is blocked.`);\n    }\n\n    private block(ctx: BashContext, segment: string, what: string): Violation {\n        const docPath = new RepoRootFinder().instructAiDocPath(ctx.workspaceRoot, INSTRUCT_FILE);\n        return new V(\n            1,\n            truncate(segment),\n            `${what} Use '${UPDATE_COMMAND}' (3-point merge). If you truly need a raw merge/rebase, ask the HUMAN to run it — and warn them to push back. Full flow: READ ${docPath}.`,\n        );\n    }\n}\n"]}
+{"version":3,"file":"redirect-how-to-merge-main.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/redirect-how-to-merge-main.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync } from 'child_process';\n\nimport { RedirectHowToMergeMainConfig, RepoRootFinder, SyncFlowGuidance } 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 { CommandScanner } from '../command-scan';\nimport { TreeRecovery } from './tree-recovery';\n\nconst INSTRUCT_FILE = 'webpieces.git-workflow.md';\nconst GUIDANCE = new SyncFlowGuidance();\n\nconst FIX_HINT = new FixHint(\n    '`git merge` / `git rebase` are never run by AI — on any branch, in any form.',\n    'To bring main\\'s changes into your feature branch:\\n'\n    + '\\n'\n    + GUIDANCE.flows().join('\\n') + '\\n'\n    + '\\n'\n    + 'Either flow does a 3-point merge (fork-point=A, feature-HEAD=B, main-HEAD=C), which is what\\n'\n    + 'keeps PR diffs clean. A raw `git merge`/`git rebase` destroys the fork-point system. The gated\\n'\n    + 'commands merge internally as child processes this hook never sees, so they are unaffected by\\n'\n    + 'this guard.\\n'\n    + '\\n'\n    + GUIDANCE.readOnlyChecks().join('\\n') + '\\n'\n    + '\\n'\n    + 'If you believe a raw merge/rebase is genuinely required, do NOT run it and do NOT work around\\n'\n    + 'this guard. STOP and ask the HUMAN to run that exact command themselves — and when you ask,\\n'\n    + 'warn them, in these words:\\n'\n    + '\\n'\n    + '  \"I am asking you to run a raw git merge/rebase. This is almost always the WRONG call —\\n'\n    + '   the gated pair for my situation (`wp-start-update` → `wp-finish-update` with no PR, or\\n'\n    + '   `wp-start-upsert-pr` → `wp-finish-upsert-pr` when a PR is open) does a 3-point merge and is\\n'\n    + '   the correct flow. Please push back and tell me to use the 3-point merge instead, unless you\\n'\n    + '   are certain this is a genuine exception.\"\\n'\n    + '\\n'\n    + 'READ the instruct-ai git-workflow doc at the absolute path on the violation line above for the\\n'\n    + 'full flow (incl. worktrees).\\n'\n    + 'Add that info to memory so you remember next time.',\n);\n\n// `git merge --abort` / `git rebase --abort|--quit` UNDO an in-progress operation — they cannot create\n// a merge commit or rewrite history, so they cannot violate the fork-point invariant this rule\n// protects. They stay allowed so a repo left mid-operation (e.g. by a human-run rebase) can still be\n// cleaned up. `--continue` is deliberately NOT here: it COMPLETES the operation.\nconst UNDO_FLAG = /--(?:abort|quit)\\b/;\n\n// Typed as a query (\"would this fast-forward?\"), but a successful --ff-only IS the merge.\nconst FF_ONLY = /--ff-only\\b/;\n\nfunction truncate(s: string): string {\n    const MAX = 120;\n    return s.length <= MAX ? s : s.slice(0, MAX) + '…';\n}\n\n// Switches to a branch OTHER than main. `git branch -D <x>` is not a checkout so it does not trip\n// this; `checkout main` and flag-only forms like `checkout -` do not count as a feature switch.\nconst SWITCHES_TO_NON_MAIN = /git\\s+(?:checkout|switch)\\s+(?!main\\b|-\\s|-$)\\S+/;\n\nexport class RedirectHowToMergeMainRule extends BashRuleBase<RedirectHowToMergeMainConfig> {\n    private readonly scanner = new CommandScanner();\n    private readonly recovery = new TreeRecovery();\n\n    constructor(config: RedirectHowToMergeMainConfig) { super(config, 'redirect-how-to-merge-main'); }\n\n    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.';\n    readonly fixHint = FIX_HINT;\n\n    check(ctx: BashContext): readonly Violation[] {\n        for (const segment of this.scanner.commandSegments(ctx.command)) {\n            const violation = this.checkSegment(ctx, segment);\n            if (violation !== null) return [violation];\n        }\n        return [];\n    }\n\n    private checkSegment(ctx: BashContext, segment: string): Violation | null {\n        // 1. merge/rebase: unconditional block. Deliberately NO branch lookup.\n        //\n        // This rule used to read hook-time HEAD and bail out when it was `main`. But a PreToolUse hook\n        // runs BEFORE the command, so HEAD-at-hook-time is a value the command itself is about to\n        // change: `git checkout feat && git rebase main`, issued while HEAD was still `main` from a\n        // prior cleanup, read as \"we're on main, this is fine\" and was waved through. That is the\n        // incident this rule exists to prevent. Since merge/rebase have no legitimate AI-run form on\n        // ANY branch, there is no branch to consult — and so no HEAD to spoof.\n        if (this.scanner.invokesGit(segment, 'merge') || this.scanner.invokesGit(segment, 'rebase')) {\n            if (UNDO_FLAG.test(segment)) return null;\n            // `--ff-only` reads like a probe (\"can I fast-forward?\") but it MUTATES whenever the answer\n            // is yes, so say that here — the AI that typed it was usually only trying to look.\n            const probe = FF_ONLY.test(segment)\n                ? ' `--ff-only` is NOT a read-only check — it moves your branch whenever it succeeds; see the read-only checks below.'\n                : '';\n            return this.block(ctx, segment, 'Direct `git merge`/`git rebase` is blocked — AI never runs it, on any branch.' + probe);\n        }\n\n        // 2. pull: unlike merge/rebase this DOES retain a legitimate on-main form\n        // (`git checkout main && git pull origin main`), so it must consult the branch — which is\n        // exactly why it also needs the branch-switch check that (1) no longer requires.\n        if (this.scanner.invokesGit(segment, 'pull') && /\\borigin\\s+main\\b/.test(segment)) {\n            return this.checkPull(ctx, segment);\n        }\n\n        return null;\n    }\n\n    private checkPull(ctx: BashContext, segment: string): Violation | null {\n        if (SWITCHES_TO_NON_MAIN.test(ctx.command)) {\n            return this.block(ctx, segment, 'Blocked: this command switches to a feature branch and then pulls main into it.');\n        }\n        // The recommended `git checkout main && git pull origin main` — but ONLY in the primary\n        // clone. Inside a linked worktree that checkout FATALS (\"'main' is already checked out at\n        // <primary>\"), so waving it through here hands the AI a command that cannot work and costs\n        // it a turn to discover. Steer to the fetch, which is all a worktree needs.\n        if (/git\\s+(?:checkout|switch)\\s+main\\b/.test(ctx.command)) {\n            if (this.recovery.kindOf(ctx.workspaceRoot) !== 'worktree') return null;\n            // updateMainSteps already explains the worktree/fatal reasoning — don't say it twice.\n            return this.block(ctx, segment, ['Blocked.', ...this.recovery.updateMainSteps('worktree')].join('\\n'));\n        }\n\n        const currentBranch = execSync('git rev-parse --abbrev-ref HEAD', {\n            cwd: ctx.workspaceRoot,\n            encoding: 'utf8',\n        }).trim();\n        if (currentBranch === 'main') return null;\n\n        return this.block(ctx, segment, `Pulling main into feature branch '${currentBranch}' is blocked.`);\n    }\n\n    private block(ctx: BashContext, segment: string, what: string): Violation {\n        const docPath = new RepoRootFinder().instructAiDocPath(ctx.workspaceRoot, INSTRUCT_FILE);\n        return new V(\n            1,\n            truncate(segment),\n            `${what} Use the gated 3-point flow instead: 'pnpm wp-start-update' → 'pnpm wp-finish-update' when NO PR is open, or 'pnpm wp-start-upsert-pr' → 'pnpm wp-finish-upsert-pr' when a PR IS open (required then — the merge rewrites the branch and the PR must be re-pointed in the same run). If you truly need a raw merge/rebase, ask the HUMAN to run it — and warn them to push back. Full flow: READ ${docPath}.`,\n        );\n    }\n}\n"]}