@webpieces/ai-hook-rules 0.4.644 → 0.4.646

package/src/core/l2-rows.js

@@ -34,7 +34,8 @@
 // package's transitive dependencies.
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NOT_DONE = exports.L2NotDone = exports.L2_ROWS = exports.L2Row = exports.L2_FAIL_OPEN = exports.L2_BLOCK = exports.L2_EXEMPT = exports.L2_ALLOW = exports.L2Action = exports.L2_FAIL_OPEN_ROW = void 0;
+exports.NOT_DONE = exports.L2NotDone = exports.L2_ROWS = exports.L2Row = exports.NO_ROW_EXIT = exports.L2UseCase = exports.L2_FAIL_OPEN = exports.L2_BLOCK = exports.L2_EXEMPT = exports.L2_ALLOW = exports.L2Action = exports.L2_FAIL_OPEN_ROW = void 0;
+exports.allL2UseCases = allL2UseCases;
 exports.l2RowForReason = l2RowForReason;
 exports.l2MappedReasons = l2MappedReasons;
 /**
@@ -67,6 +68,50 @@ exports.L2_ALLOW = new L2Action('1 allow', 'allow');
 exports.L2_EXEMPT = new L2Action('2 exempt', 'exempt');
 exports.L2_BLOCK = new L2Action('4 block', 'block');
 exports.L2_FAIL_OPEN = new L2Action('1 allow (fail-open)', 'fail-open');
+/**
+ * One row of the "L2 use cases" table: what you SEE, the state it puts you in, the verdict, the fix.
+ *
+ * THE POINT OF THIS CLASS is that a use case is added HERE, in code, beside the row it exercises — not
+ * into a hand-written doc section that drifts. When a new situation comes up in a session, it becomes
+ * one more `new L2UseCase(...)` on the row that judged it, `pnpm guards:generate` re-renders the doc,
+ * and the byte-lock spec fails if anyone edits the rendered table instead.
+ *
+ * The four text fields are rendered VERBATIM. `reason` is the ENFORCEMENT half and is never rendered:
+ * it is the exact `reason` string the guard logs for this case, so a spec can push it back through
+ * `l2RowForReason` and assert it lands on the row this use case is filed under. That closes the loop
+ * the L2 decision log opens — `row=` in the trail, this table on the page, one join between them.
+ *
+ * `reason` is REQUIRED, and a case that exercises something which is not an L2 row exit says so with
+ * `NO_ROW_EXIT` rather than by omitting the argument. An optional field would make opting OUT of the
+ * only real enforcement here the shortest thing to type and impossible to grep — the widening-by-absence
+ * shape CLAUDE.md rejects. `grep NO_ROW_EXIT` now lists every unenforced case.
+ */
+class L2UseCase {
+    num;
+    symptom;
+    state;
+    verdict;
+    fix;
+    reason;
+    // eslint-disable-next-line @typescript-eslint/max-params -- four verbatim doc cells plus the reason behind them
+    constructor(num, symptom, state, verdict, fix, reason) {
+        this.num = num;
+        this.symptom = symptom;
+        this.state = state;
+        this.verdict = verdict;
+        this.fix = fix;
+        this.reason = reason;
+    }
+}
+exports.L2UseCase = L2UseCase;
+/**
+ * The `reason` for a use case that is NOT an L2 row exit, and so has nothing to join back to.
+ *
+ * The only legitimate case today is row 3: merge-in-progress is L4's state, and L2 exempts it without
+ * logging a reason of its own. Named rather than absent, so "this case is not enforced" is a value in
+ * the table you can grep for instead of a missing argument nobody notices.
+ */
+exports.NO_ROW_EXIT = 'NO_ROW_EXIT (not an L2 row exit — another layer owns this state)';
 /**
  * One row of L2's decision table.
  *
@@ -81,17 +126,28 @@ class L2Row {
     state;
     action;
     cure;
-    // eslint-disable-next-line @typescript-eslint/max-params -- the five cells of one doc row
+    useCases;
+    // eslint-disable-next-line @typescript-eslint/max-params -- the five cells of one doc row plus its use cases
     constructor(num, tools, 
     /** The `state` cell, verbatim. */
     state, action, 
     /** The `cure` cell, verbatim. `—` when the row allows. */
