npm - @webpieces/ai-hook-rules - Versions diffs - 0.4.678 → 0.4.679 - Mend

@webpieces/ai-hook-rules 0.4.678 → 0.4.679

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/package.json +2 -2
package/src/core/l1-doc.js +34 -4
package/src/core/l1-doc.js.map +1 -1
package/src/core/l1-matrix-doc.d.ts +2 -0
package/src/core/l1-matrix-doc.js +20 -0
package/src/core/l1-matrix-doc.js.map +1 -0

package/package.json CHANGED Viewed

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

package/src/core/l1-doc.js CHANGED Viewed

@@ -25,7 +25,11 @@ function tableRow(row) {
     // Row 6 has no `why` — an EMPTY cell is `| |`, not `|  |`. Two spaces would render the same in a
     // browser and fail the byte-lock, which is the whole point of locking bytes rather than markdown.
     const why = row.why === '' ? ' ' : ` ${row.why} `;
-    return `| ${row.num} | ${dims} | ${row.action.label} |${why}|`;
+    // The CURE column exists so a reader who arrived here from a `row=` in a log gets the remedy on the
+    // same line as the verdict, the way L2's matrix does. Only blocking rows have one; a row that hands
+    // down to L2 or exempts has nothing to cure, and says so rather than leaving the cell blank.
+    const cure = row.cure === null ? 'n/a — not a block' : row.cure.summary;
+    return `| ${row.num} | ${dims} | ${row.action.label} |${why}| ${cure} |`;
 }
 // webpieces-disable no-function-outside-class -- pure row formatter for renderL1Doc below, in this render module
 function useCaseRow(useCase) {
@@ -42,10 +46,36 @@ function renderL1Doc() {
     return [
         ...renderHead(),
         ...renderTable(),
+        ...renderLogJoin(),
         ...renderUseCases(),
         ...renderTail(),
     ].join('\n');
 }
+// How a `row=` in the L1 log joins back to the table above — the section this doc existed without for
+// 1,457 logged decisions across nine repos, none of which an agent could look up, because the DELIVERED
+// copy of this page did not exist either. L2's doc has carried the same section since its own delivery.
+// webpieces-disable no-function-outside-class -- prose section of renderL1Doc's string, beside it in this module
+function renderLogJoin() {
+    return [
+        '## How a log line joins to a row',
+        '',
+        'Every L1 decision is written to `.webpieces/logs/L1-location/<writer>.log` with `layer=L1` and',
+        '`row=<n>`, where `<n>` is a row number from the table above. So `row=6` means "this call was judged',
+        'by row 6" and you read the dimensions, the verdict, the reason and the cure straight off that line. Row `0` is',
+        'the pre-stage; it is in the table for exactly this reason.',
+        '',
+        '**The join is by DISPATCH, and that is the difference from L2.** L1 takes the FIRST matching row in',
+        '`L1_ROWS` and switches on it, so a row and a behaviour are the same object — delete the row and you',
+        'delete the block. L2\'s four guard classes each own their own ladder and join to their rows by REASON',
+        'instead (see `webpieces.branch-state-matrix.md`). A totality test walks all 80 classifications and',
+        'asserts each lands on exactly one row, so there is no verdict this page cannot explain.',
+        '',
+        'Row numbers are IDENTITY and are never reused: row 3 is retired (coordinator-in-worktree) and row 8',
+        'was added in its place rather than renumbering 4-7, because every `row=` already written to a log',
+        'would otherwise re-point.',
+        '',
+    ];
+}
 // The three questions L1 answers, the preamble and the filter — all prose, none of it row data.
 // webpieces-disable no-function-outside-class -- first section of renderL1Doc's string, beside it in this module
 function renderHead() {
@@ -191,14 +221,14 @@ function renderTable() {
         '',
         '## Table',
         '',
-        '| # | K | V | R | G | P | act | why |',
-        '|---|---|---|---|---|---|---|---|',
+        '| # | K | V | R | G | P | act | why | cure |',
+        '|---|---|---|---|---|---|---|---|---|',
         // Row 0 is the PRE-STAGE (`misplacedCdBlock`). It decides from command TEXT before a tree is
         // resolved, so it cannot be classified over the five dimensions rows 1-6 share — but it IS an
         // L1 block, and an L1 block the table did not describe is exactly the drift this table exists
         // to prevent. It is numbered 0, not 7, because it does not sit in the first-match scan; and it
         // is PRINTED because `row=0` in the L1 log has to join to something.
-        `| ${l1_rows_1.L1_PRESTAGE_ROW} | – | – | – | – | – | 4 block | a \`cd\` that is not leading + literal, judged before any tree is resolved |`,
+        `| ${l1_rows_1.L1_PRESTAGE_ROW} | – | – | – | – | – | 4 block | a \`cd\` that is not leading + literal, judged before any tree is resolved | \`cd <literal abs path> && <the rest>\` — ONE leading \`cd\`, or drop it |`,
         ...l1_rows_1.L1_ROWS.map(tableRow),
         '',
         'Rows 3, 5 and 7 are the structural blocks, and they run as ONE step (`l1LocationBlock` in `runner.ts`)',

package/src/core/l1-doc.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"l1-doc.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/l1-doc.ts"],"names":[],"mappings":"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","sourcesContent":["import { L1Row, L1UseCase, L1_ROWS, L1_PRESTAGE_ROW, allL1UseCases } from './l1-rows';\n\n// ---------------------------------------------------------------------------\n// guards/L1-location.md, rendered from L1_ROWS.\n//\n// Same arrangement as l0-matrix.renderGuardMatrixDoc(): one join('\\n') of literal markdown lines with\n// the ROW DATA interpolated from the array the guard consults. Everything that is not row data — every\n// prose section — is a literal line here, because that is the half a generator cannot own.\n//\n// A unit test (l1-matrix.spec.ts) locks guards/L1-location.md byte-identical to renderL1Doc(), and\n// `pnpm guards:generate` rewrites the file. So the table in the doc IS the array, not a description of\n// it. This module, like l1-rows.ts, has no runtime imports outside this pair so the generator can load\n// it without the package's transitive dependencies.\n// ---------------------------------------------------------------------------\n\n/** A dimension cell: the wildcard renders bare, every value renders as code. /\n// webpieces-disable no-function-outside-class -- pure cell formatter for renderL1Doc below, in this render module\nfunction cell(value: string): string {\n return value === '-' ? '-' : `\\`${value}\\``;\n}\n\n// webpieces-disable no-function-outside-class -- pure row formatter for renderL1Doc below, in this render module\nfunction tableRow(row: L1Row): string {\n const dims = [row.k, row.a, row.r, row.g, row.p].map(cell).join(' \| ');\n // Row 6 has no `why` — an EMPTY cell is `\| \|`, not `\| \|`. Two spaces would render the same in a\n // browser and fail the byte-lock, which is the whole point of locking bytes rather than markdown.\n const why = row.why === '' ? ' ' : ` ${row.why} `;\n return `\| ${row.num} \| ${dims} \| ${row.action.label} \|${why}\|`;\n}\n\n// webpieces-disable no-function-outside-class -- pure row formatter for renderL1Doc below, in this render module\nfunction useCaseRow(useCase: L1UseCase): string {\n return `\| ${useCase.num} \| ${useCase.symptom} \| ${useCase.state} \| ${useCase.verdict} \| ${useCase.fix} \|`;\n}\n\n/\n Render guards/L1-location.md.\n \n Split into three consecutive halves purely to stay inside the method-line budget — the join order is\n * what makes them one file, so keep them adjacent and keep the byte-lock test as the arbiter.\n /\n// webpieces-disable no-function-outside-class -- pure string builder over L1_ROWS, beside the array it reads\nexport function renderL1Doc(): string {\n return [\n ...renderHead(),\n ...renderTable(),\n ...renderUseCases(),\n ...renderTail(),\n ].join('\\n');\n}\n\n\n// The three questions L1 answers, the preamble and the filter — all prose, none of it row data.\n// webpieces-disable no-function-outside-class -- first section of renderL1Doc's string, beside it in this module\nfunction renderHead(): string[] {\n return [\n '# L1 — location',\n '',\n 'Goal: is this call ours to judge, is this tree governed by the release it asks for, and is git being run from the root?',\n '',\n 'Config key: none, and none is proposed.* Force-to-root and trinary-version-skew have no config',\n 'key and cannot be disabled; `excludePaths` is a top-level block, not a `hookGuards` entry. A',\n '`location-guard` key was once proposed here — it never existed, and `hookGuards` has just gone from',\n 'nine keys to three, so adding a tenth-turned-fourth for a layer nobody has asked to switch off would',\n 'run against the whole point. L0 has no key for the stronger version of the same reason: a layer that',\n 'decides whether the tooling can be trusted cannot be configured by the file it has not validated yet.',\n '',\n '',\n 'Code: `packages/tooling/ai-hook-rules/src/core/effective-tree.ts` (`EffectiveTreeResolver`,',\n '`TreeKind`) · `packages/tooling/ai-hook-rules/src/core/runner.ts` (`l1LocationBlock`,',\n '`filterByExcludedPaths`, the `foreign` check) · `.../force-to-root.ts` (`ForceToRootGuard`) ·',\n '`packages/tooling/ai-hook-rules/src/core/missing-directory.ts` (`MissingDirectoryGuard`) ·',\n '`packages/tooling/ai-hook-rules/src/core/version-sync.ts` (`VersionSyncGuard`,',\n '`WebpiecesVersions`).',\n '',\n 'L1 answers four questions, and they are genuinely separate:',\n '',\n '1. Do we govern this at all? — the escape hatches, for other repos and non-governed paths.',\n ' Answered by asking GIT (`--git-common-dir`), never by path math: see the legend under K.',\n '2. Does the directory still EXIST? — row 7. A worktree reaped out from under a live shell leaves',\n ' a cwd that names nothing, and that state needs its own name and its own message, because the',\n ' remedy for \"you are in a subdirectory\" is a `cd` back into the very directory that is gone.',\n '3. Is this tree governed by a release it did not ask for? — row 8. A worktree MAY have its own',\n ' `node_modules` (nx, vitest and the eslint plugin all execute there and load from it), and when it',\n ' has none the shim\\'s upward walk runs the main tree\\'s binary. Either way the rule is the same and',\n ' holds whichever registration form — absolute or relative — is live in the consumer: the two trees',\n ' must PIN the same `@webpieces`, or the worktree is linted, validated and built by a release its',\n ' own manifest does not ask for. Asked of the PATH acted on, never of who is asking —',\n ' agent identity was measured untrustworthy for tree detection (a worktree-isolated agent whose tree',\n ' is auto-reaped at a turn boundary silently resumes on the primary clone).',\n '4. Is the agent stranded away from the root? — force-to-root, git/gh only. Agents forget where',\n ' they are constantly, and `cd` gives them two different ways to be wrong: a `cd` that stays INSIDE',\n ' the workspace PERSISTS to later calls (so the shell can be parked in a subdirectory left by an',\n ' unrelated command turns earlier), while a `cd` that LEAVES it is reset by the harness, which says',\n ' so — `Shell cwd was reset to <root>`. Neither can be assumed, which is why every remedy names the',\n ' root explicitly instead of telling the agent to `cd` first.',\n '',\n '## Preamble — resolve the target first (Bash only)',\n '',\n '`EffectiveTreeResolver.resolve()` computes `effectiveCwd`: the directory the command actually runs in,',\n 'which is the shell\\'s cwd unless the command leads with `cd <dir> &&`. K is classified from',\n '`effectiveCwd`, not from the shell\\'s cwd — so \"a foreign repo that `cd`s into ours\" is not a cell,',\n 'it is simply `pw` after resolution.',\n '',\n 'That holds because K is resolved by ASKING GIT about `effectiveCwd`, not by testing whether the path',\n 'is lexically under the governed root. It has to be said that way round: the resolver used to do the',\n 'path test, and a linked worktree under `.claude/worktrees/*` therefore resolved `f` — every bash',\n 'guard exempt in the one sandbox agents are told to work in. A sentence in this file asserted the',\n 'opposite as fact for several releases, which is how it went unnoticed.',\n '',\n 'Only a LEADING run of `cd`/`pushd` counts. A trailing* `… && cd <exempt-tree>` must never',\n 'retroactively pull a command out of scope — that would smuggle a root-level `git push` past the',\n 'guards. Quoting is handled by `ShellSegmentScan`, so `echo \"cd sub && git push\"` is one opaque',\n 'segment and its quoted `cd` is never picked up.',\n '',\n ...renderFilterSection(),\n ];\n}\n\n// `excludePaths` — a FILTER over the rule list, not a dimension of the table. Its own function because\n// renderHead is at the 70-line method cap, and because this section is one self-contained argument.\n// webpieces-disable no-function-outside-class -- prose section of renderL1Doc's string, beside it in this module\nfunction renderFilterSection(): string[] {\n return [\n '## Filter — not a dimension (all tools)',\n '',\n '`filterByExcludedPaths` drops every rule excluded for this path: the target path for',\n 'Read/Write/Edit, `effectiveCwd` for Bash. An empty rule list means allow. This is a filter, not a row:',\n '\"exempt\" is what emerges when the list empties.',\n '',\n 'ONE path is filtered out BEFORE the list is consulted and cannot be put back: `.webpieces/`,',\n 'the tooling\\'s own state dir (`isWebpiecesStateDir`). It is gitignored in every consumer, so nothing',\n 'under it can reach a branch, be reviewed or be reverted — every reason L2 prints for protecting',\n '`main` is vacuous there. It was config-only once, which made the exemption optional on exactly the',\n 'directory webpieces itself writes to: `wp-review-upsert-pr` hands a reviewer subagent a',\n '`<primary>/.webpieces/worktrees/agent-＜id＞/pr-review/…` path, that write resolves to the PRIMARY',\n 'clone, and L2 judged the primary\\'s live branch — so the reviewer was denied \"You should not be',\n 'working on main\" whenever an unrelated session had left the primary there. There is deliberately',\n 'NO companion `\".webpieces/\"` glob seeded into `excludePaths`: a config entry that changes',\n 'nothing is a second and WEAKER spelling — the matcher below misses the bare directory that the',\n 'predicate matches — and it invites a consumer to delete it and believe the exemption went too.',\n '',\n '`excludePaths` is ONE glob list (canonical: `\"excludePaths\": [\"repositories/\"]`). The',\n '`{ rules: [...], guards: [...] }` object is retired and rejected, with the union it must become',\n 'named in the error. `wp-install-ai-hooks` migrates it in place.',\n '',\n 'This used to be a tolerated fallback, justified here by \"rejecting it would block every Bash/Edit',\n 'including the edit that would fix it.\" That was never true, and the fallback it licensed is why',\n 'consumer configs — this repo\\'s own included — sat on the dead shape for releases. A Write/Edit whose',\n 'target is `webpieces.config.json` is an unconditional PASS (see the L0 table above), and',\n '`pnpm install` has an installer bypass, so an invalid config can always be repaired from inside the',\n 'block. Config rejection is self-recoverable by construction; see `retired-config-keys.ts` for the',\n 'policy and the reasoning.',\n '',\n ];\n}\n\n// The legend, the table itself (ROW DATA), and the note on the two structural blocks.\n// webpieces-disable no-function-outside-class -- second section of renderL1Doc's string, beside it in this module\nfunction renderTable(): string[] {\n return [\n '## Legend',\n '',\n '\| col \| dimension \| values \|',\n '\|---\|---\|---\|',\n '\| K \| tree kind of the resolved target, from git\\'s own dirs \| `f` foreign repo (a DIFFERENT `--git-common-dir`) · `m` the directory does not exist · `o` outside any repo · `w` a LINKED worktree of ours (`--git-dir` ≠ `--git-common-dir`), wherever it sits on disk · `pw` ours (primary or worktree) \|',\n '\| V \| do the `@webpieces` versions agree between this worktree and the MAIN tree \| `n` skewed · `y` in sync \|',\n '\| R \| command is provably read-only inspection \| `n` · `y` \|',\n '\| G \| command invokes git/gh \| `n` · `y` \|',\n '\| P \| position of the resolved target \| `root` · `sub` \|',\n '',\n 'All of them are Bash only. Read/Write/Edit resolve their own target (`input.filePath`) and have no',\n 'dimensions — the filter is all that applies to them. The Read tool is never blocked by L1.',\n '',\n 'A linked worktree is deliberately not foreign: it is the same project, so the guards run against',\n 'THAT tree\\'s branch and cache. Every rule-scoped guard treats `p` and `w` alike, hence `pw`; row 8 below',\n 'is the ONE place they separate, and it turns on V — the versions, read off the tree itself.',\n '',\n 'PLACEMENT IS NOT IDENTITY. A worktree checked out INSIDE the repo — `<repo>/.claude/worktrees/agent-XXXX`,',\n 'which is where Claude Code puts every agent worktree — is `w` exactly like a sibling `../feature-dir` one.',\n 'K comes from git\\'s own dirs (`--git-common-dir` is identical for every checkout of one repo,',\n '`--git-dir` differs only in a linked worktree), never from whether the path sits under the governed root.',\n 'It used to short-circuit on that path test, so an in-repo worktree read as `f` — every bash guard exempt,',\n 'and row 8 unreachable, for the only layout the harness actually produces. A nested clone under',\n '`repositories/` still reads `f`, because its shared git dir is its own.',\n '',\n '`V` comes from reading manifests off disk — the MAIN tree\\'s `pnpm-workspace.yaml` catalog pin, its',\n 'installed `node_modules` version, this worktree\\'s pin, and this worktree\\'s own installed version when',\n 'it has one (which it does the moment anyone runs `pnpm add` there). Three always, a fourth when',\n 'present. Anything unreadable is NO OPINION, never skew: a guard that cannot measure must not block.',\n 'It is deliberately NOT read from `agent_id`/`agent_type` — the dimension this replaced was, and a',\n 'worktree-isolated agent was measured resuming on the primary clone after its tree was reaped, so who',\n 'is asking cannot be trusted to say which tree is being acted on.',\n '',\n '`R` is `ReadOnlyInspectionScan` — the same paranoid \"provably inert\" test the unloadable-config escape',\n 'hatch uses (allowlisted viewers/searchers only, no redirects, no `sed -i`).',\n '',\n '## Table',\n '',\n '\| # \| K \| V \| R \| G \| P \| act \| why \|',\n '\|---\|---\|---\|---\|---\|---\|---\|---\|',\n // Row 0 is the PRE-STAGE (`misplacedCdBlock`). It decides from command TEXT before a tree is\n // resolved, so it cannot be classified over the five dimensions rows 1-6 share — but it IS an\n // L1 block, and an L1 block the table did not describe is exactly the drift this table exists\n // to prevent. It is numbered 0, not 7, because it does not sit in the first-match scan; and it\n // is PRINTED because `row=0` in the L1 log has to join to something.\n `\| ${L1_PRESTAGE_ROW} \| – \| – \| – \| – \| – \| 4 block \| a \\`cd\\` that is not leading + literal, judged before any tree is resolved \|`,\n ...L1_ROWS.map(tableRow),\n '',\n 'Rows 3, 5 and 7 are the structural blocks, and they run as ONE step (`l1LocationBlock` in `runner.ts`)',\n 'so they can never be reordered by accident — row 7 (the directory is gone) first, then row 8, then',\n 'force-to-root. Row 7 is printed LAST above only because row numbers are stable across releases and',\n 'renumbering 1-6 would invalidate every `row=` in the logs; `m` matches no other row, so its position',\n 'in the scan is immaterial. All three sit after the L0',\n 'allowlist, after the `f` check, and after the `excludePaths` filter and the config-sync check. So a',\n 'cure (`cd <worktree> && pnpm install`) still reaches any tree: that is L0\\'s invariant, and row 8 does',\n 'not weaken it.',\n '',\n ];\n}\n\n// The use-case table (ROW DATA, in the doc's own numbering) and the two notes that follow it.\n// webpieces-disable no-function-outside-class -- third section of renderL1Doc's string, beside it in this module\nfunction renderUseCases(): string[] {\n return [\n '## L1 use cases',\n '',\n 'Same row shape as L0: the Fix is literal or it is not a fix. `<root>` is the absolute workspace',\n 'root — the messages name it explicitly rather than telling you to `cd` first, for the reason in the',\n 'section head (neither the shell\\'s cwd nor a `cd`\\'s persistence can be assumed).',\n '',\n '\| # \| what you SEE (exact symptom) \| state \| verdict \| Fix \|',\n '\|---\|---\|---\|---\|---\|',\n ...allL1UseCases().map(useCaseRow),\n '',\n 'Row 8 is the one that changed. It used to be ALLOWED, because the predicate was',\n '`shellAtRoot \|\| cdsToRoot` — two variables OR\\'d, so the same destination got opposite verdicts',\n 'depending on where the shell happened to start. It is now one variable, `effectiveCwd === root`.',\n '',\n 'Row 12 is the incident that produced table row 8, and it is a VERSION SKEW incident — which is why',\n 'the row that replaced it measures versions rather than agent identity. The coordinator ran',\n '`git worktree add`, `cd`\\'d in,',\n 'and worked there. An L0 version-drift fault then fired against the PRIMARY (pin `0.4.545` vs',\n '`node_modules` `0.4.526`) and prescribed `pnpm install` — which ran in the WORKTREE, internally',\n 'consistent at `0.4.526`/`0.4.526`, so it succeeded, changed nothing in the measured tree, and the guard',\n 're-denied. Five identical installs later the agent had invented a theory about the harness stripping',\n 'its `cd` and handed the problem to the human. Note what row 15 says: the fix is NOT to deny that',\n 'install. It is to make the split state unreachable, so the wrong-tree install is never plausible.',\n '',\n ];\n}\n\n// The known gap and the code anchors — prose, and the one section that must never be summarised away:\n// three code comments point at it.\n// webpieces-disable no-function-outside-class -- last section of renderL1Doc's string, beside it in this module\nfunction renderTail(): string[] {\n return [\n '## Not done — `o` is not exempt yet',\n '',\n 'Row 2 hands `\\'outside\\'` down to L2 rather than exempting it. `\\'outside\\'` is produced at',\n '`effective-tree.ts` (git has no answer for the directory) carrying `governedRoot`, and no code branches on it, so a',\n 'command in no git repo is judged against the governed repo\\'s branch and staleness state. That is a',\n 'wrong verdict, and `exempt` is the right action.',\n '',\n 'It must not ship alone. Jurisdiction comes from the shell cwd, not from what the command touches,',\n 'so exempting `o` opens a bypass an agent reaches by typing `cd /tmp &&`:',\n '',\n '\| command \| today \| with `o → exempt` alone \|',\n '\|---\|---\|---\|',\n '\| `cd /tmp && ls` \| judged against the repo \| exempt — correct \|',\n '\| `cd /tmp && git -C $REPO commit` \| L2 guards fire \| exempt — every L2 guard bypassed \|',\n '\| `cd /tmp && rm -rf $REPO/packages/http/src` \| judged \| exempt — unguarded \|',\n '',\n 'The two cases only separate once jurisdiction is judged on what the command touches (explicit',\n '`git -C` / `--work-tree`, then path arguments, then the `cd`, then the shell cwd), with the fail-safe',\n 'rule that any resolved target inside `governedRoot` means `pw`. Ship the two together, or neither.',\n '',\n 'Tracked in `backlog/bug-bash-guards-judge-the-shell-cwd-not-the-paths-the-command-touches.md` and',\n '`backlog/bug-outside-tree-kind-is-never-consumed-so-a-non-git-dir-is-judged-against-the-governed-repo.md`.',\n 'That resolver has three consumers — L1\\'s K, L2\\'s scope dimension, and `excludePaths` on the Bash path',\n '— which is why the backlog says fix once**.',\n '',\n '---',\n '',\n '',\n '## Code anchors',\n '',\n '\| section \| file \| symbol \|',\n '\|---\|---\|---\|',\n '\| resolver, K \| `ai-hook-rules/src/core/effective-tree.ts` \| `EffectiveTreeResolver`, `TreeKind` \|',\n '\| the two structural blocks, in order \| `ai-hook-rules/src/core/runner.ts` \| `l1LocationBlock` \|',\n '\| trinary-version-skew (row 8), V, R \| `ai-hook-rules/src/core/version-sync.ts` \| `VersionSyncGuard`, `WebpiecesVersions` \|',\n '\| force-to-root (row 5) \| `ai-hook-rules/src/core/force-to-root.ts` \| `ForceToRootGuard` \|',\n '\| the directory is gone (row 7) \| `ai-hook-rules/src/core/missing-directory.ts` \| `MissingDirectoryGuard` \|',\n '\| the filter \| `ai-hook-rules/src/core/runner.ts` \| `filterByExcludedPaths` \|',\n '\| `excludePaths` shape \| `rules-config/src/exclude-hook-paths.ts`, `validate-config.ts`, `retired-config-keys.ts` \| `ExcludePaths`, `validateExcludePaths` \|',\n '\| the `.webpieces/` skip \| `rules-config/src/exclude-hook-paths.ts` \| `isWebpiecesStateDir` \|',\n '',\n ];\n}\n"]}
1	+ {"version":3,"file":"l1-doc.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/l1-doc.ts"],"names":[],"mappings":"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","sourcesContent":["import { L1Row, L1UseCase, L1_ROWS, L1_PRESTAGE_ROW, allL1UseCases } from './l1-rows';\n\n// ---------------------------------------------------------------------------\n// guards/L1-location.md, rendered from L1_ROWS.\n//\n// Same arrangement as l0-matrix.renderGuardMatrixDoc(): one join('\\n') of literal markdown lines with\n// the ROW DATA interpolated from the array the guard consults. Everything that is not row data — every\n// prose section — is a literal line here, because that is the half a generator cannot own.\n//\n// A unit test (l1-matrix.spec.ts) locks guards/L1-location.md byte-identical to renderL1Doc(), and\n// `pnpm guards:generate` rewrites the file. So the table in the doc IS the array, not a description of\n// it. This module, like l1-rows.ts, has no runtime imports outside this pair so the generator can load\n// it without the package's transitive dependencies.\n// ---------------------------------------------------------------------------\n\n/** A dimension cell: the wildcard renders bare, every value renders as code. /\n// webpieces-disable no-function-outside-class -- pure cell formatter for renderL1Doc below, in this render module\nfunction cell(value: string): string {\n return value === '-' ? '-' : `\\`${value}\\``;\n}\n\n// webpieces-disable no-function-outside-class -- pure row formatter for renderL1Doc below, in this render module\nfunction tableRow(row: L1Row): string {\n const dims = [row.k, row.a, row.r, row.g, row.p].map(cell).join(' \| ');\n // Row 6 has no `why` — an EMPTY cell is `\| \|`, not `\| \|`. Two spaces would render the same in a\n // browser and fail the byte-lock, which is the whole point of locking bytes rather than markdown.\n const why = row.why === '' ? ' ' : ` ${row.why} `;\n // The CURE column exists so a reader who arrived here from a `row=` in a log gets the remedy on the\n // same line as the verdict, the way L2's matrix does. Only blocking rows have one; a row that hands\n // down to L2 or exempts has nothing to cure, and says so rather than leaving the cell blank.\n const cure = row.cure === null ? 'n/a — not a block' : row.cure.summary;\n return `\| ${row.num} \| ${dims} \| ${row.action.label} \|${why}\| ${cure} \|`;\n}\n\n// webpieces-disable no-function-outside-class -- pure row formatter for renderL1Doc below, in this render module\nfunction useCaseRow(useCase: L1UseCase): string {\n return `\| ${useCase.num} \| ${useCase.symptom} \| ${useCase.state} \| ${useCase.verdict} \| ${useCase.fix} \|`;\n}\n\n/\n Render guards/L1-location.md.\n \n Split into three consecutive halves purely to stay inside the method-line budget — the join order is\n * what makes them one file, so keep them adjacent and keep the byte-lock test as the arbiter.\n /\n// webpieces-disable no-function-outside-class -- pure string builder over L1_ROWS, beside the array it reads\nexport function renderL1Doc(): string {\n return [\n ...renderHead(),\n ...renderTable(),\n ...renderLogJoin(),\n ...renderUseCases(),\n ...renderTail(),\n ].join('\\n');\n}\n\n// How a `row=` in the L1 log joins back to the table above — the section this doc existed without for\n// 1,457 logged decisions across nine repos, none of which an agent could look up, because the DELIVERED\n// copy of this page did not exist either. L2's doc has carried the same section since its own delivery.\n// webpieces-disable no-function-outside-class -- prose section of renderL1Doc's string, beside it in this module\nfunction renderLogJoin(): string[] {\n return [\n '## How a log line joins to a row',\n '',\n 'Every L1 decision is written to `.webpieces/logs/L1-location/<writer>.log` with `layer=L1` and',\n '`row=<n>`, where `<n>` is a row number from the table above. So `row=6` means \"this call was judged',\n 'by row 6\" and you read the dimensions, the verdict, the reason and the cure straight off that line. Row `0` is',\n 'the pre-stage; it is in the table for exactly this reason.',\n '',\n 'The join is by DISPATCH, and that is the difference from L2.* L1 takes the FIRST matching row in',\n '`L1_ROWS` and switches on it, so a row and a behaviour are the same object — delete the row and you',\n 'delete the block. L2\\'s four guard classes each own their own ladder and join to their rows by REASON',\n 'instead (see `webpieces.branch-state-matrix.md`). A totality test walks all 80 classifications and',\n 'asserts each lands on exactly one row, so there is no verdict this page cannot explain.',\n '',\n 'Row numbers are IDENTITY and are never reused: row 3 is retired (coordinator-in-worktree) and row 8',\n 'was added in its place rather than renumbering 4-7, because every `row=` already written to a log',\n 'would otherwise re-point.',\n '',\n ];\n}\n\n\n// The three questions L1 answers, the preamble and the filter — all prose, none of it row data.\n// webpieces-disable no-function-outside-class -- first section of renderL1Doc's string, beside it in this module\nfunction renderHead(): string[] {\n return [\n '# L1 — location',\n '',\n 'Goal: is this call ours to judge, is this tree governed by the release it asks for, and is git being run from the root?',\n '',\n 'Config key: none, and none is proposed. Force-to-root and trinary-version-skew have no config',\n 'key and cannot be disabled; `excludePaths` is a top-level block, not a `hookGuards` entry. A',\n '`location-guard` key was once proposed here — it never existed, and `hookGuards` has just gone from',\n 'nine keys to three, so adding a tenth-turned-fourth for a layer nobody has asked to switch off would',\n 'run against the whole point. L0 has no key for the stronger version of the same reason: a layer that',\n 'decides whether the tooling can be trusted cannot be configured by the file it has not validated yet.',\n '',\n '',\n 'Code: `packages/tooling/ai-hook-rules/src/core/effective-tree.ts` (`EffectiveTreeResolver`,',\n '`TreeKind`) · `packages/tooling/ai-hook-rules/src/core/runner.ts` (`l1LocationBlock`,',\n '`filterByExcludedPaths`, the `foreign` check) · `.../force-to-root.ts` (`ForceToRootGuard`) ·',\n '`packages/tooling/ai-hook-rules/src/core/missing-directory.ts` (`MissingDirectoryGuard`) ·',\n '`packages/tooling/ai-hook-rules/src/core/version-sync.ts` (`VersionSyncGuard`,',\n '`WebpiecesVersions`).',\n '',\n 'L1 answers four questions, and they are genuinely separate:',\n '',\n '1. Do we govern this at all? — the escape hatches, for other repos and non-governed paths.',\n ' Answered by asking GIT (`--git-common-dir`), never by path math: see the legend under K.',\n '2. Does the directory still EXIST? — row 7. A worktree reaped out from under a live shell leaves',\n ' a cwd that names nothing, and that state needs its own name and its own message, because the',\n ' remedy for \"you are in a subdirectory\" is a `cd` back into the very directory that is gone.',\n '3. Is this tree governed by a release it did not ask for? — row 8. A worktree MAY have its own',\n ' `node_modules` (nx, vitest and the eslint plugin all execute there and load from it), and when it',\n ' has none the shim\\'s upward walk runs the main tree\\'s binary. Either way the rule is the same and',\n ' holds whichever registration form — absolute or relative — is live in the consumer: the two trees',\n ' must PIN the same `@webpieces`, or the worktree is linted, validated and built by a release its',\n ' own manifest does not ask for. Asked of the PATH acted on, never of who is asking —',\n ' agent identity was measured untrustworthy for tree detection (a worktree-isolated agent whose tree',\n ' is auto-reaped at a turn boundary silently resumes on the primary clone).',\n '4. Is the agent stranded away from the root? — force-to-root, git/gh only. Agents forget where',\n ' they are constantly, and `cd` gives them two different ways to be wrong: a `cd` that stays INSIDE',\n ' the workspace PERSISTS to later calls (so the shell can be parked in a subdirectory left by an',\n ' unrelated command turns earlier), while a `cd` that LEAVES it is reset by the harness, which says',\n ' so — `Shell cwd was reset to <root>`. Neither can be assumed, which is why every remedy names the',\n ' root explicitly instead of telling the agent to `cd` first.',\n '',\n '## Preamble — resolve the target first (Bash only)',\n '',\n '`EffectiveTreeResolver.resolve()` computes `effectiveCwd`: the directory the command actually runs in,',\n 'which is the shell\\'s cwd unless the command leads with `cd <dir> &&`. K is classified from',\n '`effectiveCwd`, not from the shell\\'s cwd — so \"a foreign repo that `cd`s into ours\" is not a cell,',\n 'it is simply `pw` after resolution.',\n '',\n 'That holds because K is resolved by ASKING GIT about `effectiveCwd`, not by testing whether the path',\n 'is lexically under the governed root. It has to be said that way round: the resolver used to do the',\n 'path test, and a linked worktree under `.claude/worktrees/*` therefore resolved `f` — every bash',\n 'guard exempt in the one sandbox agents are told to work in. A sentence in this file asserted the',\n 'opposite as fact for several releases, which is how it went unnoticed.',\n '',\n 'Only a LEADING run of `cd`/`pushd` counts. A trailing* `… && cd <exempt-tree>` must never',\n 'retroactively pull a command out of scope — that would smuggle a root-level `git push` past the',\n 'guards. Quoting is handled by `ShellSegmentScan`, so `echo \"cd sub && git push\"` is one opaque',\n 'segment and its quoted `cd` is never picked up.',\n '',\n ...renderFilterSection(),\n ];\n}\n\n// `excludePaths` — a FILTER over the rule list, not a dimension of the table. Its own function because\n// renderHead is at the 70-line method cap, and because this section is one self-contained argument.\n// webpieces-disable no-function-outside-class -- prose section of renderL1Doc's string, beside it in this module\nfunction renderFilterSection(): string[] {\n return [\n '## Filter — not a dimension (all tools)',\n '',\n '`filterByExcludedPaths` drops every rule excluded for this path: the target path for',\n 'Read/Write/Edit, `effectiveCwd` for Bash. An empty rule list means allow. This is a filter, not a row:',\n '\"exempt\" is what emerges when the list empties.',\n '',\n 'ONE path is filtered out BEFORE the list is consulted and cannot be put back: `.webpieces/`,',\n 'the tooling\\'s own state dir (`isWebpiecesStateDir`). It is gitignored in every consumer, so nothing',\n 'under it can reach a branch, be reviewed or be reverted — every reason L2 prints for protecting',\n '`main` is vacuous there. It was config-only once, which made the exemption optional on exactly the',\n 'directory webpieces itself writes to: `wp-review-upsert-pr` hands a reviewer subagent a',\n '`<primary>/.webpieces/worktrees/agent-＜id＞/pr-review/…` path, that write resolves to the PRIMARY',\n 'clone, and L2 judged the primary\\'s live branch — so the reviewer was denied \"You should not be',\n 'working on main\" whenever an unrelated session had left the primary there. There is deliberately',\n 'NO companion `\".webpieces/\"` glob seeded into `excludePaths`: a config entry that changes',\n 'nothing is a second and WEAKER spelling — the matcher below misses the bare directory that the',\n 'predicate matches — and it invites a consumer to delete it and believe the exemption went too.',\n '',\n '`excludePaths` is ONE glob list (canonical: `\"excludePaths\": [\"repositories/\"]`). The',\n '`{ rules: [...], guards: [...] }` object is retired and rejected, with the union it must become',\n 'named in the error. `wp-install-ai-hooks` migrates it in place.',\n '',\n 'This used to be a tolerated fallback, justified here by \"rejecting it would block every Bash/Edit',\n 'including the edit that would fix it.\" That was never true, and the fallback it licensed is why',\n 'consumer configs — this repo\\'s own included — sat on the dead shape for releases. A Write/Edit whose',\n 'target is `webpieces.config.json` is an unconditional PASS (see the L0 table above), and',\n '`pnpm install` has an installer bypass, so an invalid config can always be repaired from inside the',\n 'block. Config rejection is self-recoverable by construction; see `retired-config-keys.ts` for the',\n 'policy and the reasoning.',\n '',\n ];\n}\n\n// The legend, the table itself (ROW DATA), and the note on the two structural blocks.\n// webpieces-disable no-function-outside-class -- second section of renderL1Doc's string, beside it in this module\nfunction renderTable(): string[] {\n return [\n '## Legend',\n '',\n '\| col \| dimension \| values \|',\n '\|---\|---\|---\|',\n '\| K \| tree kind of the resolved target, from git\\'s own dirs \| `f` foreign repo (a DIFFERENT `--git-common-dir`) · `m` the directory does not exist · `o` outside any repo · `w` a LINKED worktree of ours (`--git-dir` ≠ `--git-common-dir`), wherever it sits on disk · `pw` ours (primary or worktree) \|',\n '\| V \| do the `@webpieces` versions agree between this worktree and the MAIN tree \| `n` skewed · `y` in sync \|',\n '\| R \| command is provably read-only inspection \| `n` · `y` \|',\n '\| G \| command invokes git/gh \| `n` · `y` \|',\n '\| P \| position of the resolved target \| `root` · `sub` \|',\n '',\n 'All of them are Bash only. Read/Write/Edit resolve their own target (`input.filePath`) and have no',\n 'dimensions — the filter is all that applies to them. The Read tool is never blocked by L1.',\n '',\n 'A linked worktree is deliberately not foreign: it is the same project, so the guards run against',\n 'THAT tree\\'s branch and cache. Every rule-scoped guard treats `p` and `w` alike, hence `pw`; row 8 below',\n 'is the ONE place they separate, and it turns on V — the versions, read off the tree itself.',\n '',\n 'PLACEMENT IS NOT IDENTITY. A worktree checked out INSIDE the repo — `<repo>/.claude/worktrees/agent-XXXX`,',\n 'which is where Claude Code puts every agent worktree — is `w` exactly like a sibling `../feature-dir` one.',\n 'K comes from git\\'s own dirs (`--git-common-dir` is identical for every checkout of one repo,',\n '`--git-dir` differs only in a linked worktree), never from whether the path sits under the governed root.',\n 'It used to short-circuit on that path test, so an in-repo worktree read as `f` — every bash guard exempt,',\n 'and row 8 unreachable, for the only layout the harness actually produces. A nested clone under',\n '`repositories/` still reads `f`, because its shared git dir is its own.',\n '',\n '`V` comes from reading manifests off disk — the MAIN tree\\'s `pnpm-workspace.yaml` catalog pin, its',\n 'installed `node_modules` version, this worktree\\'s pin, and this worktree\\'s own installed version when',\n 'it has one (which it does the moment anyone runs `pnpm add` there). Three always, a fourth when',\n 'present. Anything unreadable is NO OPINION, never skew: a guard that cannot measure must not block.',\n 'It is deliberately NOT read from `agent_id`/`agent_type` — the dimension this replaced was, and a',\n 'worktree-isolated agent was measured resuming on the primary clone after its tree was reaped, so who',\n 'is asking cannot be trusted to say which tree is being acted on.',\n '',\n '`R` is `ReadOnlyInspectionScan` — the same paranoid \"provably inert\" test the unloadable-config escape',\n 'hatch uses (allowlisted viewers/searchers only, no redirects, no `sed -i`).',\n '',\n '## Table',\n '',\n '\| # \| K \| V \| R \| G \| P \| act \| why \| cure \|',\n '\|---\|---\|---\|---\|---\|---\|---\|---\|---\|',\n // Row 0 is the PRE-STAGE (`misplacedCdBlock`). It decides from command TEXT before a tree is\n // resolved, so it cannot be classified over the five dimensions rows 1-6 share — but it IS an\n // L1 block, and an L1 block the table did not describe is exactly the drift this table exists\n // to prevent. It is numbered 0, not 7, because it does not sit in the first-match scan; and it\n // is PRINTED because `row=0` in the L1 log has to join to something.\n `\| ${L1_PRESTAGE_ROW} \| – \| – \| – \| – \| – \| 4 block \| a \\`cd\\` that is not leading + literal, judged before any tree is resolved \| \\`cd <literal abs path> && <the rest>\\` — ONE leading \\`cd\\`, or drop it \|`,\n ...L1_ROWS.map(tableRow),\n '',\n 'Rows 3, 5 and 7 are the structural blocks, and they run as ONE step (`l1LocationBlock` in `runner.ts`)',\n 'so they can never be reordered by accident — row 7 (the directory is gone) first, then row 8, then',\n 'force-to-root. Row 7 is printed LAST above only because row numbers are stable across releases and',\n 'renumbering 1-6 would invalidate every `row=` in the logs; `m` matches no other row, so its position',\n 'in the scan is immaterial. All three sit after the L0',\n 'allowlist, after the `f` check, and after the `excludePaths` filter and the config-sync check. So a',\n 'cure (`cd <worktree> && pnpm install`) still reaches any tree: that is L0\\'s invariant, and row 8 does',\n 'not weaken it.',\n '',\n ];\n}\n\n// The use-case table (ROW DATA, in the doc's own numbering) and the two notes that follow it.\n// webpieces-disable no-function-outside-class -- third section of renderL1Doc's string, beside it in this module\nfunction renderUseCases(): string[] {\n return [\n '## L1 use cases',\n '',\n 'Same row shape as L0: the Fix is literal or it is not a fix. `<root>` is the absolute workspace',\n 'root — the messages name it explicitly rather than telling you to `cd` first, for the reason in the',\n 'section head (neither the shell\\'s cwd nor a `cd`\\'s persistence can be assumed).',\n '',\n '\| # \| what you SEE (exact symptom) \| state \| verdict \| Fix \|',\n '\|---\|---\|---\|---\|---\|',\n ...allL1UseCases().map(useCaseRow),\n '',\n 'Row 8 is the one that changed. It used to be ALLOWED, because the predicate was',\n '`shellAtRoot \|\| cdsToRoot` — two variables OR\\'d, so the same destination got opposite verdicts',\n 'depending on where the shell happened to start. It is now one variable, `effectiveCwd === root`.',\n '',\n 'Row 12 is the incident that produced table row 8, and it is a VERSION SKEW incident — which is why',\n 'the row that replaced it measures versions rather than agent identity. The coordinator ran',\n '`git worktree add`, `cd`\\'d in,',\n 'and worked there. An L0 version-drift fault then fired against the PRIMARY (pin `0.4.545` vs',\n '`node_modules` `0.4.526`) and prescribed `pnpm install` — which ran in the WORKTREE, internally',\n 'consistent at `0.4.526`/`0.4.526`, so it succeeded, changed nothing in the measured tree, and the guard',\n 're-denied. Five identical installs later the agent had invented a theory about the harness stripping',\n 'its `cd` and handed the problem to the human. Note what row 15 says: the fix is NOT to deny that',\n 'install. It is to make the split state unreachable, so the wrong-tree install is never plausible.',\n '',\n ];\n}\n\n// The known gap and the code anchors — prose, and the one section that must never be summarised away:\n// three code comments point at it.\n// webpieces-disable no-function-outside-class -- last section of renderL1Doc's string, beside it in this module\nfunction renderTail(): string[] {\n return [\n '## Not done — `o` is not exempt yet',\n '',\n 'Row 2 hands `\\'outside\\'` down to L2 rather than exempting it. `\\'outside\\'` is produced at',\n '`effective-tree.ts` (git has no answer for the directory) carrying `governedRoot`, and no code branches on it, so a',\n 'command in no git repo is judged against the governed repo\\'s branch and staleness state. That is a',\n 'wrong verdict, and `exempt` is the right action.',\n '',\n 'It must not ship alone. Jurisdiction comes from the shell cwd, not from what the command touches,',\n 'so exempting `o` opens a bypass an agent reaches by typing `cd /tmp &&`:',\n '',\n '\| command \| today \| with `o → exempt` alone \|',\n '\|---\|---\|---\|',\n '\| `cd /tmp && ls` \| judged against the repo \| exempt — correct \|',\n '\| `cd /tmp && git -C $REPO commit` \| L2 guards fire \| exempt — every L2 guard bypassed \|',\n '\| `cd /tmp && rm -rf $REPO/packages/http/src` \| judged \| exempt — unguarded \|',\n '',\n 'The two cases only separate once jurisdiction is judged on what the command touches (explicit',\n '`git -C` / `--work-tree`, then path arguments, then the `cd`, then the shell cwd), with the fail-safe',\n 'rule that any resolved target inside `governedRoot` means `pw`. Ship the two together, or neither.',\n '',\n 'Tracked in `backlog/bug-bash-guards-judge-the-shell-cwd-not-the-paths-the-command-touches.md` and',\n '`backlog/bug-outside-tree-kind-is-never-consumed-so-a-non-git-dir-is-judged-against-the-governed-repo.md`.',\n 'That resolver has three consumers — L1\\'s K, L2\\'s scope dimension, and `excludePaths` on the Bash path',\n '— which is why the backlog says fix once**.',\n '',\n '---',\n '',\n '',\n '## Code anchors',\n '',\n '\| section \| file \| symbol \|',\n '\|---\|---\|---\|',\n '\| resolver, K \| `ai-hook-rules/src/core/effective-tree.ts` \| `EffectiveTreeResolver`, `TreeKind` \|',\n '\| the two structural blocks, in order \| `ai-hook-rules/src/core/runner.ts` \| `l1LocationBlock` \|',\n '\| trinary-version-skew (row 8), V, R \| `ai-hook-rules/src/core/version-sync.ts` \| `VersionSyncGuard`, `WebpiecesVersions` \|',\n '\| force-to-root (row 5) \| `ai-hook-rules/src/core/force-to-root.ts` \| `ForceToRootGuard` \|',\n '\| the directory is gone (row 7) \| `ai-hook-rules/src/core/missing-directory.ts` \| `MissingDirectoryGuard` \|',\n '\| the filter \| `ai-hook-rules/src/core/runner.ts` \| `filterByExcludedPaths` \|',\n '\| `excludePaths` shape \| `rules-config/src/exclude-hook-paths.ts`, `validate-config.ts`, `retired-config-keys.ts` \| `ExcludePaths`, `validateExcludePaths` \|',\n '\| the `.webpieces/` skip \| `rules-config/src/exclude-hook-paths.ts` \| `isWebpiecesStateDir` \|',\n '',\n ];\n}\n"]}

