@webpieces/ai-hook-rules 0.4.684 → 0.4.685

package/src/core/l2-rows.js.map

@@ -1 +1 @@
-{"version":3,"file":"l2-rows.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/l2-rows.ts"],"names":[],"mappings":"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","sourcesContent":["// ---------------------------------------------------------------------------\n// L2 — the BRANCH-STATE layer, as data.\n//\n// L2 answers one question: *may I work here, and is what I read current?* Drawn as a decision matrix\n// that is TEN ordered rows plus one terminal fail-open row, first match wins.\n//\n// This module holds those rows, l2-doc.ts renders them into guards/L2-branch-state.md, and a unit test\n// (l2-matrix.spec.ts) locks that file byte-identical to the renderer — the same mechanism that already\n// makes L0's fault table and L1's location table undriftable. Before this existed the L2 doc was 100%\n// hand-written and said so: *\"Until that lands this text is hand-written and can drift.\"*\n//\n// ## HOW L2 JOINS TO THE ROWS TODAY — read this before assuming it works like L1\n//\n// L1 DISPATCHES from its array: `runner.l1LocationBlock` takes the first matching row and switches on\n// its `blockId`, so deleting a row deletes a block. L2 does NOT, and pretending otherwise would be the\n// drift this table exists to remove. The four L2 guard classes each own their own ladder, and those\n// ladders diverge on purpose (guards/L2-branch-state.md, \"Deliberate divergence\": the two Bash guards\n// differ in polarity, quantifier and empty-command handling all at once, so no single parameterised\n// function serves both). Unifying them is where a wrong edit turns an allow into a session-wedging\n// block, so it is deliberately not attempted here.\n//\n// What L2 does instead is a REASON→ROW join. Every exit of every L2 guard already carries a stable\n// reason string into the decision log; `L2_ROW_FOR_REASON` maps each of those to the row it is an\n// instance of, the guards stamp that number as `row=`, and l2-matrix.spec.ts asserts the map is\n// EXHAUSTIVE against the guard sources — a new reason with no row fails the build. So `row=8` in\n// `.webpieces/logs/L2-decisions` opens guards/L2-branch-state.md at row 8 and reads the state, the cure\n// and the tools that row covers, exactly as `row=5` already does for L1.\n//\n// The rows the guards cannot yet honour are named in the doc's \"Not done\" section rather than quietly\n// rendered as if they were live. That section is generated from NOT_DONE below, so it cannot rot.\n//\n// This module is deliberately import-free at runtime, so `pnpm guards:generate` can load it without the\n// package's transitive dependencies.\n// ---------------------------------------------------------------------------\n\n/** Which tools a row covers. `B` Bash · `R` Read · `E` Write/Edit. */\nexport type L2Tool = 'B' | 'R' | 'E';\n\n/** What L2 does with a row — the same action codebook every layer reports in (GUARD_MATRIX.md). */\nexport type L2ActionKind = 'allow' | 'exempt' | 'block' | 'fail-open';\n\n/**\n * The TERMINAL fail-open row, and the one number in this table that is not from the 1-10 design.\n *\n * Everything in rows 6-10 needs the main-sync cache, and the cache is written by a fire-and-forget\n * refresher that populates it for the NEXT call — so the first tool call of every session has none.\n * \"Stop here and ALLOW\" was written as a DIVIDER in the design table, i.e. as prose between two blocks\n * of rows. Prose cannot be stamped into a log line, and this is the single most frequently taken exit\n * in the whole layer (every session's first call, every unreadable branch, every unreachable forge), so\n * it is a row with a number like any other.\n *\n * It is 11 rather than 6-with-a-renumber because row numbers are IDENTITY here: they are printed in the\n * doc and logged as `row=`, so shifting 6-10 down would silently re-point every reference. The doc\n * prints it in its true position, between rows 5 and 6, with its number shown — same treatment L1 gives\n * row 8, which is printed third and numbered 8.\n */\nexport const L2_FAIL_OPEN_ROW = 11;\n\n/** The `act` cell: the doc's literal label, plus the machine-readable kind behind it. */\nexport class L2Action {\n    constructor(readonly label: string, readonly kind: L2ActionKind) {}\n}\n\nexport const L2_ALLOW = new L2Action('1 allow', 'allow');\nexport const L2_EXEMPT = new L2Action('2 exempt', 'exempt');\nexport const L2_BLOCK = new L2Action('4 block', 'block');\nexport const L2_FAIL_OPEN = new L2Action('1 allow (fail-open)', 'fail-open');\n\n/**\n * One row of the \"L2 use cases\" table: what you SEE, the state it puts you in, the verdict, the fix.\n *\n * THE POINT OF THIS CLASS is that a use case is added HERE, in code, beside the row it exercises — not\n * into a hand-written doc section that drifts. When a new situation comes up in a session, it becomes\n * one more `new L2UseCase(...)` on the row that judged it, `pnpm guards:generate` re-renders the doc,\n * and the byte-lock spec fails if anyone edits the rendered table instead.\n *\n * The four text fields are rendered VERBATIM. `reason` is the ENFORCEMENT half and is never rendered:\n * it is the exact `reason` string the guard logs for this case, so a spec can push it back through\n * `l2RowForReason` and assert it lands on the row this use case is filed under. That closes the loop\n * the L2 decision log opens — `row=` in the trail, this table on the page, one join between them.\n *\n * `reason` is REQUIRED, and a case that exercises something which is not an L2 row exit says so with\n * `NO_ROW_EXIT` rather than by omitting the argument. An optional field would make opting OUT of the\n * only real enforcement here the shortest thing to type and impossible to grep — the widening-by-absence\n * shape CLAUDE.md rejects. `grep NO_ROW_EXIT` now lists every unenforced case.\n */\nexport class L2UseCase {\n    // eslint-disable-next-line @typescript-eslint/max-params -- four verbatim doc cells plus the reason behind them\n    constructor(\n        readonly num: number,\n        readonly symptom: string,\n        readonly state: string,\n        readonly verdict: string,\n        readonly fix: string,\n        readonly reason: string,\n    ) {}\n}\n\n/**\n * The `reason` for a use case that is NOT an L2 row exit, and so has nothing to join back to.\n *\n * The only legitimate case today is row 3: merge-in-progress is L4's state, and L2 exempts it without\n * logging a reason of its own. Named rather than absent, so \"this case is not enforced\" is a value in\n * the table you can grep for instead of a missing argument nobody notices.\n */\nexport const NO_ROW_EXIT = 'NO_ROW_EXIT (not an L2 row exit — another layer owns this state)';\n\n/**\n * One row of L2's decision table.\n *\n * `cure` is rendered verbatim into the doc and is LITERAL by policy: L0's cure-reachability discipline\n * says a message pointing at documentation for its own remedy cannot be tested, and it caught a fault\n * prescribing a bin that had been renamed away. `—` is the only legal non-command cure, and only on a\n * row that allows.\n */\nexport class L2Row {\n    // eslint-disable-next-line @typescript-eslint/max-params -- the five cells of one doc row plus its use cases\n    constructor(\n        readonly num: number,\n        readonly tools: readonly L2Tool[],\n        /** The `state` cell, verbatim. */\n        readonly state: string,\n        readonly action: L2Action,\n        /** The `cure` cell, verbatim. `—` when the row allows. */\n        readonly cure: string,\n        /**\n         * The observed situations this row judges. Rendered as the \"L2 use cases\" table.\n         *\n         * A NON-EMPTY tuple, and required: a row nobody has ever seen fire is either dead or\n         * undocumented, and both are worth knowing. Expressing that in the TYPE rather than as a\n         * runtime assertion is the JwtRoles pattern — the invariant is enforced at the moment the row\n         * is written, which is the only moment that changes what somebody types.\n         */\n        readonly useCases: readonly [L2UseCase, ...L2UseCase[]],\n    ) {}\n\n    /** `B R E`, the doc's own spelling of the tool cell. */\n    toolCell(): string {\n        return this.tools.join(' ');\n    }\n}\n\n/**\n * THE ELEVEN L2 ROWS, in first-match-wins order.\n *\n * Rows 1-5 need NO cache and fire on call #1: rows 1, 2 and 4 are text matches, row 3 is a marker-file\n * scan, row 5 is one `git rev-parse`. Row 11 is the cache divider. Rows 6-10 all read the cache.\n *\n * THE ORDER OF ROW 5 IS THE MOST LOAD-BEARING THING IN THIS TABLE. Put \"on main\" BELOW the divider and\n * writes on `main` are permitted for the whole first call of every session — and permanently in a\n * multi-worktree repo, where another tree may hold the cache lock indefinitely.\n *\n * `B` tracks `E` everywhere; `R` is judged separately in exactly ONE place, rows 6/7 on `main`. A Read\n * names exactly one file so the guard can evaluate it precisely; a Bash command is opaque and gets the\n * conservative answer. Reading a CURRENT `main` is fine — the problem is that `main` is almost always\n * behind.\n */\nexport const L2_ROWS: readonly L2Row[] = [\n    new L2Row(1, ['B', 'R', 'E'], 'on the **global allowlist** (inert command, or a universal cure such as reading/editing `webpieces.config.json`)', L2_ALLOW, '—', [\n        new L2UseCase(1,\n            'You are blocked by some other L2 row, and need to turn the policy off to get anything done',\n            'any state — this row is ahead of every block',\n            'ALLOW: reading and editing `webpieces.config.json` is never blocked, so the mode-OFF cure is always reachable',\n            'Edit `webpieces.config.json` → `hookGuards` → `branch-state-guard` → `\"mode\": \"OFF\"`',\n            'webpieces-config-read (escape hatch)'),\n        new L2UseCase(2,\n            'A Write to `webpieces.config.json` while on `main`, which row 5 would otherwise block',\n            'on `main`, editing the one file that can disable the guard',\n            'ALLOW: the hook adapter bypasses feature-branch-guard for this path before any guard runs',\n            'None needed — the edit proceeds',\n            'config-bypass (feature-branch-guard skipped)'),\n    ]),\n    new L2Row(2, ['B'], 'bare `git checkout main`, with no `git pull` chained into the same command', L2_BLOCK, '`pnpm wp-checkout-clean-main`', [\n        new L2UseCase(3,\n            '`git checkout main` after a merge, to start the next piece of work',\n            'about to land on whatever local `main` you last had — 157 commits behind, in the incident',\n            'BLOCK: decided from command TEXT alone, before the checkout, because the only `main` this could measure is the one it is about to leave',\n            '`pnpm wp-checkout-clean-main` — checkout, pull, reap dead branches/worktrees, sweep orphan directories, in one command (hand-rolled, the pull must be in the SAME command as the checkout)',\n            'bare checkout of main ('),\n        new L2UseCase(4,\n            'The same command inside a linked worktree, where `git checkout main` fatals anyway',\n            'linked worktree — `main` is already checked out in the primary clone',\n            'BLOCK, and the message prints the worktree form rather than a cure git would refuse',\n            '`git fetch origin main`, then work off `origin/main`',\n            'bare checkout of main ('),\n    ]),\n    new L2Row(3, ['B', 'R', 'E'], '**merge in progress** — L4 owns this state', L2_EXEMPT, 'finish the merge: `pnpm wp-finish-upsert-pr`', [\n        new L2UseCase(5,\n            'Reading and editing conflicted files during a 3-point merge, on a branch row 9 would block',\n            'merge markers on disk — `pnpm wp-start-update` has run and not finished',\n            'EXEMPT: everything is permitted, which is exactly what lets row 9 be strict',\n            'Resolve the conflicts, then `pnpm wp-finish-upsert-pr`',\n            NO_ROW_EXIT),\n    ]),\n    new L2Row(4, ['B'], 'on the **skip list** — it gets you OUT, or tells you where you are', L2_ALLOW, '—', [\n        new L2UseCase(6,\n            '`git status` / `gh pr view` while blocked, to work out where you are',\n            'any state — orientation is never \"working here\"',\n            'ALLOW: metadata tells you where you are without putting stale file CONTENT in context',\n            'None needed',\n            'not-a-content-read (cure/build/metadata)'),\n        new L2UseCase(7,\n            '`git stash` when `git checkout -b <new> origin/main` refuses because `origin/main` touched the same files you edited',\n            'on a stale `main` or a merged branch, dirty tree, with an overlapping upstream change',\n            'ALLOW: the cure for the row that blocked you must itself never be blocked — and this is the residual step that makes rows 6 and 8 safe to block on a dirty tree',\n            'None needed — then re-run the checkout and `git stash pop`',\n            'not-a-content-read (cure/build/metadata)'),\n        new L2UseCase(8,\n            '`pnpm wp-start-upsert-pr` on a branch whose fork point is broken',\n            'row 9 state, running the tool row 9 prescribes',\n            'ALLOW: every `wp-*` bin is on the skip list, so no row can block its own remedy',\n            'None needed',\n            'merged-branch recovery/inspection (allowlisted)'),\n    ]),\n    new L2Row(5, ['B', 'E'], 'on `main`', L2_BLOCK, '`git checkout -b <new> origin/main`', [\n        new L2UseCase(9,\n            'An Edit or Write to any tracked file while `git rev-parse --abbrev-ref HEAD` says `main`',\n            'on `main`, any freshness',\n            'BLOCK: decided by one `git rev-parse`, with NO cache read, so it fires on the first tool call of the session',\n            '`git checkout -b <new> origin/main` — uncommitted work comes with you',\n            'on-main'),\n        new L2UseCase(10,\n            'A Bash command that WRITES tracked files as a side effect — `npx expo install`, a formatter, codegen, `sed -i`, a `>` redirect',\n            'on `main`, and the write is incidental to a command whose stated purpose is something else',\n            'BLOCK: default-DENY on `main` plus row 4\\'s skip list, so a command nobody thought to enumerate is caught by not being on the list — which is the only shape that could have caught this one',\n            '`git checkout -b <new> origin/main` BEFORE running anything that may write',\n            'on-main'),\n        new L2UseCase(24,\n            'A build or a test run on a `main` that is perfectly up to date',\n            'on `main`, current — no staleness anywhere',\n            'BLOCK: freshness is not the question for the BLOCK. Reading `main` to plan stays open; what is closed is WORKING here, because the feature branch is the unit of work — and when `main` is behind instead, the reads are out of date too. The cure is a new branch off `origin/main`, which fetches, so it is right in both states',\n            '`git checkout -b <new> origin/main`',\n            'on-main'),\n        new L2UseCase(16,\n            'Read is blocked, so the session reaches for `cat`, `grep` and `ls` instead — and describes a CI workflow set missing a whole workflow that existed upstream',\n            'the SIDE DOOR: same tree, different tool',\n            'BLOCK. This case used to be judged by row 6 (a stale-content blocklist on the Bash side); row 5 now subsumes it, because being on `main` is already the finding and no enumeration of readers is needed. The log used to read \"read-stale-guard handled\", which is worse than no guard — it looks covered',\n            '`git checkout -b <new> origin/main`',\n            'on-main'),\n        new L2UseCase(25,\n            'The FIRST command of a session, on `main`, before any cache exists',\n            'on `main`, cache absent — row 11 would fail open',\n            'BLOCK anyway: row 5 is ABOVE the cache divider and reads only `git rev-parse`, so it is armed on call #1. This is the case the cache-gated version could never catch',\n            '`git checkout -b <new> origin/main`',\n            'on-main'),\n    ]),\n    new L2Row(L2_FAIL_OPEN_ROW, ['B', 'R', 'E'], '**the state could not be established** — branch undeterminable, no cache yet, the cache holds another branch, `origin/main` unknown, or the forge unreachable', L2_FAIL_OPEN, '— (nothing to fix; the refresher populates the cache for the next call)', [\n        new L2UseCase(11,\n            'The very first tool call of a session is allowed even on a badly stale `main`',\n            'no cache — the refresher is fire-and-forget and populates it for the NEXT call',\n            'ALLOW (fail-open), logged as `ALLOW_FAIL_OPEN` so abstentions stay countable',\n            'None — the second call is judged normally',\n            'no-sync-cache'),\n        new L2UseCase(12,\n            'Guards quietly stand down on a plane, or when `gh` is unauthenticated or rate-limited',\n            'the forge could not be asked whether the PR is merged',\n            'ALLOW (fail-open) logged as `no-forge` — distinct from \"asked, and it is not merged\", which used to look identical in the trail',\n            'None — restore network/`gh auth` to re-arm the merged-branch policy',\n            'no-forge'),\n        new L2UseCase(14,\n            'Mid-rebase, every guard abstains',\n            'detached HEAD — there is no branch name to judge',\n            'ALLOW (fail-open), logged LOUDLY when the branch is unresolvable rather than merely detached',\n            'None — finish or abort the rebase',\n            'branch-undeterminable'),\n    ]),\n    new L2Row(6, ['R'], 'on `main`, behind `origin/main`', L2_BLOCK, '`git pull origin main`, or `git checkout -b <new> origin/main`', [\n        new L2UseCase(13,\n            'The Read tool refuses a file on a stale `main` while you have UNCOMMITTED edits',\n            'on `main`, behind `origin/main`, dirty tree',\n            'BLOCK. This used to fail open, on the argument that the prescribed `git pull` is not a clean fast-forward when the tree is dirty. That was true of the MESSAGE, not the row: the cure cell always offered a second form, and it works dirty',\n            '`git checkout -b <new> origin/main` — uncommitted changes come with you onto the new branch. If git refuses because `origin/main` touched the same files, `git stash` first (never blocked), then retry, then `git stash pop`',\n            'on-stale-main'),\n        new L2UseCase(15,\n            'The Read tool refuses a file that exists, on a `main` 18 commits behind',\n            'on `main`, behind `origin/main`, clean tree',\n            'BLOCK: judged by live ancestry (`git merge-base --is-ancestor`), not hash equality, so a pull takes effect instantly',\n            '`git pull origin main`, or `git checkout -b <new> origin/main`',\n            'on-stale-main'),\n    ]),\n    new L2Row(7, ['R'], 'on `main`, current', L2_ALLOW, '—', [\n        new L2UseCase(17,\n            'Reading files on a `main` you just pulled',\n            'on `main`, and `origin/main` is an ancestor of HEAD',\n            'ALLOW: this is the ONE place a Read is judged differently from a Bash command, because a Read names exactly one file and can be evaluated precisely',\n            'None needed',\n            'local-main-contains-origin (up to date)'),\n    ]),\n    new L2Row(8, ['B', 'R', 'E'], 'on a branch whose PR is **already merged**', L2_BLOCK, '`git fetch origin main && git checkout -b <new> origin/main`', [\n        new L2UseCase(18,\n            'You keep working on the branch after its PR merged, and the next PR reopens code review already landed',\n            'branch whose PR is merged — `merged` is monotonic, so the cached flag is trusted with no TTL',\n            'BLOCK across all three tools',\n            '`git fetch origin main && git checkout -b <new> origin/main`',\n            'already-merged PR#'),\n        new L2UseCase(26,\n            'You have uncommitted edits on a branch whose PR just merged',\n            'merged branch, dirty tree',\n            'BLOCK. This used to fail open too, and that valve never had an argument behind it — row 8\\'s cure carries uncommitted work onto the fresh branch, so nothing was ever trapped. It was drift from the documented design, which `read-stale-guard`\\'s own class comment still described correctly',\n            '`git fetch origin main && git checkout -b <new> origin/main` — your edits come with you',\n            'already-merged PR#'),\n        new L2UseCase(19,\n            'A shell-only session sails through on a merged branch',\n            'merged branch, Bash only — both FILE guards are file-scoped, so Bash reached neither',\n            'BLOCK: `merged-branch-bash-guard` exists because `branchAlreadyMerged` was being computed and logged on that very path, then thrown away',\n            '`git fetch origin main && git checkout -b <new> origin/main`',\n            'already-merged PR#'),\n    ]),\n    new L2Row(9, ['B', 'R', 'E'], 'no fork point with `origin/main`, or `origin/main` moved and collided with your files', L2_BLOCK, '`pnpm wp-start-update`, or `pnpm wp-start-upsert-pr` when a PR is open', [\n        new L2UseCase(20,\n            'Your branch and `origin/main` share no merge base — usually a branch cut from a squashed-away tip',\n            'no fork point',\n            'BLOCK: nothing built on this branch can be reasoned about relative to main',\n            '`pnpm wp-start-update`, or `pnpm wp-start-upsert-pr` when a PR is open',\n            'no-fork-point'),\n        new L2UseCase(21,\n            '`origin/main` moved and changed the same files you edited',\n            'main-moved collision',\n            'BLOCK — and row 3 then exempts everything once the merge starts, which is what makes this safe',\n            '`pnpm wp-start-update`, resolve, `pnpm wp-finish-upsert-pr`',\n            'main-moved-conflict'),\n    ]),\n    new L2Row(10, ['B', 'R', 'E'], 'healthy feature branch', L2_ALLOW, '—', [\n        new L2UseCase(22,\n            'Ordinary work on a branch cut from a current `origin/main`',\n            'healthy feature branch',\n            'ALLOW — the state every other row exists to push you back into',\n            'None needed',\n            'clean-feature-branch'),\n        new L2UseCase(23,\n            '`stale-main-bash-guard` sees a feature branch and hands off',\n            'not on `main` — state B belongs to `merged-branch-bash-guard`',\n            'ALLOW: the same verdict about the same tree, logged by the guard that is not responsible for it',\n            'None needed',\n            'not-on-main (state B is another guard)'),\n    ]),\n];\n\n/**\n * Every use case on every row, in row order, for the doc and for the exhaustiveness specs.\n *\n * Numbering is GLOBAL and is identity, exactly as the row numbers are: a use case is cited by number in\n * review and in the doc, so add new ones at the END of the highest number rather than renumbering to\n * keep a row's block contiguous.\n */\n// webpieces-disable no-function-outside-class -- pure accessor over L2_ROWS above, in this data module\nexport function allL2UseCases(): readonly L2UseCase[] {\n    return L2_ROWS.flatMap((row: L2Row): readonly L2UseCase[] => row.useCases);\n}\n\n/**\n * REASON → ROW. The join between what a guard actually logged and the row it is an instance of.\n *\n * Keys are the exact `reason` strings the four L2 guards pass to their decision log. Two of them are\n * PREFIXES because the guard interpolates a PR number or a matched segment into the reason\n * (`already-merged PR#123`); those are matched by `l2RowForReason` on prefix, which is why they end in\n * a space or a `(`.\n *\n * l2-matrix.spec.ts reads the four guard sources and asserts every reason literal in them resolves\n * here, so a new exit with no row fails the build rather than logging `row=-` forever.\n */\nconst EXACT_REASON_ROWS: Record<string, number> = {\n    // Row 1 — the universal cure that must stay reachable from inside any block.\n    'webpieces-config-read (escape hatch)': 1,\n    // Row 2 — the preventive half, decided from command TEXT before any cache is read.\n    // (prefix, see PREFIX_REASON_ROWS)\n    // Row 4 — the skip list, in its two live spellings.\n    'merged-branch recovery/inspection (allowlisted)': 4,\n    'not-a-content-read (cure/build/metadata)': 4,\n    // Row 5 — never work on main.\n    'on-main': 5,\n    // Row 6/7 — the ONE place a Read is judged differently from a Bash command.\n    'on-stale-main': 6,\n    'local-main-contains-origin (up to date)': 7,\n    // Row 9 — the two unhealthy-fork states.\n    'no-fork-point': 9,\n    'main-moved-conflict': 9,\n    // Row 10 — healthy, and the state-B guard's \"this is not my state\" hand-off, which is the same\n    // verdict about the same tree.\n    'clean-feature-branch': 10,\n    'not-on-main (state B is another guard)': 10,\n    // Row 11 — every \"could not establish\", including the two dirty-tree valves the code still opens\n    // (see NOT_DONE) and the unreachable forge.\n    'branch-undeterminable': L2_FAIL_OPEN_ROW,\n    'no-sync-cache': L2_FAIL_OPEN_ROW,\n    'stale-cross-branch-cache': L2_FAIL_OPEN_ROW,\n    'origin-main-unknown': L2_FAIL_OPEN_ROW,\n    // `dirty-tree-on-main` and `dirty-merged-branch` used to live here. Both valves are deleted: rows\n    // 6 and 8 now block on a dirty tree, because each row's cure carries uncommitted work with you.\n    'no-forge': L2_FAIL_OPEN_ROW,\n    // The config-edit bypass logged by the hook adapter before any guard runs — row 1, same universal\n    // cure as the config READ above.\n    'config-bypass (feature-branch-guard skipped)': 1,\n};\n\n/** Reasons the guards interpolate a value into. Matched by prefix, longest first. */\nconst PREFIX_REASON_ROWS: Record<string, number> = {\n    'already-merged PR#': 8,\n    'bare checkout of main (': 2,\n    // `stale-main content read (` used to live here, mapping the Bash side of row 6. It is gone with\n    // the guard exit that emitted it: on `main`, row 5 now blocks before any content-read scan runs,\n    // so row 6 is what the table always said it was — the ROW-ONLY row.\n};\n\n/**\n * The row a logged reason belongs to, or null when nothing claims it.\n *\n * Null rather than a default row: a reason with no row is a HOLE in the table, and defaulting it to\n * \"fail-open\" would hide exactly the drift the exhaustiveness spec exists to catch. The guards render\n * null as `row=-`, so an unmapped reason is visible in the log too, not only in CI.\n */\n// webpieces-disable no-function-outside-class -- the matcher over the two tables above, beside them in this data module\nexport function l2RowForReason(reason: string): number | null {\n    const exact = EXACT_REASON_ROWS[reason];\n    if (exact !== undefined) return exact;\n    for (const prefix of Object.keys(PREFIX_REASON_ROWS)) {\n        if (reason.startsWith(prefix)) return PREFIX_REASON_ROWS[prefix];\n    }\n    return null;\n}\n\n/** Every reason string this table claims, for the exhaustiveness spec. */\n// webpieces-disable no-function-outside-class -- pure accessor over the two tables above\nexport function l2MappedReasons(): readonly string[] {\n    return [...Object.keys(EXACT_REASON_ROWS), ...Object.keys(PREFIX_REASON_ROWS)];\n}\n\n/** One documented gap between a row and what the guards actually do today. Data-only. */\nexport class L2NotDone {\n    constructor(readonly row: number, readonly gap: string, readonly why: string) {}\n}\n\n/**\n * WHERE THE TABLE AND THE CODE DISAGREE, stated rather than papered over.\n *\n * The L1 precedent is `## Not done — \\`o\\` is not exempt yet`: a row the runner cannot reach, named in\n * the generated doc with the reason it has not shipped. The same treatment applies here, and it is what\n * makes it safe to publish a table the guards do not yet dispatch from — a reader is told exactly which\n * rows describe intent rather than behaviour, and the log's `row=` stamps land on row 11 for every one\n * of these, so the trail never claims the strict row fired.\n */\nexport const NOT_DONE: readonly L2NotDone[] = [\n    // EMPTY, and that is the goal state: every row in the table is a row the guards actually honour.\n    //\n    // It held three entries. Row 5's `B` half shipped (on `main` is now judged from the branch alone,\n    // above the cache divider). Rows 6 and 8 held DIRTY-TREE valves, and both are now closed — each of\n    // those rows cures with `git checkout -b <new> origin/main`, which carries uncommitted changes onto\n    // the new branch, so a dirty tree never trapped anybody. The row 6 entry claimed the dirty argument\n    // \"has teeth\" there because its cure is `git pull`; that was a fact about the MESSAGE, which printed\n    // only the pull, and the fix was to print both cures rather than to suppress the block.\n    //\n    // Keep this array. An empty \"Not done\" is a claim worth making explicitly — the doc says so in as\n    // many words — and the next divergence between a row and its code belongs here, not in prose.\n];\n"]}
+{"version":3,"file":"l2-rows.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/l2-rows.ts"],"names":[],"mappings":"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","sourcesContent":["// ---------------------------------------------------------------------------\n// L2 — the BRANCH-STATE layer, as data.\n//\n// L2 answers one question: *may I work here, and is what I read current?* Drawn as a decision matrix\n// that is TEN ordered rows plus one terminal fail-open row, first match wins.\n//\n// This module holds those rows, l2-doc.ts renders them into guards/L2-branch-state.md, and a unit test\n// (l2-matrix.spec.ts) locks that file byte-identical to the renderer — the same mechanism that already\n// makes L0's fault table and L1's location table undriftable. Before this existed the L2 doc was 100%\n// hand-written and said so: *\"Until that lands this text is hand-written and can drift.\"*\n//\n// ## HOW L2 JOINS TO THE ROWS TODAY — read this before assuming it works like L1\n//\n// L1 DISPATCHES from its array: `runner.l1LocationBlock` takes the first matching row and switches on\n// its `blockId`, so deleting a row deletes a block. L2 does NOT, and pretending otherwise would be the\n// drift this table exists to remove. The four L2 guard classes each own their own ladder, and those\n// ladders diverge on purpose (guards/L2-branch-state.md, \"Deliberate divergence\": the two Bash guards\n// differ in polarity, quantifier and empty-command handling all at once, so no single parameterised\n// function serves both). Unifying them is where a wrong edit turns an allow into a session-wedging\n// block, so it is deliberately not attempted here.\n//\n// What L2 does instead is a REASON→ROW join. Every exit of every L2 guard already carries a stable\n// reason string into the decision log; `L2_ROW_FOR_REASON` maps each of those to the row it is an\n// instance of, the guards stamp that number as `row=`, and l2-matrix.spec.ts asserts the map is\n// EXHAUSTIVE against the guard sources — a new reason with no row fails the build. So `row=8` in\n// `.webpieces/logs/L2-decisions` opens guards/L2-branch-state.md at row 8 and reads the state, the cure\n// and the tools that row covers, exactly as `row=5` already does for L1.\n//\n// The rows the guards cannot yet honour are named in the doc's \"Not done\" section rather than quietly\n// rendered as if they were live. That section is generated from NOT_DONE below, so it cannot rot.\n//\n// This module is deliberately import-free at runtime, so `pnpm guards:generate` can load it without the\n// package's transitive dependencies.\n// ---------------------------------------------------------------------------\n\n/** Which tools a row covers. `B` Bash · `R` Read · `E` Write/Edit. */\nexport type L2Tool = 'B' | 'R' | 'E';\n\n/** What L2 does with a row — the same action codebook every layer reports in (GUARD_MATRIX.md). */\nexport type L2ActionKind = 'allow' | 'exempt' | 'block' | 'fail-open';\n\n/**\n * The TERMINAL fail-open row, and the one number in this table that is not from the 1-10 design.\n *\n * Everything in rows 6-10 needs the main-sync cache, and the cache is written by a fire-and-forget\n * refresher that populates it for the NEXT call — so the first tool call of every session has none.\n * \"Stop here and ALLOW\" was written as a DIVIDER in the design table, i.e. as prose between two blocks\n * of rows. Prose cannot be stamped into a log line, and this is the single most frequently taken exit\n * in the whole layer (every session's first call, every unreadable branch, every unreachable forge), so\n * it is a row with a number like any other.\n *\n * It is 11 rather than 6-with-a-renumber because row numbers are IDENTITY here: they are printed in the\n * doc and logged as `row=`, so shifting 6-10 down would silently re-point every reference. The doc\n * prints it in its true position, between rows 5 and 6, with its number shown — same treatment L1 gives\n * row 8, which is printed third and numbered 8.\n */\nexport const L2_FAIL_OPEN_ROW = 11;\n\n/** The `act` cell: the doc's literal label, plus the machine-readable kind behind it. */\nexport class L2Action {\n    constructor(readonly label: string, readonly kind: L2ActionKind) {}\n}\n\nexport const L2_ALLOW = new L2Action('1 allow', 'allow');\nexport const L2_EXEMPT = new L2Action('2 exempt', 'exempt');\nexport const L2_BLOCK = new L2Action('4 block', 'block');\nexport const L2_FAIL_OPEN = new L2Action('1 allow (fail-open)', 'fail-open');\n\n/**\n * One row of the \"L2 use cases\" table: what you SEE, the state it puts you in, the verdict, the fix.\n *\n * THE POINT OF THIS CLASS is that a use case is added HERE, in code, beside the row it exercises — not\n * into a hand-written doc section that drifts. When a new situation comes up in a session, it becomes\n * one more `new L2UseCase(...)` on the row that judged it, `pnpm guards:generate` re-renders the doc,\n * and the byte-lock spec fails if anyone edits the rendered table instead.\n *\n * The four text fields are rendered VERBATIM. `reason` is the ENFORCEMENT half and is never rendered:\n * it is the exact `reason` string the guard logs for this case, so a spec can push it back through\n * `l2RowForReason` and assert it lands on the row this use case is filed under. That closes the loop\n * the L2 decision log opens — `row=` in the trail, this table on the page, one join between them.\n *\n * `reason` is REQUIRED, and a case that exercises something which is not an L2 row exit says so with\n * `NO_ROW_EXIT` rather than by omitting the argument. An optional field would make opting OUT of the\n * only real enforcement here the shortest thing to type and impossible to grep — the widening-by-absence\n * shape CLAUDE.md rejects. `grep NO_ROW_EXIT` now lists every unenforced case.\n */\nexport class L2UseCase {\n    // eslint-disable-next-line @typescript-eslint/max-params -- four verbatim doc cells plus the reason behind them\n    constructor(\n        readonly num: number,\n        readonly symptom: string,\n        readonly state: string,\n        readonly verdict: string,\n        readonly fix: string,\n        readonly reason: string,\n    ) {}\n}\n\n/**\n * The `reason` for a use case that is NOT an L2 row exit, and so has nothing to join back to.\n *\n * The only legitimate case today is row 3: merge-in-progress is L4's state, and L2 exempts it without\n * logging a reason of its own. Named rather than absent, so \"this case is not enforced\" is a value in\n * the table you can grep for instead of a missing argument nobody notices.\n */\nexport const NO_ROW_EXIT = 'NO_ROW_EXIT (not an L2 row exit — another layer owns this state)';\n\n/**\n * One row of L2's decision table.\n *\n * `cure` is rendered verbatim into the doc and is LITERAL by policy: L0's cure-reachability discipline\n * says a message pointing at documentation for its own remedy cannot be tested, and it caught a fault\n * prescribing a bin that had been renamed away. `—` is the only legal non-command cure, and only on a\n * row that allows.\n */\nexport class L2Row {\n    // eslint-disable-next-line @typescript-eslint/max-params -- the five cells of one doc row plus its use cases\n    constructor(\n        readonly num: number,\n        readonly tools: readonly L2Tool[],\n        /** The `state` cell, verbatim. */\n        readonly state: string,\n        readonly action: L2Action,\n        /** The `cure` cell, verbatim. `—` when the row allows. */\n        readonly cure: string,\n        /**\n         * The observed situations this row judges. Rendered as the \"L2 use cases\" table.\n         *\n         * A NON-EMPTY tuple, and required: a row nobody has ever seen fire is either dead or\n         * undocumented, and both are worth knowing. Expressing that in the TYPE rather than as a\n         * runtime assertion is the JwtRoles pattern — the invariant is enforced at the moment the row\n         * is written, which is the only moment that changes what somebody types.\n         */\n        readonly useCases: readonly [L2UseCase, ...L2UseCase[]],\n    ) {}\n\n    /** `B R E`, the doc's own spelling of the tool cell. */\n    toolCell(): string {\n        return this.tools.join(' ');\n    }\n}\n\n/**\n * THE ELEVEN L2 ROWS, in first-match-wins order.\n *\n * Rows 1-5 need NO cache and fire on call #1: rows 1, 2 and 4 are text matches, row 3 is a marker-file\n * scan, row 5 is one `git rev-parse`. Row 11 is the cache divider. Rows 6-10 all read the cache.\n *\n * THE ORDER OF ROW 5 IS THE MOST LOAD-BEARING THING IN THIS TABLE. Put \"on main\" BELOW the divider and\n * WRITES on `main` are permitted for the whole first call of every session — and permanently in a\n * multi-worktree repo, where another tree may hold the cache lock indefinitely.\n *\n * `B` AND `E` PART COMPANY ON `main`, and rows 5/6/7 are where. A WRITE on `main` is wrong at any\n * freshness — the work lands somewhere unreviewable and unrevertable — so row 5 is `E` only, judged on\n * the branch alone, above the divider. A READ or a BUILD on a CURRENT `main` is harmless, and blocking\n * it strands the agent right after `pnpm wp-checkout-clean-main` put it there; so `B` joins `R` on the\n * FRESHNESS-gated pair below the divider (row 6 behind → block, row 7 current → allow), where \"cannot\n * tell\" fails open at row 11 by construction. `B` and `R` still differ in SHAPE inside row 6: a Read\n * names one file and is judged precisely, a Bash command is opaque and gets default-deny plus row 4.\n */\nexport const L2_ROWS: readonly L2Row[] = [\n    new L2Row(1, ['B', 'R', 'E'], 'on the **global allowlist** (inert command, or a universal cure such as reading/editing `webpieces.config.json`)', L2_ALLOW, '—', [\n        new L2UseCase(1,\n            'You are blocked by some other L2 row, and need to turn the policy off to get anything done',\n            'any state — this row is ahead of every block',\n            'ALLOW: reading and editing `webpieces.config.json` is never blocked, so the mode-OFF cure is always reachable',\n            'Edit `webpieces.config.json` → `hookGuards` → `branch-state-guard` → `\"mode\": \"OFF\"`',\n            'webpieces-config-read (escape hatch)'),\n        new L2UseCase(2,\n            'A Write to `webpieces.config.json` while on `main`, which row 5 would otherwise block',\n            'on `main`, editing the one file that can disable the guard',\n            'ALLOW: the hook adapter bypasses feature-branch-guard for this path before any guard runs',\n            'None needed — the edit proceeds',\n            'config-bypass (feature-branch-guard skipped)'),\n    ]),\n    new L2Row(2, ['B'], 'bare `git checkout main`, with no `git pull` chained into the same command', L2_BLOCK, '`pnpm wp-checkout-clean-main`', [\n        new L2UseCase(3,\n            '`git checkout main` after a merge, to start the next piece of work',\n            'about to land on whatever local `main` you last had — 157 commits behind, in the incident',\n            'BLOCK: decided from command TEXT alone, before the checkout, because the only `main` this could measure is the one it is about to leave',\n            '`pnpm wp-checkout-clean-main` — checkout, pull, reap dead branches/worktrees, sweep orphan directories, in one command (hand-rolled, the pull must be in the SAME command as the checkout)',\n            'bare checkout of main ('),\n        new L2UseCase(4,\n            'The same command inside a linked worktree, where `git checkout main` fatals anyway',\n            'linked worktree — `main` is already checked out in the primary clone',\n            'BLOCK, and the message prints the worktree form rather than a cure git would refuse',\n            '`git fetch origin main`, then work off `origin/main`',\n            'bare checkout of main ('),\n    ]),\n    new L2Row(3, ['B', 'R', 'E'], '**merge in progress** — L4 owns this state', L2_EXEMPT, 'finish the merge: `pnpm wp-finish-upsert-pr`', [\n        new L2UseCase(5,\n            'Reading and editing conflicted files during a 3-point merge, on a branch row 9 would block',\n            'merge markers on disk — `pnpm wp-start-update` has run and not finished',\n            'EXEMPT: everything is permitted, which is exactly what lets row 9 be strict',\n            'Resolve the conflicts, then `pnpm wp-finish-upsert-pr`',\n            NO_ROW_EXIT),\n    ]),\n    new L2Row(4, ['B'], 'on the **skip list** — it gets you OUT, or tells you where you are', L2_ALLOW, '—', [\n        new L2UseCase(6,\n            '`git status` / `gh pr view` while blocked, to work out where you are',\n            'any state — orientation is never \"working here\"',\n            'ALLOW: metadata tells you where you are without putting stale file CONTENT in context',\n            'None needed',\n            'not-a-content-read (cure/build/metadata)'),\n        new L2UseCase(7,\n            '`git stash` when `git checkout -b <new> origin/main` refuses because `origin/main` touched the same files you edited',\n            'on a stale `main` or a merged branch, dirty tree, with an overlapping upstream change',\n            'ALLOW: the cure for the row that blocked you must itself never be blocked — and this is the residual step that makes rows 6 and 8 safe to block on a dirty tree',\n            'None needed — then re-run the checkout and `git stash pop`',\n            'not-a-content-read (cure/build/metadata)'),\n        new L2UseCase(28,\n            '`gh pr close 123`, `gh pr comment`, `gh api …` or a `curl` while parked on a stale `main` or a merged branch',\n            'blocked state, running something that touches GitHub or a URL and nothing in this tree',\n            'ALLOW: the skip list asks one question — does this read or write repo CONTENT? `gh` talks to GitHub and `curl`/`wget` talk to a network, so the branch state has nothing to say about them. The forms that write a local file (`gh repo clone`, `gh pr checkout`, `curl -o`, any `> file`) are excluded, and `gh pr create`/`merge` remain governed by their own guards',\n            'None needed',\n            'not-a-content-read (cure/build/metadata)'),\n        new L2UseCase(8,\n            '`pnpm wp-start-upsert-pr` on a branch whose fork point is broken',\n            'row 9 state, running the tool row 9 prescribes',\n            'ALLOW: every `wp-*` bin is on the skip list, so no row can block its own remedy',\n            'None needed',\n            'merged-branch recovery/inspection (allowlisted)'),\n    ]),\n    new L2Row(5, ['E'], 'on `main`', L2_BLOCK, '`git checkout -b <new> origin/main`', [\n        new L2UseCase(9,\n            'An Edit or Write to any tracked file while `git rev-parse --abbrev-ref HEAD` says `main`',\n            'on `main`, any freshness',\n            'BLOCK: decided by one `git rev-parse`, with NO cache read, so it fires on the first tool call of the session',\n            '`git checkout -b <new> origin/main` — uncommitted work comes with you',\n            'on-main'),\n        new L2UseCase(25,\n            'The FIRST edit of a session, on `main`, before any cache exists',\n            'on `main`, cache absent — row 11 would fail open',\n            'BLOCK anyway: row 5 is ABOVE the cache divider and reads only `git rev-parse`, so it is armed on call #1. This is why the row is `E` only and must never be gated on the cache',\n            '`git checkout -b <new> origin/main`',\n            'on-main'),\n    ]),\n    new L2Row(L2_FAIL_OPEN_ROW, ['B', 'R', 'E'], '**the state could not be established** — branch undeterminable, no cache yet, the cache holds another branch, `origin/main` unknown, or the forge unreachable', L2_FAIL_OPEN, '— (nothing to fix; the refresher populates the cache for the next call)', [\n        new L2UseCase(11,\n            'The very first tool call of a session is allowed even on a badly stale `main`',\n            'no cache — the refresher is fire-and-forget and populates it for the NEXT call',\n            'ALLOW (fail-open), logged as `ALLOW_FAIL_OPEN` so abstentions stay countable',\n            'None — the second call is judged normally',\n            'no-sync-cache'),\n        new L2UseCase(12,\n            'Guards quietly stand down on a plane, or when `gh` is unauthenticated or rate-limited',\n            'the forge could not be asked whether the PR is merged',\n            'ALLOW (fail-open) logged as `no-forge` — distinct from \"asked, and it is not merged\", which used to look identical in the trail',\n            'None — restore network/`gh auth` to re-arm the merged-branch policy',\n            'no-forge'),\n        new L2UseCase(27,\n            'A build, a `cat` or a `curl` on `main`, on the first Bash call of a session',\n            'on `main`, cache absent — so whether `main` is behind is UNKNOWN',\n            'ALLOW (fail-open), logged `ALLOW_FAIL_OPEN`. `B` on `main` is judged by rows 6/7 and therefore lands here when the cache cannot answer; the WRITE half is not, which is why row 5 sits above this divider',\n            'None — the second call is judged normally',\n            'no-sync-cache'),\n        new L2UseCase(14,\n            'Mid-rebase, every guard abstains',\n            'detached HEAD — there is no branch name to judge',\n            'ALLOW (fail-open), logged LOUDLY when the branch is unresolvable rather than merely detached',\n            'None — finish or abort the rebase',\n            'branch-undeterminable'),\n    ]),\n    new L2Row(6, ['B', 'R'], 'on `main`, behind `origin/main`', L2_BLOCK, '`git pull origin main`, or `git checkout -b <new> origin/main`', [\n        new L2UseCase(13,\n            'The Read tool refuses a file on a stale `main` while you have UNCOMMITTED edits',\n            'on `main`, behind `origin/main`, dirty tree',\n            'BLOCK. This used to fail open, on the argument that the prescribed `git pull` is not a clean fast-forward when the tree is dirty. That was true of the MESSAGE, not the row: the cure cell always offered a second form, and it works dirty',\n            '`git checkout -b <new> origin/main` — uncommitted changes come with you onto the new branch. If git refuses because `origin/main` touched the same files, `git stash` first (never blocked), then retry, then `git stash pop`',\n            'on-stale-main'),\n        new L2UseCase(15,\n            'The Read tool refuses a file that exists, on a `main` 18 commits behind',\n            'on `main`, behind `origin/main`, clean tree',\n            'BLOCK: judged by live ancestry (`git merge-base --is-ancestor`), not hash equality, so a pull takes effect instantly',\n            '`git pull origin main`, or `git checkout -b <new> origin/main`',\n            'on-stale-main'),\n        new L2UseCase(16,\n            'Read is blocked, so the session reaches for `cat`, `grep` and `ls` instead — and describes a CI workflow set missing a whole workflow that existed upstream',\n            'the SIDE DOOR: same tree, same staleness, different tool',\n            'BLOCK: `B` is judged here beside `R`, so closing the Read tool no longer opens a shell-shaped hole. The log used to read \"read-stale-guard handled\", which is worse than no guard — it looks covered',\n            '`git checkout -b <new> origin/main`',\n            'on-stale-main'),\n        new L2UseCase(10,\n            'A Bash command that WRITES tracked files as a side effect — `npx expo install`, a formatter, codegen, `sed -i`, a `>` redirect',\n            'on a `main` known to be BEHIND, and the write is incidental to a command whose stated purpose is something else',\n            'BLOCK: inside this row `B` is default-DENY plus row 4\\'s skip list, never a blocklist of readers — a command nobody thought to enumerate is caught by not being on the list, which is the only shape that could have caught this one',\n            '`git checkout -b <new> origin/main` BEFORE running anything that may write',\n            'on-stale-main'),\n    ]),\n    new L2Row(7, ['B', 'R'], 'on `main`, current', L2_ALLOW, '—', [\n        new L2UseCase(17,\n            'Reading files on a `main` you just pulled',\n            'on `main`, and `origin/main` is an ancestor of HEAD',\n            'ALLOW: ancestry, not hash equality, so the allow arrives the instant the pull lands rather than when the detached refresher next runs',\n            'None needed',\n            'local-main-contains-origin (up to date)'),\n        new L2UseCase(24,\n            '`curl`, `gh pr close` or a test run, immediately after `pnpm wp-checkout-clean-main` landed you on a perfectly current `main`',\n            'on `main`, current — no staleness anywhere',\n            'ALLOW. This used to BLOCK, from the branch alone: the tool the repo prescribes put the agent here, and the guard whose name says STALE then refused everything off a narrow allowlist for a reason that had nothing to do with staleness. WRITES here are still blocked, by row 5 — that hazard is real at any freshness',\n            'None needed',\n            'local-main-contains-origin (up to date)'),\n    ]),\n    new L2Row(8, ['B', 'R', 'E'], 'on a branch whose PR is **already merged**', L2_BLOCK, '`git fetch origin main && git checkout -b <new> origin/main`', [\n        new L2UseCase(18,\n            'You keep working on the branch after its PR merged, and the next PR reopens code review already landed',\n            'branch whose PR is merged — `merged` is monotonic, so the cached flag is trusted with no TTL',\n            'BLOCK across all three tools',\n            '`git fetch origin main && git checkout -b <new> origin/main`',\n            'already-merged PR#'),\n        new L2UseCase(26,\n            'You have uncommitted edits on a branch whose PR just merged',\n            'merged branch, dirty tree',\n            'BLOCK. This used to fail open too, and that valve never had an argument behind it — row 8\\'s cure carries uncommitted work onto the fresh branch, so nothing was ever trapped. It was drift from the documented design, which `read-stale-guard`\\'s own class comment still described correctly',\n            '`git fetch origin main && git checkout -b <new> origin/main` — your edits come with you',\n            'already-merged PR#'),\n        new L2UseCase(19,\n            'A shell-only session sails through on a merged branch',\n            'merged branch, Bash only — both FILE guards are file-scoped, so Bash reached neither',\n            'BLOCK: `merged-branch-bash-guard` exists because `branchAlreadyMerged` was being computed and logged on that very path, then thrown away',\n            '`git fetch origin main && git checkout -b <new> origin/main`',\n            'already-merged PR#'),\n    ]),\n    new L2Row(9, ['B', 'R', 'E'], 'no fork point with `origin/main`, or `origin/main` moved and collided with your files', L2_BLOCK, '`pnpm wp-start-update`, or `pnpm wp-start-upsert-pr` when a PR is open', [\n        new L2UseCase(20,\n            'Your branch and `origin/main` share no merge base — usually a branch cut from a squashed-away tip',\n            'no fork point',\n            'BLOCK: nothing built on this branch can be reasoned about relative to main',\n            '`pnpm wp-start-update`, or `pnpm wp-start-upsert-pr` when a PR is open',\n            'no-fork-point'),\n        new L2UseCase(21,\n            '`origin/main` moved and changed the same files you edited',\n            'main-moved collision',\n            'BLOCK — and row 3 then exempts everything once the merge starts, which is what makes this safe',\n            '`pnpm wp-start-update`, resolve, `pnpm wp-finish-upsert-pr`',\n            'main-moved-conflict'),\n    ]),\n    new L2Row(10, ['B', 'R', 'E'], 'healthy feature branch', L2_ALLOW, '—', [\n        new L2UseCase(22,\n            'Ordinary work on a branch cut from a current `origin/main`',\n            'healthy feature branch',\n            'ALLOW — the state every other row exists to push you back into',\n            'None needed',\n            'clean-feature-branch'),\n        new L2UseCase(23,\n            '`stale-main-bash-guard` sees a feature branch and hands off',\n            'not on `main` — state B belongs to `merged-branch-bash-guard`',\n            'ALLOW: the same verdict about the same tree, logged by the guard that is not responsible for it',\n            'None needed',\n            'not-on-main (state B is another guard)'),\n    ]),\n];\n\n/**\n * Every use case on every row, in row order, for the doc and for the exhaustiveness specs.\n *\n * Numbering is GLOBAL and is identity, exactly as the row numbers are: a use case is cited by number in\n * review and in the doc, so add new ones at the END of the highest number rather than renumbering to\n * keep a row's block contiguous.\n */\n// webpieces-disable no-function-outside-class -- pure accessor over L2_ROWS above, in this data module\nexport function allL2UseCases(): readonly L2UseCase[] {\n    return L2_ROWS.flatMap((row: L2Row): readonly L2UseCase[] => row.useCases);\n}\n\n/**\n * REASON → ROW. The join between what a guard actually logged and the row it is an instance of.\n *\n * Keys are the exact `reason` strings the four L2 guards pass to their decision log. Two of them are\n * PREFIXES because the guard interpolates a PR number or a matched segment into the reason\n * (`already-merged PR#123`); those are matched by `l2RowForReason` on prefix, which is why they end in\n * a space or a `(`.\n *\n * l2-matrix.spec.ts reads the four guard sources and asserts every reason literal in them resolves\n * here, so a new exit with no row fails the build rather than logging `row=-` forever.\n */\nconst EXACT_REASON_ROWS: Record<string, number> = {\n    // Row 1 — the universal cure that must stay reachable from inside any block.\n    'webpieces-config-read (escape hatch)': 1,\n    // Row 2 — the preventive half, decided from command TEXT before any cache is read.\n    // (prefix, see PREFIX_REASON_ROWS)\n    // Row 4 — the skip list, in its two live spellings.\n    'merged-branch recovery/inspection (allowlisted)': 4,\n    'not-a-content-read (cure/build/metadata)': 4,\n    // Row 5 — never WRITE on main, at any freshness. `E` only; the Bash half is rows 6/7.\n    'on-main': 5,\n    // Row 6/7 — freshness, for `B` and `R` alike. Both guards log these two literals: read-stale-guard\n    // for the Read tool, stale-main-bash-guard for Bash. Same cache, same ancestry test, one verdict.\n    'on-stale-main': 6,\n    'local-main-contains-origin (up to date)': 7,\n    // Row 9 — the two unhealthy-fork states.\n    'no-fork-point': 9,\n    'main-moved-conflict': 9,\n    // Row 10 — healthy, and the state-B guard's \"this is not my state\" hand-off, which is the same\n    // verdict about the same tree.\n    'clean-feature-branch': 10,\n    'not-on-main (state B is another guard)': 10,\n    // Row 11 — every \"could not establish\", including the two dirty-tree valves the code still opens\n    // (see NOT_DONE) and the unreachable forge.\n    'branch-undeterminable': L2_FAIL_OPEN_ROW,\n    'no-sync-cache': L2_FAIL_OPEN_ROW,\n    'stale-cross-branch-cache': L2_FAIL_OPEN_ROW,\n    'origin-main-unknown': L2_FAIL_OPEN_ROW,\n    // `dirty-tree-on-main` and `dirty-merged-branch` used to live here. Both valves are deleted: rows\n    // 6 and 8 now block on a dirty tree, because each row's cure carries uncommitted work with you.\n    'no-forge': L2_FAIL_OPEN_ROW,\n    // The config-edit bypass logged by the hook adapter before any guard runs — row 1, same universal\n    // cure as the config READ above.\n    'config-bypass (feature-branch-guard skipped)': 1,\n};\n\n/** Reasons the guards interpolate a value into. Matched by prefix, longest first. */\nconst PREFIX_REASON_ROWS: Record<string, number> = {\n    'already-merged PR#': 8,\n    'bare checkout of main (': 2,\n    // `stale-main content read (` used to live here, mapping the Bash side of row 6. It is gone with\n    // the guard exit that emitted it: on `main`, row 5 now blocks before any content-read scan runs,\n    // so row 6 is what the table always said it was — the ROW-ONLY row.\n};\n\n/**\n * The row a logged reason belongs to, or null when nothing claims it.\n *\n * Null rather than a default row: a reason with no row is a HOLE in the table, and defaulting it to\n * \"fail-open\" would hide exactly the drift the exhaustiveness spec exists to catch. The guards render\n * null as `row=-`, so an unmapped reason is visible in the log too, not only in CI.\n */\n// webpieces-disable no-function-outside-class -- the matcher over the two tables above, beside them in this data module\nexport function l2RowForReason(reason: string): number | null {\n    const exact = EXACT_REASON_ROWS[reason];\n    if (exact !== undefined) return exact;\n    for (const prefix of Object.keys(PREFIX_REASON_ROWS)) {\n        if (reason.startsWith(prefix)) return PREFIX_REASON_ROWS[prefix];\n    }\n    return null;\n}\n\n/** Every reason string this table claims, for the exhaustiveness spec. */\n// webpieces-disable no-function-outside-class -- pure accessor over the two tables above\nexport function l2MappedReasons(): readonly string[] {\n    return [...Object.keys(EXACT_REASON_ROWS), ...Object.keys(PREFIX_REASON_ROWS)];\n}\n\n/** One documented gap between a row and what the guards actually do today. Data-only. */\nexport class L2NotDone {\n    constructor(readonly row: number, readonly gap: string, readonly why: string) {}\n}\n\n/**\n * WHERE THE TABLE AND THE CODE DISAGREE, stated rather than papered over.\n *\n * The L1 precedent is `## Not done — \\`o\\` is not exempt yet`: a row the runner cannot reach, named in\n * the generated doc with the reason it has not shipped. The same treatment applies here, and it is what\n * makes it safe to publish a table the guards do not yet dispatch from — a reader is told exactly which\n * rows describe intent rather than behaviour, and the log's `row=` stamps land on row 11 for every one\n * of these, so the trail never claims the strict row fired.\n */\nexport const NOT_DONE: readonly L2NotDone[] = [\n    // EMPTY, and that is the goal state: every row in the table is a row the guards actually honour.\n    //\n    // It held three entries. Row 5's `B` half shipped and then MOVED: on `main`, a write is judged from\n    // the branch alone (row 5, above the divider) while Bash is judged on freshness beside the Read tool\n    // (rows 6/7), because a build on a CURRENT `main` harms nothing and denying it stranded agents on\n    // the very `main` `pnpm wp-checkout-clean-main` had just handed them. Rows 6 and 8 held DIRTY-TREE\n    // valves, and both are now closed — each of\n    // those rows cures with `git checkout -b <new> origin/main`, which carries uncommitted changes onto\n    // the new branch, so a dirty tree never trapped anybody. The row 6 entry claimed the dirty argument\n    // \"has teeth\" there because its cure is `git pull`; that was a fact about the MESSAGE, which printed\n    // only the pull, and the fix was to print both cures rather than to suppress the block.\n    //\n    // Keep this array. An empty \"Not done\" is a claim worth making explicitly — the doc says so in as\n    // many words — and the next divergence between a row and its code belongs here, not in prose.\n];\n"]}