-    cure) {
+    cure, 
+    /**
+     * The observed situations this row judges. Rendered as the "L2 use cases" table.
+     *
+     * A NON-EMPTY tuple, and required: a row nobody has ever seen fire is either dead or
+     * undocumented, and both are worth knowing. Expressing that in the TYPE rather than as a
+     * runtime assertion is the JwtRoles pattern — the invariant is enforced at the moment the row
+     * is written, which is the only moment that changes what somebody types.
+     */
+    useCases) {
         this.num = num;
         this.tools = tools;
         this.state = state;
         this.action = action;
         this.cure = cure;
+        this.useCases = useCases;
     }
     /** `B R E`, the doc's own spelling of the tool cell. */
     toolCell() {
@@ -115,18 +171,65 @@ exports.L2Row = L2Row;
  * behind.
  */
 exports.L2_ROWS = [
-    new L2Row(1, ['B', 'R', 'E'], 'on the **global allowlist** (inert command, or a universal cure such as reading/editing `webpieces.config.json`)', exports.L2_ALLOW, '—'),
-    new L2Row(2, ['B'], 'bare `git checkout main`, with no `git pull` chained into the same command', exports.L2_BLOCK, '`git checkout main && git pull origin main`'),
-    new L2Row(3, ['B', 'R', 'E'], '**merge in progress** — L4 owns this state', exports.L2_EXEMPT, 'finish the merge: `pnpm wp-finish-upsert-pr`'),
-    new L2Row(4, ['B'], 'on the **skip list** — it gets you OUT, or tells you where you are', exports.L2_ALLOW, '—'),
-    new L2Row(5, ['B', 'E'], 'on `main`', exports.L2_BLOCK, '`git checkout -b <new> origin/main`'),
-    new L2Row(exports.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, the forge unreachable, or a dirty tree whose cure is not a clean fast-forward', exports.L2_FAIL_OPEN, '— (nothing to fix; the refresher populates the cache for the next call)'),
-    new L2Row(6, ['R'], 'on `main`, behind `origin/main`', exports.L2_BLOCK, '`git pull origin main`, or `git checkout -b <new> origin/main`'),
-    new L2Row(7, ['R'], 'on `main`, current', exports.L2_ALLOW, '—'),
-    new L2Row(8, ['B', 'R', 'E'], 'on a branch whose PR is **already merged**', exports.L2_BLOCK, '`git fetch origin main && git checkout -b <new> origin/main`'),
-    new L2Row(9, ['B', 'R', 'E'], 'no fork point with `origin/main`, or `origin/main` moved and collided with your files', exports.L2_BLOCK, '`pnpm wp-start-update`, or `pnpm wp-start-upsert-pr` when a PR is open'),
-    new L2Row(10, ['B', 'R', 'E'], 'healthy feature branch', exports.L2_ALLOW, '—'),
+    new L2Row(1, ['B', 'R', 'E'], 'on the **global allowlist** (inert command, or a universal cure such as reading/editing `webpieces.config.json`)', exports.L2_ALLOW, '—', [
+        new L2UseCase(1, 'You are blocked by some other L2 row, and need to turn the policy off to get anything done', 'any state — this row is ahead of every block', 'ALLOW: reading and editing `webpieces.config.json` is never blocked, so the mode-OFF cure is always reachable', 'Edit `webpieces.config.json` → `hookGuards` → `branch-state-guard` → `"mode": "OFF"`', 'webpieces-config-read (escape hatch)'),
+        new L2UseCase(2, 'A Write to `webpieces.config.json` while on `main`, which row 5 would otherwise block', 'on `main`, editing the one file that can disable the guard', 'ALLOW: the hook adapter bypasses feature-branch-guard for this path before any guard runs', 'None needed — the edit proceeds', 'config-bypass (feature-branch-guard skipped)'),
+    ]),
+    new L2Row(2, ['B'], 'bare `git checkout main`, with no `git pull` chained into the same command', exports.L2_BLOCK, '`git checkout main && git pull origin main`', [
+        new L2UseCase(3, '`git checkout main` after a merge, to start the next piece of work', 'about to land on whatever local `main` you last had — 157 commits behind, in the incident', 'BLOCK: decided from command TEXT alone, before the checkout, because the only `main` this could measure is the one it is about to leave', '`git checkout main && git pull origin main` — the pull must be in the SAME command', 'bare checkout of main ('),
+        new L2UseCase(4, 'The same command inside a linked worktree, where `git checkout main` fatals anyway', 'linked worktree — `main` is already checked out in the primary clone', 'BLOCK, and the message prints the worktree form rather than a cure git would refuse', '`git fetch origin main`, then work off `origin/main`', 'bare checkout of main ('),
+    ]),
+    new L2Row(3, ['B', 'R', 'E'], '**merge in progress** — L4 owns this state', exports.L2_EXEMPT, 'finish the merge: `pnpm wp-finish-upsert-pr`', [
+        new L2UseCase(5, 'Reading and editing conflicted files during a 3-point merge, on a branch row 9 would block', 'merge markers on disk — `pnpm wp-start-update` has run and not finished', 'EXEMPT: everything is permitted, which is exactly what lets row 9 be strict', 'Resolve the conflicts, then `pnpm wp-finish-upsert-pr`', exports.NO_ROW_EXIT),
+    ]),
+    new L2Row(4, ['B'], 'on the **skip list** — it gets you OUT, or tells you where you are', exports.L2_ALLOW, '—', [
+        new L2UseCase(6, '`git status` / `gh pr view` while blocked, to work out where you are', 'any state — orientation is never "working here"', 'ALLOW: metadata tells you where you are without putting stale file CONTENT in context', 'None needed', 'not-a-content-read (cure/build/metadata)'),
+        new L2UseCase(7, '`git stash` to clear a dirty tree so the prescribed `git pull` can fast-forward', 'on a stale `main` with local modifications', 'ALLOW: the cure for the row that blocked you must itself never be blocked', 'None needed — then run the pull and `git stash pop`', 'not-a-content-read (cure/build/metadata)'),
+        new L2UseCase(8, '`pnpm wp-start-upsert-pr` on a branch whose fork point is broken', 'row 9 state, running the tool row 9 prescribes', 'ALLOW: every `wp-*` bin is on the skip list, so no row can block its own remedy', 'None needed', 'merged-branch recovery/inspection (allowlisted)'),
+    ]),
+    new L2Row(5, ['B', 'E'], 'on `main`', exports.L2_BLOCK, '`git checkout -b <new> origin/main`', [
+        new L2UseCase(9, 'An Edit or Write to any tracked file while `git rev-parse --abbrev-ref HEAD` says `main`', 'on `main`, any freshness', 'BLOCK: decided by one `git rev-parse`, with NO cache read, so it fires on the first tool call of the session', '`git checkout -b <new> origin/main` — uncommitted work comes with you', 'on-main'),
+        new L2UseCase(10, 'A Bash command that WRITES tracked files as a side effect — `npx expo install`, a formatter, codegen, `sed -i`, a `>` redirect', 'on `main`, and the write is incidental to a command whose stated purpose is something else', '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', '`git checkout -b <new> origin/main` BEFORE running anything that may write', 'on-main'),
+        new L2UseCase(24, 'A build or a test run on a `main` that is perfectly up to date', 'on `main`, current — no staleness anywhere', 'BLOCK: freshness is not the question. `main` is not a place to work even when current, and the cure is a new branch, not a pull', '`git checkout -b <new> origin/main`', 'on-main'),
+        new L2UseCase(16, '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', 'the SIDE DOOR: same tree, different tool', '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', '`git checkout -b <new> origin/main`', 'on-main'),
+        new L2UseCase(25, 'The FIRST command of a session, on `main`, before any cache exists', 'on `main`, cache absent — row 11 would fail open', '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', '`git checkout -b <new> origin/main`', 'on-main'),
+    ]),
+    new L2Row(exports.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, the forge unreachable, or a dirty tree whose cure is not a clean fast-forward', exports.L2_FAIL_OPEN, '— (nothing to fix; the refresher populates the cache for the next call)', [
+        new L2UseCase(11, 'The very first tool call of a session is allowed even on a badly stale `main`', 'no cache — the refresher is fire-and-forget and populates it for the NEXT call', 'ALLOW (fail-open), logged as `ALLOW_FAIL_OPEN` so abstentions stay countable', 'None — the second call is judged normally', 'no-sync-cache'),
+        new L2UseCase(12, 'Guards quietly stand down on a plane, or when `gh` is unauthenticated or rate-limited', 'the forge could not be asked whether the PR is merged', 'ALLOW (fail-open) logged as `no-forge` — distinct from "asked, and it is not merged", which used to look identical in the trail', 'None — restore network/`gh auth` to re-arm the merged-branch policy', 'no-forge'),
+        new L2UseCase(13, 'A stale-`main` read is allowed because the tree is dirty', 'on `main`, behind `origin/main`, with local modifications', 'ALLOW (fail-open): the prescribed `git pull` is not a clean fast-forward on a dirty tree', '`git stash` → `git pull origin main` → `git stash pop`', 'dirty-tree-on-main'),
+        new L2UseCase(14, 'Mid-rebase, every guard abstains', 'detached HEAD — there is no branch name to judge', 'ALLOW (fail-open), logged LOUDLY when the branch is unresolvable rather than merely detached', 'None — finish or abort the rebase', 'branch-undeterminable'),
+    ]),
+    new L2Row(6, ['R'], 'on `main`, behind `origin/main`', exports.L2_BLOCK, '`git pull origin main`, or `git checkout -b <new> origin/main`', [
+        new L2UseCase(15, 'The Read tool refuses a file that exists, on a `main` 18 commits behind', 'on `main`, behind `origin/main`, clean tree', 'BLOCK: judged by live ancestry (`git merge-base --is-ancestor`), not hash equality, so a pull takes effect instantly', '`git pull origin main`, or `git checkout -b <new> origin/main`', 'on-stale-main'),
+    ]),
+    new L2Row(7, ['R'], 'on `main`, current', exports.L2_ALLOW, '—', [
+        new L2UseCase(17, 'Reading files on a `main` you just pulled', 'on `main`, and `origin/main` is an ancestor of HEAD', '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', 'None needed', 'local-main-contains-origin (up to date)'),
+    ]),
+    new L2Row(8, ['B', 'R', 'E'], 'on a branch whose PR is **already merged**', exports.L2_BLOCK, '`git fetch origin main && git checkout -b <new> origin/main`', [
+        new L2UseCase(18, 'You keep working on the branch after its PR merged, and the next PR reopens code review already landed', 'branch whose PR is merged — `merged` is monotonic, so the cached flag is trusted with no TTL', 'BLOCK across all three tools', '`git fetch origin main && git checkout -b <new> origin/main`', 'already-merged PR#'),
+        new L2UseCase(19, 'A shell-only session sails through on a merged branch', 'merged branch, Bash only — both FILE guards are file-scoped, so Bash reached neither', 'BLOCK: `merged-branch-bash-guard` exists because `branchAlreadyMerged` was being computed and logged on that very path, then thrown away', '`git fetch origin main && git checkout -b <new> origin/main`', 'already-merged PR#'),
+    ]),
+    new L2Row(9, ['B', 'R', 'E'], 'no fork point with `origin/main`, or `origin/main` moved and collided with your files', exports.L2_BLOCK, '`pnpm wp-start-update`, or `pnpm wp-start-upsert-pr` when a PR is open', [
+        new L2UseCase(20, 'Your branch and `origin/main` share no merge base — usually a branch cut from a squashed-away tip', 'no fork point', 'BLOCK: nothing built on this branch can be reasoned about relative to main', '`pnpm wp-start-update`, or `pnpm wp-start-upsert-pr` when a PR is open', 'no-fork-point'),
+        new L2UseCase(21, '`origin/main` moved and changed the same files you edited', 'main-moved collision', 'BLOCK — and row 3 then exempts everything once the merge starts, which is what makes this safe', '`pnpm wp-start-update`, resolve, `pnpm wp-finish-upsert-pr`', 'main-moved-conflict'),
+    ]),
+    new L2Row(10, ['B', 'R', 'E'], 'healthy feature branch', exports.L2_ALLOW, '—', [
+        new L2UseCase(22, 'Ordinary work on a branch cut from a current `origin/main`', 'healthy feature branch', 'ALLOW — the state every other row exists to push you back into', 'None needed', 'clean-feature-branch'),
+        new L2UseCase(23, '`stale-main-bash-guard` sees a feature branch and hands off', 'not on `main` — state B belongs to `merged-branch-bash-guard`', 'ALLOW: the same verdict about the same tree, logged by the guard that is not responsible for it', 'None needed', 'not-on-main (state B is another guard)'),
+    ]),
 ];
+/**
+ * Every use case on every row, in row order, for the doc and for the exhaustiveness specs.
+ *
+ * Numbering is GLOBAL and is identity, exactly as the row numbers are: a use case is cited by number in
+ * review and in the doc, so add new ones at the END of the highest number rather than renumbering to
+ * keep a row's block contiguous.
+ */
+// webpieces-disable no-function-outside-class -- pure accessor over L2_ROWS above, in this data module
+function allL2UseCases() {
+    return exports.L2_ROWS.flatMap((row) => row.useCases);
+}
 /**
  * REASON → ROW. The join between what a guard actually logged and the row it is an instance of.
  *
@@ -175,7 +278,9 @@ const EXACT_REASON_ROWS = {
 const PREFIX_REASON_ROWS = {
     'already-merged PR#': 8,
     'bare checkout of main (': 2,
-    'stale-main content read (': 6,
+    // `stale-main content read (` used to live here, mapping the Bash side of row 6. It is gone with
+    // the guard exit that emitted it: on `main`, row 5 now blocks before any content-read scan runs,
+    // so row 6 is what the table always said it was — the ROW-ONLY row.
 };
 /**
  * The row a logged reason belongs to, or null when nothing claims it.
@@ -222,7 +327,6 @@ exports.L2NotDone = L2NotDone;
  * of these, so the trail never claims the strict row fired.
  */
 exports.NOT_DONE = [
-    new L2NotDone(5, 'Row 5 blocks `B` as well as `E` on `main`. Only `E` is blocked today: `feature-branch-guard` blocks the write, while `stale-main-bash-guard` blocks only CONTENT-READING Bash, and only once the cache proves `main` is behind.', 'Bash on a CURRENT `main` is harmless, and the strict form needs the skip list (row 4) to be complete first — a `B`-on-main block with an incomplete skip list wedges the session on its own cure.'),
     new L2NotDone(8, 'Row 8 blocks reads on a merged branch even when the tree is DIRTY. The code opens a dirty valve and fails open (`dirty-merged-branch`, logged at row 11).', 'The row is the ORIGINAL documented design — `git checkout -b <new> origin/main` carries uncommitted changes onto the fresh branch, so nothing is trapped — and `read-stale-guard`\'s own class comment still states it. The code drifted, and closing the valve is a behaviour change that belongs in its own PR with its own evidence, not in a config collapse.'),
     new L2NotDone(6, 'Row 6 blocks reads on a stale `main` even when the tree is DIRTY. The code opens a dirty valve (`dirty-tree-on-main`, logged at row 11).', 'This is the one place the dirty argument has teeth: the cure is `git pull`, which genuinely is not a clean fast-forward on a dirty tree. `git stash` is on the skip list and clears it, so the strict form is reachable — but it is the same behaviour change, and the same separate PR.'),
 ];

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 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\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\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 L2Row(2, ['B'], 'bare `git checkout main`, with no `git pull` chained into the same command', L2_BLOCK, '`git checkout main && git pull origin main`'),\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 L2Row(4, ['B'], 'on the **skip list** — it gets you OUT, or tells you where you are', L2_ALLOW, '—'),\n    new L2Row(5, ['B', 'E'], 'on `main`', L2_BLOCK, '`git checkout -b <new> origin/main`'),\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, the forge unreachable, or a dirty tree whose cure is not a clean fast-forward', L2_FAIL_OPEN, '— (nothing to fix; the refresher populates the cache for the next call)'),\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 L2Row(7, ['R'], 'on `main`, current', L2_ALLOW, '—'),\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 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 L2Row(10, ['B', 'R', 'E'], 'healthy feature branch', L2_ALLOW, '—'),\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': L2_FAIL_OPEN_ROW,\n    'dirty-merged-branch': L2_FAIL_OPEN_ROW,\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 (': 6,\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    new L2NotDone(5,\n        'Row 5 blocks `B` as well as `E` on `main`. Only `E` is blocked today: `feature-branch-guard` blocks the write, while `stale-main-bash-guard` blocks only CONTENT-READING Bash, and only once the cache proves `main` is behind.',\n        'Bash on a CURRENT `main` is harmless, and the strict form needs the skip list (row 4) to be complete first — a `B`-on-main block with an incomplete skip list wedges the session on its own cure.'),\n    new L2NotDone(8,\n        'Row 8 blocks reads on a merged branch even when the tree is DIRTY. The code opens a dirty valve and fails open (`dirty-merged-branch`, logged at row 11).',\n        'The row is the ORIGINAL documented design — `git checkout -b <new> origin/main` carries uncommitted changes onto the fresh branch, so nothing is trapped — and `read-stale-guard`\\'s own class comment still states it. The code drifted, and closing the valve is a behaviour change that belongs in its own PR with its own evidence, not in a config collapse.'),\n    new L2NotDone(6,\n        'Row 6 blocks reads on a stale `main` even when the tree is DIRTY. The code opens a dirty valve (`dirty-tree-on-main`, logged at row 11).',\n        'This is the one place the dirty argument has teeth: the cure is `git pull`, which genuinely is not a clean fast-forward on a dirty tree. `git stash` is on the skip list and clears it, so the strict form is reachable — but it is the same behaviour change, and the same separate PR.'),\n];\n"]}
+{"version":3,"file":"l2-rows.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/l2-rows.ts"],"names":[],"mappings":";AAAA,8EAA8E;AAC9E,wCAAwC;AACxC,EAAE;AACF,qGAAqG;AACrG,8EAA8E;AAC9E,EAAE;AACF,uGAAuG;AACvG,uGAAuG;AACvG,sGAAsG;AACtG,0FAA0F;AAC1F,EAAE;AACF,iFAAiF;AACjF,EAAE;AACF,sGAAsG;AACtG,uGAAuG;AACvG,oGAAoG;AACpG,sGAAsG;AACtG,oGAAoG;AACpG,mGAAmG;AACnG,mDAAmD;AACnD,EAAE;AACF,mGAAmG;AACnG,kGAAkG;AAClG,gGAAgG;AAChG,iGAAiG;AACjG,wGAAwG;AACxG,yEAAyE;AACzE,EAAE;AACF,sGAAsG;AACtG,kGAAkG;AAClG,EAAE;AACF,wGAAwG;AACxG,qCAAqC;AACrC,8EAA8E;;;AAmT9E,sCAEC;AAgED,wCAOC;AAID,0CAEC;AA1XD;;;;;;;;;;;;;;GAcG;AACU,QAAA,gBAAgB,GAAG,EAAE,CAAC;AAEnC,yFAAyF;AACzF,MAAa,QAAQ;IACI;IAAwB;IAA7C,YAAqB,KAAa,EAAW,IAAkB;QAA1C,UAAK,GAAL,KAAK,CAAQ;QAAW,SAAI,GAAJ,IAAI,CAAc;IAAG,CAAC;CACtE;AAFD,4BAEC;AAEY,QAAA,QAAQ,GAAG,IAAI,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AAC5C,QAAA,SAAS,GAAG,IAAI,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;AAC/C,QAAA,QAAQ,GAAG,IAAI,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AAC5C,QAAA,YAAY,GAAG,IAAI,QAAQ,CAAC,qBAAqB,EAAE,WAAW,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAa,SAAS;IAGL;IACA;IACA;IACA;IACA;IACA;IAPb,gHAAgH;IAChH,YACa,GAAW,EACX,OAAe,EACf,KAAa,EACb,OAAe,EACf,GAAW,EACX,MAAc;QALd,QAAG,GAAH,GAAG,CAAQ;QACX,YAAO,GAAP,OAAO,CAAQ;QACf,UAAK,GAAL,KAAK,CAAQ;QACb,YAAO,GAAP,OAAO,CAAQ;QACf,QAAG,GAAH,GAAG,CAAQ;QACX,WAAM,GAAN,MAAM,CAAQ;IACxB,CAAC;CACP;AAVD,8BAUC;AAED;;;;;;GAMG;AACU,QAAA,WAAW,GAAG,kEAAkE,CAAC;AAE9F;;;;;;;GAOG;AACH,MAAa,KAAK;IAGD;IACA;IAEA;IACA;IAEA;IASA;IAjBb,6GAA6G;IAC7G,YACa,GAAW,EACX,KAAwB;IACjC,kCAAkC;IACzB,KAAa,EACb,MAAgB;IACzB,0DAA0D;IACjD,IAAY;IACrB;;;;;;;OAOG;IACM,QAA8C;QAf9C,QAAG,GAAH,GAAG,CAAQ;QACX,UAAK,GAAL,KAAK,CAAmB;QAExB,UAAK,GAAL,KAAK,CAAQ;QACb,WAAM,GAAN,MAAM,CAAU;QAEhB,SAAI,GAAJ,IAAI,CAAQ;QASZ,aAAQ,GAAR,QAAQ,CAAsC;IACxD,CAAC;IAEJ,wDAAwD;IACxD,QAAQ;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;CACJ;AAzBD,sBAyBC;AAED;;;;;;;;;;;;;;GAcG;AACU,QAAA,OAAO,GAAqB;IACrC,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,kHAAkH,EAAE,gBAAQ,EAAE,GAAG,EAAE;QAC7J,IAAI,SAAS,CAAC,CAAC,EACX,4FAA4F,EAC5F,8CAA8C,EAC9C,+GAA+G,EAC/G,sFAAsF,EACtF,sCAAsC,CAAC;QAC3C,IAAI,SAAS,CAAC,CAAC,EACX,uFAAuF,EACvF,4DAA4D,EAC5D,2FAA2F,EAC3F,iCAAiC,EACjC,8CAA8C,CAAC;KACtD,CAAC;IACF,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,4EAA4E,EAAE,gBAAQ,EAAE,6CAA6C,EAAE;QACvJ,IAAI,SAAS,CAAC,CAAC,EACX,oEAAoE,EACpE,2FAA2F,EAC3F,yIAAyI,EACzI,oFAAoF,EACpF,yBAAyB,CAAC;QAC9B,IAAI,SAAS,CAAC,CAAC,EACX,oFAAoF,EACpF,sEAAsE,EACtE,qFAAqF,EACrF,sDAAsD,EACtD,yBAAyB,CAAC;KACjC,CAAC;IACF,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,4CAA4C,EAAE,iBAAS,EAAE,8CAA8C,EAAE;QACnI,IAAI,SAAS,CAAC,CAAC,EACX,4FAA4F,EAC5F,yEAAyE,EACzE,6EAA6E,EAC7E,wDAAwD,EACxD,mBAAW,CAAC;KACnB,CAAC;IACF,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,oEAAoE,EAAE,gBAAQ,EAAE,GAAG,EAAE;QACrG,IAAI,SAAS,CAAC,CAAC,EACX,sEAAsE,EACtE,iDAAiD,EACjD,uFAAuF,EACvF,aAAa,EACb,0CAA0C,CAAC;QAC/C,IAAI,SAAS,CAAC,CAAC,EACX,iFAAiF,EACjF,4CAA4C,EAC5C,2EAA2E,EAC3E,qDAAqD,EACrD,0CAA0C,CAAC;QAC/C,IAAI,SAAS,CAAC,CAAC,EACX,kEAAkE,EAClE,gDAAgD,EAChD,iFAAiF,EACjF,aAAa,EACb,iDAAiD,CAAC;KACzD,CAAC;IACF,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,WAAW,EAAE,gBAAQ,EAAE,qCAAqC,EAAE;QACnF,IAAI,SAAS,CAAC,CAAC,EACX,0FAA0F,EAC1F,0BAA0B,EAC1B,8GAA8G,EAC9G,uEAAuE,EACvE,SAAS,CAAC;QACd,IAAI,SAAS,CAAC,EAAE,EACZ,gIAAgI,EAChI,4FAA4F,EAC5F,8LAA8L,EAC9L,4EAA4E,EAC5E,SAAS,CAAC;QACd,IAAI,SAAS,CAAC,EAAE,EACZ,gEAAgE,EAChE,4CAA4C,EAC5C,iIAAiI,EACjI,qCAAqC,EACrC,SAAS,CAAC;QACd,IAAI,SAAS,CAAC,EAAE,EACZ,6JAA6J,EAC7J,0CAA0C,EAC1C,2SAA2S,EAC3S,qCAAqC,EACrC,SAAS,CAAC;QACd,IAAI,SAAS,CAAC,EAAE,EACZ,oEAAoE,EACpE,kDAAkD,EAClD,sKAAsK,EACtK,qCAAqC,EACrC,SAAS,CAAC;KACjB,CAAC;IACF,IAAI,KAAK,CAAC,wBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,oNAAoN,EAAE,oBAAY,EAAE,yEAAyE,EAAE;QACxV,IAAI,SAAS,CAAC,EAAE,EACZ,+EAA+E,EAC/E,gFAAgF,EAChF,8EAA8E,EAC9E,2CAA2C,EAC3C,eAAe,CAAC;QACpB,IAAI,SAAS,CAAC,EAAE,EACZ,uFAAuF,EACvF,uDAAuD,EACvD,iIAAiI,EACjI,qEAAqE,EACrE,UAAU,CAAC;QACf,IAAI,SAAS,CAAC,EAAE,EACZ,0DAA0D,EAC1D,2DAA2D,EAC3D,0FAA0F,EAC1F,wDAAwD,EACxD,oBAAoB,CAAC;QACzB,IAAI,SAAS,CAAC,EAAE,EACZ,kCAAkC,EAClC,kDAAkD,EAClD,8FAA8F,EAC9F,mCAAmC,EACnC,uBAAuB,CAAC;KAC/B,CAAC;IACF,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,iCAAiC,EAAE,gBAAQ,EAAE,gEAAgE,EAAE;QAC/H,IAAI,SAAS,CAAC,EAAE,EACZ,yEAAyE,EACzE,6CAA6C,EAC7C,sHAAsH,EACtH,gEAAgE,EAChE,eAAe,CAAC;KACvB,CAAC;IACF,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,oBAAoB,EAAE,gBAAQ,EAAE,GAAG,EAAE;QACrD,IAAI,SAAS,CAAC,EAAE,EACZ,2CAA2C,EAC3C,qDAAqD,EACrD,qJAAqJ,EACrJ,aAAa,EACb,yCAAyC,CAAC;KACjD,CAAC;IACF,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,4CAA4C,EAAE,gBAAQ,EAAE,8DAA8D,EAAE;QAClJ,IAAI,SAAS,CAAC,EAAE,EACZ,wGAAwG,EACxG,8FAA8F,EAC9F,8BAA8B,EAC9B,8DAA8D,EAC9D,oBAAoB,CAAC;QACzB,IAAI,SAAS,CAAC,EAAE,EACZ,uDAAuD,EACvD,sFAAsF,EACtF,0IAA0I,EAC1I,8DAA8D,EAC9D,oBAAoB,CAAC;KAC5B,CAAC;IACF,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,uFAAuF,EAAE,gBAAQ,EAAE,wEAAwE,EAAE;QACvM,IAAI,SAAS,CAAC,EAAE,EACZ,mGAAmG,EACnG,eAAe,EACf,4EAA4E,EAC5E,wEAAwE,EACxE,eAAe,CAAC;QACpB,IAAI,SAAS,CAAC,EAAE,EACZ,2DAA2D,EAC3D,sBAAsB,EACtB,gGAAgG,EAChG,6DAA6D,EAC7D,qBAAqB,CAAC;KAC7B,CAAC;IACF,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,wBAAwB,EAAE,gBAAQ,EAAE,GAAG,EAAE;QACpE,IAAI,SAAS,CAAC,EAAE,EACZ,4DAA4D,EAC5D,wBAAwB,EACxB,gEAAgE,EAChE,aAAa,EACb,sBAAsB,CAAC;QAC3B,IAAI,SAAS,CAAC,EAAE,EACZ,6DAA6D,EAC7D,+DAA+D,EAC/D,iGAAiG,EACjG,aAAa,EACb,wCAAwC,CAAC;KAChD,CAAC;CACL,CAAC;AAEF;;;;;;GAMG;AACH,uGAAuG;AACvG,SAAgB,aAAa;IACzB,OAAO,eAAO,CAAC,OAAO,CAAC,CAAC,GAAU,EAAwB,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,iBAAiB,GAA2B;IAC9C,6EAA6E;IAC7E,sCAAsC,EAAE,CAAC;IACzC,mFAAmF;IACnF,mCAAmC;IACnC,oDAAoD;IACpD,iDAAiD,EAAE,CAAC;IACpD,0CAA0C,EAAE,CAAC;IAC7C,8BAA8B;IAC9B,SAAS,EAAE,CAAC;IACZ,4EAA4E;IAC5E,eAAe,EAAE,CAAC;IAClB,yCAAyC,EAAE,CAAC;IAC5C,yCAAyC;IACzC,eAAe,EAAE,CAAC;IAClB,qBAAqB,EAAE,CAAC;IACxB,+FAA+F;IAC/F,+BAA+B;IAC/B,sBAAsB,EAAE,EAAE;IAC1B,wCAAwC,EAAE,EAAE;IAC5C,iGAAiG;IACjG,4CAA4C;IAC5C,uBAAuB,EAAE,wBAAgB;IACzC,eAAe,EAAE,wBAAgB;IACjC,0BAA0B,EAAE,wBAAgB;IAC5C,qBAAqB,EAAE,wBAAgB;IACvC,oBAAoB,EAAE,wBAAgB;IACtC,qBAAqB,EAAE,wBAAgB;IACvC,UAAU,EAAE,wBAAgB;IAC5B,kGAAkG;IAClG,iCAAiC;IACjC,8CAA8C,EAAE,CAAC;CACpD,CAAC;AAEF,qFAAqF;AACrF,MAAM,kBAAkB,GAA2B;IAC/C,oBAAoB,EAAE,CAAC;IACvB,yBAAyB,EAAE,CAAC;IAC5B,iGAAiG;IACjG,iGAAiG;IACjG,oEAAoE;CACvE,CAAC;AAEF;;;;;;GAMG;AACH,wHAAwH;AACxH,SAAgB,cAAc,CAAC,MAAc;IACzC,MAAM,KAAK,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACnD,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,0EAA0E;AAC1E,yFAAyF;AACzF,SAAgB,eAAe;IAC3B,OAAO,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC;AACnF,CAAC;AAED,yFAAyF;AACzF,MAAa,SAAS;IACG;IAAsB;IAAsB;IAAjE,YAAqB,GAAW,EAAW,GAAW,EAAW,GAAW;QAAvD,QAAG,GAAH,GAAG,CAAQ;QAAW,QAAG,GAAH,GAAG,CAAQ;QAAW,QAAG,GAAH,GAAG,CAAQ;IAAG,CAAC;CACnF;AAFD,8BAEC;AAED;;;;;;;;GAQG;AACU,QAAA,QAAQ,GAAyB;IAC1C,IAAI,SAAS,CAAC,CAAC,EACX,2JAA2J,EAC3J,mWAAmW,CAAC;IACxW,IAAI,SAAS,CAAC,CAAC,EACX,0IAA0I,EAC1I,0RAA0R,CAAC;CAClS,CAAC","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, '`git checkout main && git pull origin 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            '`git checkout main && git pull origin main` — the pull must be in the SAME command',\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` to clear a dirty tree so the prescribed `git pull` can fast-forward',\n            'on a stale `main` with local modifications',\n            'ALLOW: the cure for the row that blocked you must itself never be blocked',\n            'None needed — then run the pull 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. `main` is not a place to work even when current, and the cure is a new branch, not a pull',\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, the forge unreachable, or a dirty tree whose cure is not a clean fast-forward', 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(13,\n            'A stale-`main` read is allowed because the tree is dirty',\n            'on `main`, behind `origin/main`, with local modifications',\n            'ALLOW (fail-open): the prescribed `git pull` is not a clean fast-forward on a dirty tree',\n            '`git stash` → `git pull origin main` → `git stash pop`',\n            'dirty-tree-on-main'),\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(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(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': L2_FAIL_OPEN_ROW,\n    'dirty-merged-branch': L2_FAIL_OPEN_ROW,\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    new L2NotDone(8,\n        'Row 8 blocks reads on a merged branch even when the tree is DIRTY. The code opens a dirty valve and fails open (`dirty-merged-branch`, logged at row 11).',\n        'The row is the ORIGINAL documented design — `git checkout -b <new> origin/main` carries uncommitted changes onto the fresh branch, so nothing is trapped — and `read-stale-guard`\\'s own class comment still states it. The code drifted, and closing the valve is a behaviour change that belongs in its own PR with its own evidence, not in a config collapse.'),\n    new L2NotDone(6,\n        'Row 6 blocks reads on a stale `main` even when the tree is DIRTY. The code opens a dirty valve (`dirty-tree-on-main`, logged at row 11).',\n        'This is the one place the dirty argument has teeth: the cure is `git pull`, which genuinely is not a clean fast-forward on a dirty tree. `git stash` is on the skip list and clears it, so the strict form is reachable — but it is the same behaviour change, and the same separate PR.'),\n];\n"]}