package/src/core/l1-matrix-doc.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ /** The delivered copy of `guards/L1-location.md`, as a rules-config template name. */
2	+ export declare const LOCATION_MATRIX_DOC = "webpieces.location-matrix.md";

package/src/core/l1-matrix-doc.js ADDED Viewed

@@ -0,0 +1,20 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// The L1 matrix, DELIVERED — the same treatment L0 and L2 already had.
+//
+// THE GAP THIS CLOSES. L1 stamps `layer=L1 row=<n>` on every decision it makes: a fleet audit counted
+// 1,457 of them across nine repos, with rows 0, 1, 4, 5, 6 and 7 all in active use. `.webpieces/instruct-ai/`
+// shipped a matrix for L2 (`webpieces.branch-state-matrix.md`) and one for L0 (`webpieces.guard-matrix.md`)
+// — and NOTHING for L1. An agent told "L1 row 6" had nowhere to look it up.
+//
+// The table itself was never missing; `guards/L1-location.md` has been generated from `L1_ROWS` for
+// releases. What was missing is DELIVERY: `guards/` is a path in webpieces' own repo, not something a
+// consumer repo has. So this names the delivered copy, `generate-guard-docs.ts` writes it from the same
+// `renderL1Doc()` that writes `guards/L1-location.md`, and `l1-matrix.spec.ts` byte-locks the two
+// together — the delivered page cannot describe a table the guards no longer have.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCATION_MATRIX_DOC = void 0;
+/** The delivered copy of `guards/L1-location.md`, as a rules-config template name. */
+exports.LOCATION_MATRIX_DOC = 'webpieces.location-matrix.md';
+//# sourceMappingURL=l1-matrix-doc.js.map