package/src/core/rules/feature-branch-guard.d.ts

@@ -14,6 +14,26 @@ import { FixHint } from '../fix-hint';
  * fire-and-forget spawns the refresher so the NEXT call is fresh. Runs in the GUARDS hook (it's a
  * hookGuard); file-scoped, so only Write/Edit/MultiEdit are guarded — Bash passes through so the AI
  * can still run `pnpm wp-start-upsert-pr` and the rest of the recovery flow.
+ *
+ * ── STATE 1 IS UNCONDITIONAL, AND `B` NO LONGER TRACKS `E` HERE ──────────────────────────────────
+ *
+ * Earlier docblocks in this family argued that the Bash half of "on `main`" should match this one
+ * exactly — one `git rev-parse`, no cache, so it fires on the first call of a session. That argument
+ * has been split, deliberately, and the two halves now differ:
+ *
+ *   `E` (here)                 blocks on ANY `main`, current or stale.
+ *   `B` (stale-main-bash-guard) blocks only once local `main` is KNOWN BEHIND `origin/main`.
+ *
+ * The hazards are not the same hazard. A WRITE on `main` puts work where it cannot be reviewed, cannot
+ * be reverted as a unit, and is one `git checkout` from being lost — none of which depends on how
+ * current `main` is, so nothing about freshness could make this block right or wrong. A READ or a
+ * BUILD on a CURRENT `main` harms nothing at all, and denying it strands the agent immediately after
+ * `pnpm wp-checkout-clean-main` — the very command this repo prescribes — put it there.
+ *
+ * So do NOT "restore the symmetry" by gating this on the cache. That would make writes on `main`
+ * permitted for the whole first call of every session (the cache is populated for the NEXT call), and
+ * permanently in a multi-worktree repo where another tree can hold the refresh lock. That ordering is
+ * the most load-bearing thing in the L2 table, which is why row 5 sits ABOVE the cache divider.
  */
 export declare class FeatureBranchGuardRule extends FileRuleBase<BranchStateGuardConfig> {
     constructor(config: BranchStateGuardConfig);
@@ -53,7 +73,7 @@ export declare class FeatureBranchGuardRule extends FileRuleBase<BranchStateGuar
      * ONE CURE, and it is the dirty-safe one. This half used to print `git pull origin main` and then
      * "create a feature branch" — but this guard fires on a WRITE, so uncommitted work is the LIKELY
      * state, and a pull is exactly the form that is not a clean fast-forward there. Its two siblings
-     * (stale-main-bash-guard's row-5 deny, StaleMainMessage.forReads) both prescribe
+     * (stale-main-bash-guard's rows-6/7 deny, StaleMainMessage.forReads) both prescribe
      * `git fetch origin main && git checkout -b <new> origin/main`, which fetches AND carries the
      * uncommitted work onto the new branch. Three halves of one row printing one cure is the point:
      * a fragile cure is a defect here even when it often happens to work.

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

@@ -26,6 +26,26 @@ const tree_recovery_1 = require("./tree-recovery");
  * fire-and-forget spawns the refresher so the NEXT call is fresh. Runs in the GUARDS hook (it's a
  * hookGuard); file-scoped, so only Write/Edit/MultiEdit are guarded — Bash passes through so the AI
  * can still run `pnpm wp-start-upsert-pr` and the rest of the recovery flow.
+ *
+ * ── STATE 1 IS UNCONDITIONAL, AND `B` NO LONGER TRACKS `E` HERE ──────────────────────────────────
+ *
+ * Earlier docblocks in this family argued that the Bash half of "on `main`" should match this one
+ * exactly — one `git rev-parse`, no cache, so it fires on the first call of a session. That argument
+ * has been split, deliberately, and the two halves now differ:
+ *
+ *   `E` (here)                 blocks on ANY `main`, current or stale.
+ *   `B` (stale-main-bash-guard) blocks only once local `main` is KNOWN BEHIND `origin/main`.
+ *
+ * The hazards are not the same hazard. A WRITE on `main` puts work where it cannot be reviewed, cannot
+ * be reverted as a unit, and is one `git checkout` from being lost — none of which depends on how
+ * current `main` is, so nothing about freshness could make this block right or wrong. A READ or a
+ * BUILD on a CURRENT `main` harms nothing at all, and denying it strands the agent immediately after
+ * `pnpm wp-checkout-clean-main` — the very command this repo prescribes — put it there.
+ *
+ * So do NOT "restore the symmetry" by gating this on the cache. That would make writes on `main`
+ * permitted for the whole first call of every session (the cache is populated for the NEXT call), and
+ * permanently in a multi-worktree repo where another tree can hold the refresh lock. That ordering is
+ * the most load-bearing thing in the L2 table, which is why row 5 sits ABOVE the cache divider.
  */
 class FeatureBranchGuardRule extends rule_base_1.FileRuleBase {
     // NAME is this class's operator identity (every `rule=` in the log, every deny header);
@@ -157,7 +177,7 @@ class FeatureBranchGuardRule extends rule_base_1.FileRuleBase {
      * ONE CURE, and it is the dirty-safe one. This half used to print `git pull origin main` and then
      * "create a feature branch" — but this guard fires on a WRITE, so uncommitted work is the LIKELY
      * state, and a pull is exactly the form that is not a clean fast-forward there. Its two siblings
-     * (stale-main-bash-guard's row-5 deny, StaleMainMessage.forReads) both prescribe
+     * (stale-main-bash-guard's rows-6/7 deny, StaleMainMessage.forReads) both prescribe
      * `git fetch origin main && git checkout -b <new> origin/main`, which fetches AND carries the
      * uncommitted work onto the new branch. Three halves of one row printing one cure is the point:
      * a fragile cure is a defect here even when it often happens to work.

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 { BranchStateGuardConfig, BRANCH_STATE_GUARD_KEY, DEFAULT_HANG_TIMEOUT_MINUTES, readMainSyncStatus, squashRecoverySteps, MainSyncStatus, SyncFlowGuidance, Option } from '@webpieces/rules-config';\n\nimport type { FileContext, Violation } from '../types';\nimport { Violation as V } from '../types';\nimport { FileRuleBase } from '../rule-base';\nimport { FixHint } from '../fix-hint';\nimport { toError } from '../to-error';\nimport { triggerMainSyncRefresh } from '../main-sync-refresh';\nimport { hangTimeoutOf } from '../main-sync-timeout';\nimport { logGuardDecision, GuardDecision, Verdict, matrixL2Row } from '../decision-log';\nimport { writeBranchStateMatrixDoc, branchStateMatrixPointer } from '../l2-matrix-doc';\nimport { L0_FAULT_NONE } from '../l0-fault-codes';\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<BranchStateGuardConfig> {\n    // NAME is this class's operator identity (every `rule=` in the log, every deny header);\n    // CONFIG KEY is the one branch-state policy entry all four of these guards read. See AbstractRule.\n    constructor(config: BranchStateGuardConfig) { super(config, 'feature-branch-guard', BRANCH_STATE_GUARD_KEY); }\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 hookGuards → branch-state-guard (mode OFF) if intentional — that one key governs the Write, Read and Bash halves of this policy together.'),\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.failOpen(ctx, branch, 'branch-undeterminable');\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, hangTimeoutOf(this.config));\n\n        const status = readMainSyncStatus(ctx.workspaceRoot, branch);\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.failOpen(ctx, branch, 'no-sync-cache', 'cache=none');\n\n        const cache = this.cacheSummary(status);\n        // BELT-AND-BRACES since the cache became branch-keyed: we looked this entry up BY `branch`, so\n        // a mismatch now means the map's key and the entry's own `branch` field disagree — a shape bug,\n        // not a normal state. Kept (rather than deleted) so such a bug degrades to an allow instead of\n        // blocking on another branch's signals. Unreachable in normal operation.\n        if (status.branch !== branch) return this.failOpen(ctx, branch, 'stale-cross-branch-cache', 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        // NOT-MERGED, or NOT-ASKED? `branchAlreadyMerged: false` is produced both by \"this branch has\n        // no merged PR\" and by \"the forge could not be reached\" (`gh` missing, unauthenticated,\n        // rate-limited, offline). Same allow either way — never block on data you could not establish\n        // — but the LOG must not call the second one an approval, or the trail cannot tell a policy\n        // that is protecting something from one that is quietly standing down.\n        // Reached only when the branch is NOT merged, HAS a fork point and does NOT conflict. The\n        // last two are pure git; only the first depends on the forge, which is why an unreachable\n        // forge downgrades this to an abstention rather than leaving it a clean approval.\n        if (!status.forgeReachable) return this.failOpen(ctx, branch, 'no-forge', cache);\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    /**\n     * The guard could not ESTABLISH the state it judges on, so it judged nothing.\n     *\n     * A sibling of allow() rather than a reason string passed to it, because the difference has to\n     * reach the LOG as a value: `ALLOW_FAIL_OPEN` vs `ALLOW`. It was previously a `' (fail-open)'`\n     * suffix on the free-text reason, which meant an abstention and a real approval were the same\n     * verdict and the abstentions could not be counted — so nobody could tell whether these guards\n     * were protecting anything or quietly standing down. Never block on data you could not\n     * establish; but say out loud, in a field, that you did not establish it.\n     */\n    private failOpen(ctx: FileContext, branch: string | null, reason: string, cache: string = '-'): readonly Violation[] {\n        this.logDecision(ctx, branch, 'ALLOW_FAIL_OPEN', reason, cache);\n        return [];\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_AI_CURE', reason, cache);\n        // Deliver the matrix and name the row — see stale-main-bash-guard.block for why it is lazy.\n        const pointer = branchStateMatrixPointer(writeBranchStateMatrixDoc(ctx.workspaceRoot), matrixL2Row(reason).row);\n        return [new V(1, ctx.relativePath, message + pointer)];\n    }\n\n    private logDecision(ctx: FileContext, branch: string | null, verdict: Verdict, 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, L0_FAULT_NONE, matrixL2Row(reason)),\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    /**\n     * The Write/Edit half of row 5. Same three points as stale-main-bash-guard's deny, told for THIS\n     * surface: reading main while you plan is legitimate and is not what got blocked; the feature\n     * branch is the unit of work; and a `main` that is behind makes the reads wrong too, so getting\n     * current is not an extra step, it is what makes the plan you are about to write against correct.\n     *\n     * Per-surface, deliberately: this guard sees only Write/Edit, so it says the WRITE was blocked.\n     * (read-stale-guard is the one that can close Read, and only once `main` falls behind.)\n     *\n     * ONE CURE, and it is the dirty-safe one. This half used to print `git pull origin main` and then\n     * \"create a feature branch\" — but this guard fires on a WRITE, so uncommitted work is the LIKELY\n     * state, and a pull is exactly the form that is not a clean fast-forward there. Its two siblings\n     * (stale-main-bash-guard's row-5 deny, StaleMainMessage.forReads) both prescribe\n     * `git fetch origin main && git checkout -b <new> origin/main`, which fetches AND carries the\n     * uncommitted work onto the new branch. Three halves of one row printing one cure is the point:\n     * a fragile cure is a defect here even when it often happens to work.\n     */\n    private onMainMessage(): string {\n        const convention = this.config.branchNamingConvention ?? '{whoami}/{featurename}';\n        return [\n            'Blocked: this is a WRITE on main. Reading main to PLAN is fine — writing here is not, because the feature branch is the unit of work: reviewable, revertable, and not one `git checkout` from being lost.',\n            'And if local main is BEHIND origin/main, what you read here was out of date too — so the fetch below is not an extra step, it is what makes your reads true.',\n            'Branch off origin/main (it fetches first, and uncommitted work comes with you):',\n            '  git fetch origin main && git checkout -b <new-branch> origin/main',\n            `Name <new-branch> by the convention (from webpieces.config.json): ${convention}`,\n            'Example: git fetch origin main && git checkout -b ' + convention.replace(/<[^>]+>/g, 'value') + ' origin/main',\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(workspaceRoot).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"]}
+{"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 { BranchStateGuardConfig, BRANCH_STATE_GUARD_KEY, DEFAULT_HANG_TIMEOUT_MINUTES, readMainSyncStatus, squashRecoverySteps, MainSyncStatus, SyncFlowGuidance, Option } from '@webpieces/rules-config';\n\nimport type { FileContext, Violation } from '../types';\nimport { Violation as V } from '../types';\nimport { FileRuleBase } from '../rule-base';\nimport { FixHint } from '../fix-hint';\nimport { toError } from '../to-error';\nimport { triggerMainSyncRefresh } from '../main-sync-refresh';\nimport { hangTimeoutOf } from '../main-sync-timeout';\nimport { logGuardDecision, GuardDecision, Verdict, matrixL2Row } from '../decision-log';\nimport { writeBranchStateMatrixDoc, branchStateMatrixPointer } from '../l2-matrix-doc';\nimport { L0_FAULT_NONE } from '../l0-fault-codes';\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 *\n * ── STATE 1 IS UNCONDITIONAL, AND `B` NO LONGER TRACKS `E` HERE ──────────────────────────────────\n *\n * Earlier docblocks in this family argued that the Bash half of \"on `main`\" should match this one\n * exactly — one `git rev-parse`, no cache, so it fires on the first call of a session. That argument\n * has been split, deliberately, and the two halves now differ:\n *\n *   `E` (here)                 blocks on ANY `main`, current or stale.\n *   `B` (stale-main-bash-guard) blocks only once local `main` is KNOWN BEHIND `origin/main`.\n *\n * The hazards are not the same hazard. A WRITE on `main` puts work where it cannot be reviewed, cannot\n * be reverted as a unit, and is one `git checkout` from being lost — none of which depends on how\n * current `main` is, so nothing about freshness could make this block right or wrong. A READ or a\n * BUILD on a CURRENT `main` harms nothing at all, and denying it strands the agent immediately after\n * `pnpm wp-checkout-clean-main` — the very command this repo prescribes — put it there.\n *\n * So do NOT \"restore the symmetry\" by gating this on the cache. That would make writes on `main`\n * permitted for the whole first call of every session (the cache is populated for the NEXT call), and\n * permanently in a multi-worktree repo where another tree can hold the refresh lock. That ordering is\n * the most load-bearing thing in the L2 table, which is why row 5 sits ABOVE the cache divider.\n */\nexport class FeatureBranchGuardRule extends FileRuleBase<BranchStateGuardConfig> {\n    // NAME is this class's operator identity (every `rule=` in the log, every deny header);\n    // CONFIG KEY is the one branch-state policy entry all four of these guards read. See AbstractRule.\n    constructor(config: BranchStateGuardConfig) { super(config, 'feature-branch-guard', BRANCH_STATE_GUARD_KEY); }\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 hookGuards → branch-state-guard (mode OFF) if intentional — that one key governs the Write, Read and Bash halves of this policy together.'),\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.failOpen(ctx, branch, 'branch-undeterminable');\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, hangTimeoutOf(this.config));\n\n        const status = readMainSyncStatus(ctx.workspaceRoot, branch);\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.failOpen(ctx, branch, 'no-sync-cache', 'cache=none');\n\n        const cache = this.cacheSummary(status);\n        // BELT-AND-BRACES since the cache became branch-keyed: we looked this entry up BY `branch`, so\n        // a mismatch now means the map's key and the entry's own `branch` field disagree — a shape bug,\n        // not a normal state. Kept (rather than deleted) so such a bug degrades to an allow instead of\n        // blocking on another branch's signals. Unreachable in normal operation.\n        if (status.branch !== branch) return this.failOpen(ctx, branch, 'stale-cross-branch-cache', 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        // NOT-MERGED, or NOT-ASKED? `branchAlreadyMerged: false` is produced both by \"this branch has\n        // no merged PR\" and by \"the forge could not be reached\" (`gh` missing, unauthenticated,\n        // rate-limited, offline). Same allow either way — never block on data you could not establish\n        // — but the LOG must not call the second one an approval, or the trail cannot tell a policy\n        // that is protecting something from one that is quietly standing down.\n        // Reached only when the branch is NOT merged, HAS a fork point and does NOT conflict. The\n        // last two are pure git; only the first depends on the forge, which is why an unreachable\n        // forge downgrades this to an abstention rather than leaving it a clean approval.\n        if (!status.forgeReachable) return this.failOpen(ctx, branch, 'no-forge', cache);\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    /**\n     * The guard could not ESTABLISH the state it judges on, so it judged nothing.\n     *\n     * A sibling of allow() rather than a reason string passed to it, because the difference has to\n     * reach the LOG as a value: `ALLOW_FAIL_OPEN` vs `ALLOW`. It was previously a `' (fail-open)'`\n     * suffix on the free-text reason, which meant an abstention and a real approval were the same\n     * verdict and the abstentions could not be counted — so nobody could tell whether these guards\n     * were protecting anything or quietly standing down. Never block on data you could not\n     * establish; but say out loud, in a field, that you did not establish it.\n     */\n    private failOpen(ctx: FileContext, branch: string | null, reason: string, cache: string = '-'): readonly Violation[] {\n        this.logDecision(ctx, branch, 'ALLOW_FAIL_OPEN', reason, cache);\n        return [];\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_AI_CURE', reason, cache);\n        // Deliver the matrix and name the row — see stale-main-bash-guard.block for why it is lazy.\n        const pointer = branchStateMatrixPointer(writeBranchStateMatrixDoc(ctx.workspaceRoot), matrixL2Row(reason).row);\n        return [new V(1, ctx.relativePath, message + pointer)];\n    }\n\n    private logDecision(ctx: FileContext, branch: string | null, verdict: Verdict, 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, L0_FAULT_NONE, matrixL2Row(reason)),\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    /**\n     * The Write/Edit half of row 5. Same three points as stale-main-bash-guard's deny, told for THIS\n     * surface: reading main while you plan is legitimate and is not what got blocked; the feature\n     * branch is the unit of work; and a `main` that is behind makes the reads wrong too, so getting\n     * current is not an extra step, it is what makes the plan you are about to write against correct.\n     *\n     * Per-surface, deliberately: this guard sees only Write/Edit, so it says the WRITE was blocked.\n     * (read-stale-guard is the one that can close Read, and only once `main` falls behind.)\n     *\n     * ONE CURE, and it is the dirty-safe one. This half used to print `git pull origin main` and then\n     * \"create a feature branch\" — but this guard fires on a WRITE, so uncommitted work is the LIKELY\n     * state, and a pull is exactly the form that is not a clean fast-forward there. Its two siblings\n     * (stale-main-bash-guard's rows-6/7 deny, StaleMainMessage.forReads) both prescribe\n     * `git fetch origin main && git checkout -b <new> origin/main`, which fetches AND carries the\n     * uncommitted work onto the new branch. Three halves of one row printing one cure is the point:\n     * a fragile cure is a defect here even when it often happens to work.\n     */\n    private onMainMessage(): string {\n        const convention = this.config.branchNamingConvention ?? '{whoami}/{featurename}';\n        return [\n            'Blocked: this is a WRITE on main. Reading main to PLAN is fine — writing here is not, because the feature branch is the unit of work: reviewable, revertable, and not one `git checkout` from being lost.',\n            'And if local main is BEHIND origin/main, what you read here was out of date too — so the fetch below is not an extra step, it is what makes your reads true.',\n            'Branch off origin/main (it fetches first, and uncommitted work comes with you):',\n            '  git fetch origin main && git checkout -b <new-branch> origin/main',\n            `Name <new-branch> by the convention (from webpieces.config.json): ${convention}`,\n            'Example: git fetch origin main && git checkout -b ' + convention.replace(/<[^>]+>/g, 'value') + ' origin/main',\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(workspaceRoot).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/main-freshness.d.ts

@@ -0,0 +1,35 @@
+import { MainSyncStatus } from '@webpieces/rules-config';
+/**
+ * The two primitives every "is local `main` stale?" ladder is built out of: the ANCESTRY test, and the
+ * one-line cache summary the decision log records beside the verdict.
+ *
+ * ONE implementation, because two guards now ask the same question of the same cache —
+ * `read-stale-guard` for the Read tool (rows 6/7) and `stale-main-bash-guard` for Bash. The ladders
+ * themselves deliberately stay in the guards: each exit's `reason` string is a LITERAL there, which is
+ * what `l2-matrix.spec.ts` scrapes to prove every exit maps to a row. What must not be written twice is
+ * the predicate — a second copy of the ancestry rule is exactly how the two halves of one row start
+ * disagreeing about whether a pull has landed.
+ */
+export declare class MainFreshness {
+    /**
+     * Is `commit` an ancestor of (i.e. already contained in) HEAD? Local-only and fast — no network.
+     *
+     * ANCESTRY, NOT HASH EQUALITY, and this is the single most important line in the freshness story.
+     * The cached `originMain` is written by the detached refresher and is arbitrarily old, so
+     * `local !== origin` stays true for a while AFTER a successful pull — which would spin the agent
+     * forever against a hash nobody can reach. Asking "does local main already CONTAIN the cached
+     * origin/main?" flips the instant the pull lands, with no refresher round-trip.
+     *
+     * spawnSync, not execSync, precisely because the EXIT CODE is the answer and three outcomes must be
+     * told apart: 0 = ancestor (up to date), 1 = cleanly NOT an ancestor (genuinely behind), anything
+     * else = git could not answer (bad/pruned object, not a repo) which must fail OPEN. execSync
+     * collapses 1 and "git broke" into the same thrown Error, so it cannot make that call. The
+     * arg-array form also means the commit hash is never parsed by a shell.
+     */
+    containsOriginMain(workspaceRoot: string, commit: string): boolean;
+    /**
+     * The async-written cache that drove this decision, as one log field — so a wrong allow/block is
+     * traceable to the exact (possibly stale) `main-sync-status.json` that produced it.
+     */
+    summarize(status: MainSyncStatus): string;
+}

package/src/core/rules/main-freshness.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MainFreshness = void 0;
+const child_process_1 = require("child_process");
+/**
+ * The two primitives every "is local `main` stale?" ladder is built out of: the ANCESTRY test, and the
+ * one-line cache summary the decision log records beside the verdict.
+ *
+ * ONE implementation, because two guards now ask the same question of the same cache —
+ * `read-stale-guard` for the Read tool (rows 6/7) and `stale-main-bash-guard` for Bash. The ladders
+ * themselves deliberately stay in the guards: each exit's `reason` string is a LITERAL there, which is
+ * what `l2-matrix.spec.ts` scrapes to prove every exit maps to a row. What must not be written twice is
+ * the predicate — a second copy of the ancestry rule is exactly how the two halves of one row start
+ * disagreeing about whether a pull has landed.
+ */
+class MainFreshness {
+    /**
+     * Is `commit` an ancestor of (i.e. already contained in) HEAD? Local-only and fast — no network.
+     *
+     * ANCESTRY, NOT HASH EQUALITY, and this is the single most important line in the freshness story.
+     * The cached `originMain` is written by the detached refresher and is arbitrarily old, so
+     * `local !== origin` stays true for a while AFTER a successful pull — which would spin the agent
+     * forever against a hash nobody can reach. Asking "does local main already CONTAIN the cached
+     * origin/main?" flips the instant the pull lands, with no refresher round-trip.
+     *
+     * spawnSync, not execSync, precisely because the EXIT CODE is the answer and three outcomes must be
+     * told apart: 0 = ancestor (up to date), 1 = cleanly NOT an ancestor (genuinely behind), anything
+     * else = git could not answer (bad/pruned object, not a repo) which must fail OPEN. execSync
+     * collapses 1 and "git broke" into the same thrown Error, so it cannot make that call. The
+     * arg-array form also means the commit hash is never parsed by a shell.
+     */
+    containsOriginMain(workspaceRoot, commit) {
+        const result = (0, child_process_1.spawnSync)('git', ['merge-base', '--is-ancestor', commit, 'HEAD'], {
+            cwd: workspaceRoot,
+            encoding: 'utf8',
+        });
+        if (result.status === 0)
+            return true;
+        if (result.status === 1)
+            return false;
+        return true; // unknown/failed → treat as "contained" so the guard allows
+    }
+    /**
+     * The async-written cache that drove this decision, as one log field — so a wrong allow/block is
+     * traceable to the exact (possibly stale) `main-sync-status.json` that produced it.
+     */
+    summarize(status) {
+        const merged = status.branchAlreadyMerged ? `PR#${status.mergedPr !== '' ? status.mergedPr : '?'}` : 'no';
+        return `cache=${status.branch} localMain=${status.localMain.slice(0, 8)} originMain=${status.originMain.slice(0, 8)} merged=${merged} ts=${status.timestamp}`;
+    }
+}
+exports.MainFreshness = MainFreshness;
+//# sourceMappingURL=main-freshness.js.map

package/src/core/rules/main-freshness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main-freshness.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/main-freshness.ts"],"names":[],"mappings":";;;AAAA,iDAA0C;AAI1C;;;;;;;;;;GAUG;AACH,MAAa,aAAa;IACtB;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,CAAC,aAAqB,EAAE,MAAc;QACpD,MAAM,MAAM,GAAG,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE;YAC7E,GAAG,EAAE,aAAa;YAClB,QAAQ,EAAE,MAAM;SACnB,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACrC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACtC,OAAO,IAAI,CAAC,CAAC,4DAA4D;IAC7E,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,MAAsB;QAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAC1G,OAAO,SAAS,MAAM,CAAC,MAAM,cAAc,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,eAAe,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,MAAM,OAAO,MAAM,CAAC,SAAS,EAAE,CAAC;IAClK,CAAC;CACJ;AAlCD,sCAkCC","sourcesContent":["import { spawnSync } from 'child_process';\n\nimport { MainSyncStatus } from '@webpieces/rules-config';\n\n/**\n * The two primitives every \"is local `main` stale?\" ladder is built out of: the ANCESTRY test, and the\n * one-line cache summary the decision log records beside the verdict.\n *\n * ONE implementation, because two guards now ask the same question of the same cache —\n * `read-stale-guard` for the Read tool (rows 6/7) and `stale-main-bash-guard` for Bash. The ladders\n * themselves deliberately stay in the guards: each exit's `reason` string is a LITERAL there, which is\n * what `l2-matrix.spec.ts` scrapes to prove every exit maps to a row. What must not be written twice is\n * the predicate — a second copy of the ancestry rule is exactly how the two halves of one row start\n * disagreeing about whether a pull has landed.\n */\nexport class MainFreshness {\n    /**\n     * Is `commit` an ancestor of (i.e. already contained in) HEAD? Local-only and fast — no network.\n     *\n     * ANCESTRY, NOT HASH EQUALITY, and this is the single most important line in the freshness story.\n     * The cached `originMain` is written by the detached refresher and is arbitrarily old, so\n     * `local !== origin` stays true for a while AFTER a successful pull — which would spin the agent\n     * forever against a hash nobody can reach. Asking \"does local main already CONTAIN the cached\n     * origin/main?\" flips the instant the pull lands, with no refresher round-trip.\n     *\n     * spawnSync, not execSync, precisely because the EXIT CODE is the answer and three outcomes must be\n     * told apart: 0 = ancestor (up to date), 1 = cleanly NOT an ancestor (genuinely behind), anything\n     * else = git could not answer (bad/pruned object, not a repo) which must fail OPEN. execSync\n     * collapses 1 and \"git broke\" into the same thrown Error, so it cannot make that call. The\n     * arg-array form also means the commit hash is never parsed by a shell.\n     */\n    containsOriginMain(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    /**\n     * The async-written cache that drove this decision, as one log field — so a wrong allow/block is\n     * traceable to the exact (possibly stale) `main-sync-status.json` that produced it.\n     */\n    summarize(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"]}

package/src/core/rules/merged-branch-bash-guard.js

@@ -58,7 +58,7 @@ class MergedBranchBashGuardRule extends rule_base_1.BashRuleBase {
     };
     fixHint = new fix_hint_1.FixHint('This branch is already merged into main — do not keep working here.', 'Get onto a fresh branch off origin/main, then retry:', [
         new rules_config_1.Option('git fetch origin main && git checkout -b <new-branch> origin/main (in a worktree: git worktree add ../<dir> -b <new> origin/main). Then re-run your command.', true),
-        new rules_config_1.Option('Still allowed here: recovery/cleanup git, read-only git status|log|diff|show|branch and gh pr list|view, switching branches/worktrees, pnpm wp-checkout-clean-main and pnpm wp-cleanup, and installs/upgrades.'),
+        new rules_config_1.Option('Still allowed here: recovery/cleanup git, read-only git status|log|diff|show|branch, gh GENERALLY (it talks to GitHub, not to this tree — but not gh repo clone / pr checkout / run download, which write local files), curl/wget without -o/-O or a > redirect, switching branches/worktrees, pnpm wp-checkout-clean-main and pnpm wp-cleanup, and installs/upgrades.'),
         new rules_config_1.Option('Disable in webpieces.config.json under hookGuards → branch-state-guard (mode OFF) if intentional — that one key governs the Write, Read and Bash halves of this policy together.'),
     ]);
     check(ctx) {

package/src/core/rules/merged-branch-bash-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"merged-branch-bash-guard.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/merged-branch-bash-guard.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync } from 'child_process';\n\nimport { BranchStateGuardConfig, BRANCH_STATE_GUARD_KEY, DEFAULT_HANG_TIMEOUT_MINUTES, readMainSyncStatus, MainSyncStatus, Option } 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 { toError } from '../to-error';\nimport { triggerMainSyncRefresh } from '../main-sync-refresh';\nimport { hangTimeoutOf } from '../main-sync-timeout';\nimport { logGuardDecision, GuardDecision, Verdict, matrixL2Row } from '../decision-log';\nimport { writeBranchStateMatrixDoc, branchStateMatrixPointer } from '../l2-matrix-doc';\nimport { L0_FAULT_NONE } from '../l0-fault-codes';\nimport { CommandScanner } from '../command-scan';\nimport { MergedBranchMessage } from './merged-branch-message';\nimport { TreeRecovery } from './tree-recovery';\nimport { RecoveryAllowlist } from './recovery-allowlist';\n\n/**\n * The BASH half of the merged-branch protection — the gap that let a whole session run on an\n * already-merged branch.\n *\n * feature-branch-guard blocks Write/Edit and read-stale-guard blocks the Read tool when the\n * checked-out branch's PR is already merged into main, but BOTH are file-scoped: a `runBash()` command\n * never reaches either. So an agent that only ran shell — `scripts/local.sh start lang` (boots\n * servers), `cat`/`ls` of repo files, git — sailed through, even though the very same\n * `branchAlreadyMerged` flag was loaded and logged on the Bash path (the `calls/` stream →\n * `merged=PR#…`). It was computed and thrown away; nothing consulted it for a block.\n *\n * Those two file guards intentionally leave Bash alone (\"every cure is a Bash command, so Bash is the\n * escape hatch — never wedge it\"). This guard therefore DEFAULT-DENIES Bash on a merged branch but\n * allowlists exactly the commands that get you OFF the branch (the fresh-start / cleanup git commands,\n * switching away, read-only orientation, wp-* cleanup, installs). The redirect it returns names those\n * same commands, so following it can never re-trip the guard — the agent is redirected, not wedged.\n *\n * FAIL-OPEN like its siblings: branch undeterminable, no cache yet, or a cache for a DIFFERENT branch\n * → allow. The cache is per-branch (`status.branch` is the branch it was computed FOR), so acting on\n * another branch's snapshot is never allowed.\n *\n * On the DELIBERATELY-UNFIXED staleness window: the cache is only as fresh as the last detached\n * refresh, so for a few seconds after a merge lands mid-session it can still read `merged=NO` and this\n * guard fails open. That window is tiny and self-closing — agents burst tool calls every few seconds\n * and every Bash call re-triggers the refresh, so `branchAlreadyMerged` flips within 1–3 calls and the\n * next command is caught. Closing it synchronously would require the slow `gh pr list` on the blocking\n * path (the thing the whole cache design avoids) and would mean blocking on stale/uncertain data,\n * which violates the fail-open principle every one of these guards is built on. Not worth it.\n */\nexport class MergedBranchBashGuardRule extends BashRuleBase<BranchStateGuardConfig> {\n    constructor(config: BranchStateGuardConfig) { super(config, 'merged-branch-bash-guard', BRANCH_STATE_GUARD_KEY); }\n\n    private readonly scanner = new CommandScanner();\n    // ROW 4, the skip list — shared with stale-main-bash-guard so the two states cannot drift apart\n    // about what \"gets you out\" means. See recovery-allowlist.ts.\n    private readonly recoveryList = new RecoveryAllowlist(this.scanner);\n\n    readonly description =\n        'Block ordinary Bash on an already-merged branch (allowlisting only recovery/cleanup and ' +\n        'read-only inspection commands), so a session cannot proceed on a stale post-merge branch.';\n    override readonly defaultOptions = {\n        hangTimeoutMinutes: DEFAULT_HANG_TIMEOUT_MINUTES,\n    };\n    readonly fixHint = new FixHint(\n        'This branch is already merged into main — do not keep working here.',\n        'Get onto a fresh branch off origin/main, then retry:',\n        [\n            new Option('git fetch origin main && git checkout -b <new-branch> origin/main (in a worktree: git worktree add ../<dir> -b <new> origin/main). Then re-run your command.', true),\n            new Option('Still allowed here: recovery/cleanup git, read-only git status|log|diff|show|branch and gh pr list|view, switching branches/worktrees, pnpm wp-checkout-clean-main and pnpm wp-cleanup, and installs/upgrades.'),\n            new Option('Disable in webpieces.config.json under hookGuards → branch-state-guard (mode OFF) if intentional — that one key governs the Write, Read and Bash halves of this policy together.'),\n        ],\n    );\n\n    check(ctx: BashContext): readonly Violation[] {\n        const branch = this.currentBranch(ctx.workspaceRoot);\n        // Can't determine the branch (not a git repo, git unavailable) → never block. Fail-open.\n        if (branch === null) return this.failOpen(ctx, branch, 'branch-undeterminable');\n\n        // Keep the shared cache warm for the next call. Detached; never blocks this command. (The\n        // runner also warms it, but only when feature-branch-guard is loaded — do it here too so this\n        // guard is self-sufficient when that one is off.)\n        triggerMainSyncRefresh(ctx.workspaceRoot, hangTimeoutOf(this.config));\n\n        const status = readMainSyncStatus(ctx.workspaceRoot, branch);\n        // No cache yet (first command of the session), or a branch this refresh has not seen → allow;\n        // the refresh we just spawned populates it.\n        if (status === null) return this.failOpen(ctx, branch, 'no-sync-cache', 'cache=none');\n\n        const cache = this.cacheSummary(status);\n        // BELT-AND-BRACES since the cache became branch-keyed: the entry was looked up BY `branch`, so\n        // a mismatch is a shape bug rather than the old \"cache is for another branch\" state. Kept so\n        // such a bug degrades to an allow. Unreachable in normal operation.\n        if (status.branch !== branch) return this.failOpen(ctx, branch, 'stale-cross-branch-cache', cache);\n\n        // NOT-MERGED, or NOT-ASKED? `branchAlreadyMerged: false` is produced both by \"this branch has\n        // no merged PR\" and by \"the forge could not be reached\" (`gh` missing, unauthenticated,\n        // rate-limited, offline). Same allow either way — never block on data you could not establish\n        // — but the LOG must not call the second one an approval, or the trail cannot tell a policy\n        // that is protecting something from one that is quietly standing down.\n        // For THIS guard the merged flag is the ONLY block condition, so an unreachable forge means\n        // it is fully abstaining — the state it exists to catch cannot be observed at all.\n        if (!status.branchAlreadyMerged) {\n            return status.forgeReachable\n                ? this.allow(ctx, branch, 'clean-feature-branch', cache)\n                : this.failOpen(ctx, branch, 'no-forge', cache);\n        }\n\n        // Merged. Allow ONLY when every segment of the command is a recovery / cleanup / read-only\n        // inspection command — anything else (servers, builds, tests, cat/ls of repo files, git writes)\n        // is denied with the redirect.\n        if (this.recoveryList.isFullyRecovery(ctx)) {\n            return this.allow(ctx, branch, 'merged-branch recovery/inspection (allowlisted)', cache);\n        }\n\n        const pr = status.mergedPr !== '' ? status.mergedPr : '?';\n        return this.block(ctx, branch, `already-merged PR#${pr}`, this.mergedMessage(ctx.workspaceRoot, branch, status.mergedPr), cache);\n    }\n\n    private mergedMessage(workspaceRoot: string, branch: string, mergedPr: string): string {\n        return new MergedBranchMessage(workspaceRoot).forBash(\n            branch, mergedPr, new TreeRecovery().kindOf(workspaceRoot), workspaceRoot,\n        );\n    }\n\n    // One-line summary of the async-written cache that drove this decision (mirrors the file guards),\n    // so a wrong allow/block is traceable to the exact 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} conflict=${String(status.conflict)} ts=${status.timestamp}`;\n    }\n\n    /**\n     * The guard could not ESTABLISH the state it judges on, so it judged nothing.\n     *\n     * A sibling of allow() rather than a reason string passed to it, because the difference has to\n     * reach the LOG as a value: `ALLOW_FAIL_OPEN` vs `ALLOW`. It was previously a `' (fail-open)'`\n     * suffix on the free-text reason, which meant an abstention and a real approval were the same\n     * verdict and the abstentions could not be counted — so nobody could tell whether these guards\n     * were protecting anything or quietly standing down. Never block on data you could not\n     * establish; but say out loud, in a field, that you did not establish it.\n     */\n    private failOpen(ctx: BashContext, branch: string | null, reason: string, cache: string = '-'): readonly Violation[] {\n        this.logDecision(ctx, branch, 'ALLOW_FAIL_OPEN', reason, cache);\n        return [];\n    }\n\n    private allow(ctx: BashContext, 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: BashContext, branch: string, reason: string, message: string, cache: string = '-'): readonly Violation[] {\n        this.logDecision(ctx, branch, 'BLOCK_AI_CURE', reason, cache);\n        // Deliver the matrix and name the row — see stale-main-bash-guard.block for why it is lazy.\n        const pointer = branchStateMatrixPointer(writeBranchStateMatrixDoc(ctx.workspaceRoot), matrixL2Row(reason).row);\n        return [new V(1, this.truncate(ctx.command), message + pointer)];\n    }\n\n    private truncate(s: string): string {\n        const MAX = 120;\n        return s.length <= MAX ? s : s.slice(0, MAX) + '…';\n    }\n\n    private logDecision(ctx: BashContext, branch: string | null, verdict: Verdict, reason: string, cache: string): void {\n        logGuardDecision(\n            ctx.workspaceRoot,\n            new GuardDecision('merged-branch-bash-guard', 'Bash', ctx.command, branch ?? 'unknown', verdict, reason, cache, L0_FAULT_NONE, matrixL2Row(reason)),\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\n// git subcommands that are recovery/cleanup OR read-only orientation, and so stay allowed on a merged\n// branch. Everything NOT here (commit, merge, rebase, push, reset, add, restore, clean, cherry-pick,\n// …) is a \"keep working\" operation and is denied with the redirect. `worktree` covers add/remove/prune\n// (branch-creation-guard governs which worktree adds are legal); `branch` covers listing and `-D`\n// cleanup (branch-creation-guard governs creation); `pull` is the on-main update, itself gated by\n// redirect-how-to-merge-main. Reading git METADATA (log/diff/show) is fine — it is not the stale FILE\n// CONTENT that `cat` would surface, which is exactly why `git grep` (reads tracked content) is absent.\n"]}
+{"version":3,"file":"merged-branch-bash-guard.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/merged-branch-bash-guard.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync } from 'child_process';\n\nimport { BranchStateGuardConfig, BRANCH_STATE_GUARD_KEY, DEFAULT_HANG_TIMEOUT_MINUTES, readMainSyncStatus, MainSyncStatus, Option } 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 { toError } from '../to-error';\nimport { triggerMainSyncRefresh } from '../main-sync-refresh';\nimport { hangTimeoutOf } from '../main-sync-timeout';\nimport { logGuardDecision, GuardDecision, Verdict, matrixL2Row } from '../decision-log';\nimport { writeBranchStateMatrixDoc, branchStateMatrixPointer } from '../l2-matrix-doc';\nimport { L0_FAULT_NONE } from '../l0-fault-codes';\nimport { CommandScanner } from '../command-scan';\nimport { MergedBranchMessage } from './merged-branch-message';\nimport { TreeRecovery } from './tree-recovery';\nimport { RecoveryAllowlist } from './recovery-allowlist';\n\n/**\n * The BASH half of the merged-branch protection — the gap that let a whole session run on an\n * already-merged branch.\n *\n * feature-branch-guard blocks Write/Edit and read-stale-guard blocks the Read tool when the\n * checked-out branch's PR is already merged into main, but BOTH are file-scoped: a `runBash()` command\n * never reaches either. So an agent that only ran shell — `scripts/local.sh start lang` (boots\n * servers), `cat`/`ls` of repo files, git — sailed through, even though the very same\n * `branchAlreadyMerged` flag was loaded and logged on the Bash path (the `calls/` stream →\n * `merged=PR#…`). It was computed and thrown away; nothing consulted it for a block.\n *\n * Those two file guards intentionally leave Bash alone (\"every cure is a Bash command, so Bash is the\n * escape hatch — never wedge it\"). This guard therefore DEFAULT-DENIES Bash on a merged branch but\n * allowlists exactly the commands that get you OFF the branch (the fresh-start / cleanup git commands,\n * switching away, read-only orientation, wp-* cleanup, installs). The redirect it returns names those\n * same commands, so following it can never re-trip the guard — the agent is redirected, not wedged.\n *\n * FAIL-OPEN like its siblings: branch undeterminable, no cache yet, or a cache for a DIFFERENT branch\n * → allow. The cache is per-branch (`status.branch` is the branch it was computed FOR), so acting on\n * another branch's snapshot is never allowed.\n *\n * On the DELIBERATELY-UNFIXED staleness window: the cache is only as fresh as the last detached\n * refresh, so for a few seconds after a merge lands mid-session it can still read `merged=NO` and this\n * guard fails open. That window is tiny and self-closing — agents burst tool calls every few seconds\n * and every Bash call re-triggers the refresh, so `branchAlreadyMerged` flips within 1–3 calls and the\n * next command is caught. Closing it synchronously would require the slow `gh pr list` on the blocking\n * path (the thing the whole cache design avoids) and would mean blocking on stale/uncertain data,\n * which violates the fail-open principle every one of these guards is built on. Not worth it.\n */\nexport class MergedBranchBashGuardRule extends BashRuleBase<BranchStateGuardConfig> {\n    constructor(config: BranchStateGuardConfig) { super(config, 'merged-branch-bash-guard', BRANCH_STATE_GUARD_KEY); }\n\n    private readonly scanner = new CommandScanner();\n    // ROW 4, the skip list — shared with stale-main-bash-guard so the two states cannot drift apart\n    // about what \"gets you out\" means. See recovery-allowlist.ts.\n    private readonly recoveryList = new RecoveryAllowlist(this.scanner);\n\n    readonly description =\n        'Block ordinary Bash on an already-merged branch (allowlisting only recovery/cleanup and ' +\n        'read-only inspection commands), so a session cannot proceed on a stale post-merge branch.';\n    override readonly defaultOptions = {\n        hangTimeoutMinutes: DEFAULT_HANG_TIMEOUT_MINUTES,\n    };\n    readonly fixHint = new FixHint(\n        'This branch is already merged into main — do not keep working here.',\n        'Get onto a fresh branch off origin/main, then retry:',\n        [\n            new Option('git fetch origin main && git checkout -b <new-branch> origin/main (in a worktree: git worktree add ../<dir> -b <new> origin/main). Then re-run your command.', true),\n            new Option('Still allowed here: recovery/cleanup git, read-only git status|log|diff|show|branch, gh GENERALLY (it talks to GitHub, not to this tree — but not gh repo clone / pr checkout / run download, which write local files), curl/wget without -o/-O or a > redirect, switching branches/worktrees, pnpm wp-checkout-clean-main and pnpm wp-cleanup, and installs/upgrades.'),\n            new Option('Disable in webpieces.config.json under hookGuards → branch-state-guard (mode OFF) if intentional — that one key governs the Write, Read and Bash halves of this policy together.'),\n        ],\n    );\n\n    check(ctx: BashContext): readonly Violation[] {\n        const branch = this.currentBranch(ctx.workspaceRoot);\n        // Can't determine the branch (not a git repo, git unavailable) → never block. Fail-open.\n        if (branch === null) return this.failOpen(ctx, branch, 'branch-undeterminable');\n\n        // Keep the shared cache warm for the next call. Detached; never blocks this command. (The\n        // runner also warms it, but only when feature-branch-guard is loaded — do it here too so this\n        // guard is self-sufficient when that one is off.)\n        triggerMainSyncRefresh(ctx.workspaceRoot, hangTimeoutOf(this.config));\n\n        const status = readMainSyncStatus(ctx.workspaceRoot, branch);\n        // No cache yet (first command of the session), or a branch this refresh has not seen → allow;\n        // the refresh we just spawned populates it.\n        if (status === null) return this.failOpen(ctx, branch, 'no-sync-cache', 'cache=none');\n\n        const cache = this.cacheSummary(status);\n        // BELT-AND-BRACES since the cache became branch-keyed: the entry was looked up BY `branch`, so\n        // a mismatch is a shape bug rather than the old \"cache is for another branch\" state. Kept so\n        // such a bug degrades to an allow. Unreachable in normal operation.\n        if (status.branch !== branch) return this.failOpen(ctx, branch, 'stale-cross-branch-cache', cache);\n\n        // NOT-MERGED, or NOT-ASKED? `branchAlreadyMerged: false` is produced both by \"this branch has\n        // no merged PR\" and by \"the forge could not be reached\" (`gh` missing, unauthenticated,\n        // rate-limited, offline). Same allow either way — never block on data you could not establish\n        // — but the LOG must not call the second one an approval, or the trail cannot tell a policy\n        // that is protecting something from one that is quietly standing down.\n        // For THIS guard the merged flag is the ONLY block condition, so an unreachable forge means\n        // it is fully abstaining — the state it exists to catch cannot be observed at all.\n        if (!status.branchAlreadyMerged) {\n            return status.forgeReachable\n                ? this.allow(ctx, branch, 'clean-feature-branch', cache)\n                : this.failOpen(ctx, branch, 'no-forge', cache);\n        }\n\n        // Merged. Allow ONLY when every segment of the command is a recovery / cleanup / read-only\n        // inspection command — anything else (servers, builds, tests, cat/ls of repo files, git writes)\n        // is denied with the redirect.\n        if (this.recoveryList.isFullyRecovery(ctx)) {\n            return this.allow(ctx, branch, 'merged-branch recovery/inspection (allowlisted)', cache);\n        }\n\n        const pr = status.mergedPr !== '' ? status.mergedPr : '?';\n        return this.block(ctx, branch, `already-merged PR#${pr}`, this.mergedMessage(ctx.workspaceRoot, branch, status.mergedPr), cache);\n    }\n\n    private mergedMessage(workspaceRoot: string, branch: string, mergedPr: string): string {\n        return new MergedBranchMessage(workspaceRoot).forBash(\n            branch, mergedPr, new TreeRecovery().kindOf(workspaceRoot), workspaceRoot,\n        );\n    }\n\n    // One-line summary of the async-written cache that drove this decision (mirrors the file guards),\n    // so a wrong allow/block is traceable to the exact 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} conflict=${String(status.conflict)} ts=${status.timestamp}`;\n    }\n\n    /**\n     * The guard could not ESTABLISH the state it judges on, so it judged nothing.\n     *\n     * A sibling of allow() rather than a reason string passed to it, because the difference has to\n     * reach the LOG as a value: `ALLOW_FAIL_OPEN` vs `ALLOW`. It was previously a `' (fail-open)'`\n     * suffix on the free-text reason, which meant an abstention and a real approval were the same\n     * verdict and the abstentions could not be counted — so nobody could tell whether these guards\n     * were protecting anything or quietly standing down. Never block on data you could not\n     * establish; but say out loud, in a field, that you did not establish it.\n     */\n    private failOpen(ctx: BashContext, branch: string | null, reason: string, cache: string = '-'): readonly Violation[] {\n        this.logDecision(ctx, branch, 'ALLOW_FAIL_OPEN', reason, cache);\n        return [];\n    }\n\n    private allow(ctx: BashContext, 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: BashContext, branch: string, reason: string, message: string, cache: string = '-'): readonly Violation[] {\n        this.logDecision(ctx, branch, 'BLOCK_AI_CURE', reason, cache);\n        // Deliver the matrix and name the row — see stale-main-bash-guard.block for why it is lazy.\n        const pointer = branchStateMatrixPointer(writeBranchStateMatrixDoc(ctx.workspaceRoot), matrixL2Row(reason).row);\n        return [new V(1, this.truncate(ctx.command), message + pointer)];\n    }\n\n    private truncate(s: string): string {\n        const MAX = 120;\n        return s.length <= MAX ? s : s.slice(0, MAX) + '…';\n    }\n\n    private logDecision(ctx: BashContext, branch: string | null, verdict: Verdict, reason: string, cache: string): void {\n        logGuardDecision(\n            ctx.workspaceRoot,\n            new GuardDecision('merged-branch-bash-guard', 'Bash', ctx.command, branch ?? 'unknown', verdict, reason, cache, L0_FAULT_NONE, matrixL2Row(reason)),\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\n// git subcommands that are recovery/cleanup OR read-only orientation, and so stay allowed on a merged\n// branch. Everything NOT here (commit, merge, rebase, push, reset, add, restore, clean, cherry-pick,\n// …) is a \"keep working\" operation and is denied with the redirect. `worktree` covers add/remove/prune\n// (branch-creation-guard governs which worktree adds are legal); `branch` covers listing and `-D`\n// cleanup (branch-creation-guard governs creation); `pull` is the on-main update, itself gated by\n// redirect-how-to-merge-main. Reading git METADATA (log/diff/show) is fine — it is not the stale FILE\n// CONTENT that `cat` would surface, which is exactly why `git grep` (reads tracked content) is absent.\n"]}

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

@@ -56,7 +56,8 @@ class MergedBranchMessage {
         return [
             'Still allowed while this block is up (these get you OFF this branch — run one, then retry):',
             '  - the fresh-start / cleanup git commands above',
-            '  - read-only orientation: git status|log|diff|show|branch, gh pr list|view|status, gh run view|list|watch',
+            '  - read-only orientation: git status|log|diff|show|branch',
+            '  - gh GENERALLY (pr view, pr close, pr comment, api, run watch — it talks to GitHub, not to this tree), and curl/wget; NOT gh repo clone / pr checkout / run download, curl -o, or any `> file`, which write here',
             switching,
             '  - pnpm wp-checkout-clean-main, pnpm wp-cleanup and the gated wp-start-*/wp-finish-* commands, pnpm install / upgrades',
             '  - output shaping on any of the above: `… 2>&1 | tail -40`, `… | head -5`, `…; echo done`',