package/src/core/matrix-cures.d.ts

@@ -0,0 +1,12 @@
+/** What a row with no cure — every ALLOW row, and every layer this module does not own — logs. */
+export declare const NO_CURE = "-";
+/**
+ * The literal cure for a layer+row, for the log line. `-` when the row allows, or when the layer is
+ * not one this module owns.
+ *
+ * Markdown backticks are stripped: the doc is read by a human in a renderer, the log is read through
+ * `grep`, and a cure you cannot grep for without escaping the fence characters is a cure the trail
+ * cannot be searched by. The words are otherwise untouched, so the log and the doc stay comparable
+ * literal-for-literal, which is the point of deriving one from the other.
+ */
+export declare function cureForMatrix(layer: string, row: string): string;

package/src/core/matrix-cures.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_CURE = void 0;
+exports.cureForMatrix = cureForMatrix;
+const l1_rows_1 = require("./l1-rows");
+const l2_rows_1 = require("./l2-rows");
+// ---------------------------------------------------------------------------
+// THE CURE, as a log field — the other half of `row=`.
+//
+// `row=` already joined a decision-log line to a row in the generated matrix. What it could not tell
+// you is what the agent was actually TOLD to do, and that is the half you need to audit the table:
+// a row whose cure keeps appearing in the trail next to a session that then did something else is a
+// row whose use cases need updating. Reading the doc tells you what the cure IS; reading the log used
+// to tell you only that some row fired.
+//
+// THE ONE DESIGN DECISION HERE: the cure is LOOKED UP from the row, never passed in by the caller.
+//
+// A `cure` field on GuardDecision would have been the obvious move and is the wrong one. It would let
+// the logged cure and the printed cure drift — two spellings of one thing, which is the shim shape
+// this repo rejects — and it would have to be threaded through every construction site, so the cheap
+// path would be to pass '' and the field would rot. Deriving it from `decision.matrix` means the
+// logged cure is BY CONSTRUCTION the same literal the generated doc prints for that row, and no call
+// site changes at all.
+//
+// Both layers are covered because both stamp a MatrixRef: L1 dispatches from L1_ROWS, L2 joins by
+// reason. L0's cures are a different shape (L0Cure carries mention + discriminator + guidance, and
+// the sh shim prints them itself), so L0 rows resolve to '-' here rather than being half-rendered.
+// ---------------------------------------------------------------------------
+/** What a row with no cure — every ALLOW row, and every layer this module does not own — logs. */
+exports.NO_CURE = '-';
+/**
+ * The literal cure for a layer+row, for the log line. `-` when the row allows, or when the layer is
+ * not one this module owns.
+ *
+ * Markdown backticks are stripped: the doc is read by a human in a renderer, the log is read through
+ * `grep`, and a cure you cannot grep for without escaping the fence characters is a cure the trail
+ * cannot be searched by. The words are otherwise untouched, so the log and the doc stay comparable
+ * literal-for-literal, which is the point of deriving one from the other.
+ */
+// webpieces-disable no-function-outside-class -- the pure lookup this module exists to be, over the two row arrays it imports
+function cureForMatrix(layer, row) {
+    if (layer === 'L2')
+        return cureOf(l2_rows_1.L2_ROWS.find((r) => String(r.num) === row)?.cure);
+    if (layer === 'L1')
+        return cureOf(l1_rows_1.L1_ROWS.find((r) => String(r.num) === row)?.cure?.denyMention);
+    return exports.NO_CURE;
+}
+// An allow row's cure cell is the em-dash the doc prints; in a log field that is noise, so it becomes
+// the same `-` an unknown row gets. The distinction a reader needs is carried by `verdict`, not here.
+// webpieces-disable no-function-outside-class -- private normalizer for cureForMatrix above, beside it in this module
+function cureOf(cure) {
+    if (cure === undefined || cure === '' || cure === '—')
+        return exports.NO_CURE;
+    return cure.replace(/`/g, '');
+}
+//# sourceMappingURL=matrix-cures.js.map

package/src/core/matrix-cures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix-cures.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/matrix-cures.ts"],"names":[],"mappings":";;;AAuCA,sCAIC;AA3CD,uCAA2C;AAC3C,uCAA2C;AAE3C,8EAA8E;AAC9E,uDAAuD;AACvD,EAAE;AACF,qGAAqG;AACrG,mGAAmG;AACnG,oGAAoG;AACpG,sGAAsG;AACtG,wCAAwC;AACxC,EAAE;AACF,mGAAmG;AACnG,EAAE;AACF,sGAAsG;AACtG,mGAAmG;AACnG,qGAAqG;AACrG,iGAAiG;AACjG,qGAAqG;AACrG,uBAAuB;AACvB,EAAE;AACF,kGAAkG;AAClG,mGAAmG;AACnG,mGAAmG;AACnG,8EAA8E;AAE9E,kGAAkG;AACrF,QAAA,OAAO,GAAG,GAAG,CAAC;AAE3B;;;;;;;;GAQG;AACH,8HAA8H;AAC9H,SAAgB,aAAa,CAAC,KAAa,EAAE,GAAW;IACpD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,iBAAO,CAAC,IAAI,CAAC,CAAC,CAAQ,EAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;IACpG,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,iBAAO,CAAC,IAAI,CAAC,CAAC,CAAQ,EAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IACjH,OAAO,eAAO,CAAC;AACnB,CAAC;AAED,sGAAsG;AACtG,sGAAsG;AACtG,sHAAsH;AACtH,SAAS,MAAM,CAAC,IAAwB;IACpC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,eAAO,CAAC;IACtE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAClC,CAAC","sourcesContent":["import { L1_ROWS, L1Row } from './l1-rows';\nimport { L2_ROWS, L2Row } from './l2-rows';\n\n// ---------------------------------------------------------------------------\n// THE CURE, as a log field — the other half of `row=`.\n//\n// `row=` already joined a decision-log line to a row in the generated matrix. What it could not tell\n// you is what the agent was actually TOLD to do, and that is the half you need to audit the table:\n// a row whose cure keeps appearing in the trail next to a session that then did something else is a\n// row whose use cases need updating. Reading the doc tells you what the cure IS; reading the log used\n// to tell you only that some row fired.\n//\n// THE ONE DESIGN DECISION HERE: the cure is LOOKED UP from the row, never passed in by the caller.\n//\n// A `cure` field on GuardDecision would have been the obvious move and is the wrong one. It would let\n// the logged cure and the printed cure drift — two spellings of one thing, which is the shim shape\n// this repo rejects — and it would have to be threaded through every construction site, so the cheap\n// path would be to pass '' and the field would rot. Deriving it from `decision.matrix` means the\n// logged cure is BY CONSTRUCTION the same literal the generated doc prints for that row, and no call\n// site changes at all.\n//\n// Both layers are covered because both stamp a MatrixRef: L1 dispatches from L1_ROWS, L2 joins by\n// reason. L0's cures are a different shape (L0Cure carries mention + discriminator + guidance, and\n// the sh shim prints them itself), so L0 rows resolve to '-' here rather than being half-rendered.\n// ---------------------------------------------------------------------------\n\n/** What a row with no cure — every ALLOW row, and every layer this module does not own — logs. */\nexport const NO_CURE = '-';\n\n/**\n * The literal cure for a layer+row, for the log line. `-` when the row allows, or when the layer is\n * not one this module owns.\n *\n * Markdown backticks are stripped: the doc is read by a human in a renderer, the log is read through\n * `grep`, and a cure you cannot grep for without escaping the fence characters is a cure the trail\n * cannot be searched by. The words are otherwise untouched, so the log and the doc stay comparable\n * literal-for-literal, which is the point of deriving one from the other.\n */\n// webpieces-disable no-function-outside-class -- the pure lookup this module exists to be, over the two row arrays it imports\nexport function cureForMatrix(layer: string, row: string): string {\n    if (layer === 'L2') return cureOf(L2_ROWS.find((r: L2Row): boolean => String(r.num) === row)?.cure);\n    if (layer === 'L1') return cureOf(L1_ROWS.find((r: L1Row): boolean => String(r.num) === row)?.cure?.denyMention);\n    return NO_CURE;\n}\n\n// An allow row's cure cell is the em-dash the doc prints; in a log field that is noise, so it becomes\n// the same `-` an unknown row gets. The distinction a reader needs is carried by `verdict`, not here.\n// webpieces-disable no-function-outside-class -- private normalizer for cureForMatrix above, beside it in this module\nfunction cureOf(cure: string | undefined): string {\n    if (cure === undefined || cure === '' || cure === '—') return NO_CURE;\n    return cure.replace(/`/g, '');\n}\n"]}

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