package/src/core/l1-matrix-doc.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"l1-matrix-doc.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/l1-matrix-doc.ts"],"names":[],"mappings":";AAAA,8EAA8E;AAC9E,uEAAuE;AACvE,EAAE;AACF,sGAAsG;AACtG,8GAA8G;AAC9G,4GAA4G;AAC5G,4EAA4E;AAC5E,EAAE;AACF,oGAAoG;AACpG,sGAAsG;AACtG,wGAAwG;AACxG,kGAAkG;AAClG,mFAAmF;AACnF,8EAA8E;;;AAE9E,sFAAsF;AACzE,QAAA,mBAAmB,GAAG,8BAA8B,CAAC","sourcesContent":["// ---------------------------------------------------------------------------\n// The L1 matrix, DELIVERED — the same treatment L0 and L2 already had.\n//\n// THE GAP THIS CLOSES. L1 stamps `layer=L1 row=<n>` on every decision it makes: a fleet audit counted\n// 1,457 of them across nine repos, with rows 0, 1, 4, 5, 6 and 7 all in active use. `.webpieces/instruct-ai/`\n// shipped a matrix for L2 (`webpieces.branch-state-matrix.md`) and one for L0 (`webpieces.guard-matrix.md`)\n// — and NOTHING for L1. An agent told \"L1 row 6\" had nowhere to look it up.\n//\n// The table itself was never missing; `guards/L1-location.md` has been generated from `L1_ROWS` for\n// releases. What was missing is DELIVERY: `guards/` is a path in webpieces' own repo, not something a\n// consumer repo has. So this names the delivered copy, `generate-guard-docs.ts` writes it from the same\n// `renderL1Doc()` that writes `guards/L1-location.md`, and `l1-matrix.spec.ts` byte-locks the two\n// together — the delivered page cannot describe a table the guards no longer have.\n// ---------------------------------------------------------------------------\n\n/** The delivered copy of `guards/L1-location.md`, as a rules-config template name. */\nexport const LOCATION_MATRIX_DOC = 'webpieces.location-matrix.md';\n"]}