@@ -10,6 +10,7 @@ const to_error_1 = require("../to-error");
 const main_sync_refresh_1 = require("../main-sync-refresh");
 const main_sync_timeout_1 = require("../main-sync-timeout");
 const decision_log_1 = require("../decision-log");
+const l2_matrix_doc_1 = require("../l2-matrix-doc");
 const l0_fault_codes_1 = require("../l0-fault-codes");
 const merged_branch_message_1 = require("./merged-branch-message");
 const tree_recovery_1 = require("./tree-recovery");
@@ -122,7 +123,9 @@ class FeatureBranchGuardRule extends rule_base_1.FileRuleBase {
     }
     block(ctx, branch, reason, message, cache = '-') {
         this.logDecision(ctx, branch, 'BLOCK_AI_CURE', reason, cache);
-        return [new types_1.Violation(1, ctx.relativePath, message)];
+        // Deliver the matrix and name the row — see stale-main-bash-guard.block for why it is lazy.
+        const pointer = (0, l2_matrix_doc_1.branchStateMatrixPointer)((0, l2_matrix_doc_1.writeBranchStateMatrixDoc)(ctx.workspaceRoot), (0, decision_log_1.matrixL2Row)(reason).row);
+        return [new types_1.Violation(1, ctx.relativePath, message + pointer)];
     }
     logDecision(ctx, branch, verdict, reason, cache) {
         (0, decision_log_1.logGuardDecision)(ctx.workspaceRoot, new decision_log_1.GuardDecision('feature-branch-guard', ctx.tool, ctx.relativePath, branch ?? 'unknown', verdict, reason, cache, l0_fault_codes_1.L0_FAULT_NONE, (0, decision_log_1.matrixL2Row)(reason)));

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

@@ -1 +1 @@
-{"version":3,"file":"feature-branch-guard.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/feature-branch-guard.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync } from 'child_process';\n\nimport {\n    BranchStateGuardConfig,\n    BRANCH_STATE_GUARD_KEY,\n    DEFAULT_HANG_TIMEOUT_MINUTES,\n    readMainSyncStatus,\n    squashRecoverySteps,\n    MainSyncStatus,\n    SyncFlowGuidance,\n} from '@webpieces/rules-config';\n\nimport type { FileContext, Violation } from '../types';\nimport { Violation as V } from '../types';\nimport { FileRuleBase } from '../rule-base';\nimport { FixHint, Option } from '../fix-hint';\nimport { toError } from '../to-error';\nimport { triggerMainSyncRefresh } from '../main-sync-refresh';\nimport { hangTimeoutOf } from '../main-sync-timeout';\nimport { logGuardDecision, GuardDecision, Verdict, matrixL2Row } from '../decision-log';\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        return [new V(1, ctx.relativePath, message)];\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    private onMainMessage(): string {\n        const convention = this.config.branchNamingConvention ?? '{whoami}/{featurename}';\n        return [\n            'You should not be working on main.',\n            'Do a `git pull origin main` to get latest, then create a feature branch based on the naming convention.',\n            `Branch naming convention (from webpieces.config.json): ${convention}`,\n            'Example: git checkout -b ' + convention.replace(/<[^>]+>/g, 'value'),\n        ].join('\\n');\n    }\n\n    // Shared with read-stale-guard, which blocks READS in this same state — see MergedBranchMessage.\n    // The tree kind picks the flavour of the cure: a dead LINKED WORKTREE is told to open a new\n    // worktree off origin/main and reap this one; the primary clone is told to branch off origin/main.\n    private alreadyMergedMessage(workspaceRoot: string, branch: string, mergedPr: string): string {\n        return new MergedBranchMessage(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 {\n    BranchStateGuardConfig,\n    BRANCH_STATE_GUARD_KEY,\n    DEFAULT_HANG_TIMEOUT_MINUTES,\n    readMainSyncStatus,\n    squashRecoverySteps,\n    MainSyncStatus,\n    SyncFlowGuidance,\n} from '@webpieces/rules-config';\n\nimport type { FileContext, Violation } from '../types';\nimport { Violation as V } from '../types';\nimport { FileRuleBase } from '../rule-base';\nimport { FixHint, Option } from '../fix-hint';\nimport { toError } from '../to-error';\nimport { triggerMainSyncRefresh } from '../main-sync-refresh';\nimport { 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    private onMainMessage(): string {\n        const convention = this.config.branchNamingConvention ?? '{whoami}/{featurename}';\n        return [\n            'You should not be working on main.',\n            'Do a `git pull origin main` to get latest, then create a feature branch based on the naming convention.',\n            `Branch naming convention (from webpieces.config.json): ${convention}`,\n            'Example: git checkout -b ' + convention.replace(/<[^>]+>/g, 'value'),\n        ].join('\\n');\n    }\n\n    // Shared with read-stale-guard, which blocks READS in this same state — see MergedBranchMessage.\n    // The tree kind picks the flavour of the cure: a dead LINKED WORKTREE is told to open a new\n    // worktree off origin/main and reap this one; the primary clone is told to branch off origin/main.\n    private alreadyMergedMessage(workspaceRoot: string, branch: string, mergedPr: string): string {\n        return new MergedBranchMessage(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/merged-branch-bash-guard.d.ts

@@ -34,26 +34,13 @@ import { FixHint } from '../fix-hint';
 export declare class MergedBranchBashGuardRule extends BashRuleBase<BranchStateGuardConfig> {
     constructor(config: BranchStateGuardConfig);
     private readonly scanner;
-    private readonly shell;
+    private readonly recoveryList;
     readonly description: string;
     readonly defaultOptions: {
         hangTimeoutMinutes: number;
     };
     readonly fixHint: FixHint;
     check(ctx: BashContext): readonly Violation[];
-    /**
-     * A command is a recovery command only when EVERY one of its segments is — a single
-     * `… && scripts/local.sh start` in the chain is enough to deny the whole thing.
-     *
-     * Segments are judged by ROLE first (see ShellSegmentScan). Shell STRUCTURE (`for … in`, `do`,
-     * `done`) invokes nothing, and output SHAPING (`| tail -40`, `; echo done`) cannot touch the repo
-     * — so neither may veto a chain. Judging the raw string instead is what made the guard reject
-     * `git fetch origin main 2>&1 | tail -5`, a command its own redirect had just told the agent to run.
-     */
-    private isFullyRecovery;
-    private isRecoverySegment;
-    private isGhInspection;
-    private isPackageRecovery;
     private mergedMessage;
     private cacheSummary;
     /**