@erclx/aitk 3.1.0 → 3.2.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/git-pr/SKILL.md

@@ -84,9 +84,23 @@ A detached HEAD gives `git branch --show-current` an empty result, which would r
 
 ### Labels
 
-Read `.claude/aitk/pr-labels.toml` from the project root. A project that has not declared a map gets no labels and no warning, since a label set this skill supplied would be a guess about that project's surfaces.
+Ask the CLI first:
 
-When the file resolves, match it against the name-only diff per `${CLAUDE_SKILL_DIR}/references/labels.md` and write the comma-separated result into `pr_labels` below. Leave `pr_labels` empty when no map resolves or no prefix matches, which skips the labelling command rather than running it against nothing.
+```bash
+aitk labels audit --base <base> --json
+```
+
+The record carries `labels`, the set this branch earns, and `uncovered`, the changed paths no row of the map reaches. Join `labels` with commas into `pr_labels` below. Report each `uncovered` path beside the result line, naming the map so the reader knows where a row would go, since a surface nobody covered merges bare and nothing else says so.
+
+Branch on the record rather than on the exit. An operator's shell profile may wrap `aitk` in a function whose status comes from a trailing command, and the binary exits 1 for an unknown subcommand and 1 for an ordinary refusal alike.
+
+A `reason` of `no-map` is the answer that the project declared no map, which earns no labels and no warning: a label set this skill supplied would be a guess about that project's surfaces. Stop there and label nothing.
+
+Every other `reason` is a map or a range the verb could not read, which is `unreadable-map`, `no-domains`, `no-base`, and `unreadable-changes`, plus `bad-base` for a ref this skill resolved wrongly. Take the fallback below and warn beside the result line, naming the reason. A map with a typo in it still has rows a prefix match can reach, and reading the refusal as an absence would open the pull request with no labels and nothing said, which is the surface merging bare that the verb exists to name.
+
+The fallback is reading `.claude/aitk/pr-labels.toml` and matching it against the name-only diff per `${CLAUDE_SKILL_DIR}/references/labels.md`. It also covers no record coming back at all, which is an installed `aitk` predating the verb, since a skill reaches a target the moment it merges while the CLI reaches one only when a release publishes. The fallback labels correctly and reports no uncovered path, which is the half only the verb carries.
+
+Leave `pr_labels` empty when no map resolves or no prefix matches, which skips the labelling command rather than running it against nothing.
 
 ### Final command
 

package/claude/skills/git-pr/references/labels.md

@@ -29,11 +29,35 @@ A label takes more than one prefix when two folders read as one surface. Two lab
 
 Matching is prefix-anchored, so a row written for an authoring root reaches nothing under the copy a project consumes. A surface living only under a dotted folder carries its own prefix on the row that owns its subject, and a folder holding several subjects rather than one splits across the rows that own them.
 
-The map is authored by hand and nothing detects a directory it fails to cover, so a surface added after the map was written labels nothing until someone adds a row. A map that has been censused against its own history says in its comment where that check is owned, so a reader meeting the gap is sent somewhere rather than left with the prediction.
+The map is authored by hand, so a surface added after it was written labels nothing until someone adds a row. `aitk labels audit` is what names that surface before the branch merges.
 
 ## Paths a map declines to label
 
-A path that moves only when a release or a generator rewrites it earns no row. Release automation applies its own label, and a domain label on a generated file gives a mechanical edit a subject it does not have. Neither is covered, so both are recorded in the map's comment with the reason, which is what separates a path nobody has gotten to from one somebody decided against.
+A path that moves only when a release or a generator rewrites it earns no row. Release automation applies its own label, and a domain label on a generated file gives a mechanical edit a subject it does not have.
+
+Both go under a `[declined]` table keyed by the reason, in the same file and matched by the same prefix rule:
+
+```toml
+[declined]
+release-managed = ["CHANGELOG.md", "package.json"]
+generated = ["build/manifest.json"]
+```
+
+A table rather than a comment because the check reads it. A path here is a decision already taken and a path under neither table is a gap nobody has gotten to, and a report that could not tell those apart would be useful about neither.
+
+A path claimed by a `[domains]` row and a `[declined]` row takes the label. It already has a subject, so reporting it as deliberately unlabelled would contradict the label the same run applies.
+
+## Reporting a surface no row reaches
+
+```bash
+aitk labels audit --base <base> --json
+```
+
+The record carries `labels`, `declined`, and `uncovered`. It exits 2 when `uncovered` has anything in it and 1 when it refuses, with `reason` naming the cause: `no-map` for a project that declared none, and a parse or range failure otherwise.
+
+It reports and never gates. Whether an uncovered surface deserves a label is a judgment only the person who owns that surface can make, and a push failing on one teaches a contributor to route around the check while nothing about the surface has changed.
+
+What it leaves unmeasured is a prefix reaching no path, so a row left behind by a deleted folder stays in the map. That is the map going stale from the other side and a second measure rather than this one.
 
 ## Matching
 

package/docs/agents/audits.md

@@ -22,11 +22,11 @@ aitk audits list --json
 
 ## What it runs
 
-Fifteen verbs, listed by `aitk audits list`. Each runs once in its fullest form, and the aggregate reads that verb's own record rather than imposing a shared envelope on it. Every one of those records already has consumers naming its keys, so a common shape would be a breaking change bought for tidiness.
+Sixteen verbs, listed by `aitk audits list`. Each runs once in its fullest form, and the aggregate reads that verb's own record rather than imposing a shared envelope on it. Every one of those records already has consumers naming its keys, so a common shape would be a breaking change bought for tidiness.
 
 The verbs walk separate trees and share no state, so they run together. Measured on the authoring machine at twelve verbs, a run finished in 0.8 seconds of wall clock against 4.4 seconds of processor, which is under every other stage in `bun run check`. `aitk deps audit` is the one that changes that reading, since it reaches a network rather than a tree and its latency is the index's rather than this machine's.
 
-Thirteen of the fifteen read a tree on this disk. The two added by `state-scoped-risk.md` read committed state rather than an arriving change, which is the gap every review surface here leaves by construction.
+Thirteen of the sixteen read a tree on this disk. The two added by `state-scoped-risk.md` read committed state rather than an arriving change, which is the gap every review surface here leaves by construction, and the one added by `label-coverage.md` reads a branch range against a map the project declares.
 
 Each is invoked as the CLI the caller is running rather than as a global `aitk`. A globally installed binary resolves to the main checkout no matter which worktree is executing, so the aggregate would measure a tree the branch never touched and report a pass over it.
 

package/docs/agents/commands.md

@@ -50,6 +50,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                        |
 | `aitk secrets scan`        | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`)                          |
 | `aitk deps audit`          | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`) |
+| `aitk labels audit`        | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`)                                  |
 | `aitk audits run`          | Run every audit as one set, report per check under one verdict, and compare each count to the recorded baseline (`--json`, `--record`)         |
 | `aitk audits list`         | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)                                                      |
 | `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                          |
@@ -77,6 +78,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `markdown`  | `audit`                                                                                                     |
 | `secrets`   | `scan`                                                                                                      |
 | `deps`      | `audit`                                                                                                     |
+| `labels`    | `audit`                                                                                                     |
 | `audits`    | `run`, `list`                                                                                               |
 
 Common patterns:

package/docs/agents/index.md

@@ -18,6 +18,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Indexes](indexes.md): Flags, exit codes, and JSON shape for aitk indexes regen, plus when it auto-stages what it rewrote
 - [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
 - [Intake](intake.md): Reading intake folder counts and items, the three read states an item can be in, landing a batch of selections in one cluster, the refusal reasons, and why a call is scoped to one file
+- [Label coverage](label-coverage.md): Reading a changed set against the pull request label map, the two tables it matches, how a gap is separated from a decision, and why an absent map is an answer
 - [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead

package/docs/agents/install-and-sync.md

@@ -138,11 +138,14 @@ edit and a job counting those stays red with no remedy.
 
 ### Surfaces reported beside the domains
 
-Four sections sit outside the per-domain scan, because each names something
-that walk cannot see. None of them produces a change, and no sync command
-applies any of them.
-
-All four report only against a toolkit-managed target, which is one carrying a
+Six sections sit outside the per-domain scan, because each names something
+that walk cannot see: `seeds`, `superseded`, `unmigrated`, `newSkills`,
+`newRules`, and `reverse`. None of them produces a change, and no sync command
+applies any of them. The headings below group the first three together and give
+`newSkills` its description under `newRules`, which answers the same question
+about a different corpus.
+
+All six report only against a toolkit-managed target, which is one carrying a
 `.claude/` directory, a `CLAUDE.md`, or a domain still at the root layout. The
 report says so through `managed` in the JSON and routes an unmanaged directory to
 `aitk init`. Seeds are why the gate exists, since they enumerate from the toolkit
@@ -198,6 +201,66 @@ the toolkit ships, so a root folder holding the project's own documents beside
 the installed ones reports the installed subset, where a listing reports every
 file and proposes relocating the lot.
 
+#### Rules the target never received
+
+`newRules` names a rule the toolkit authored after this target last synced
+governance. A sync refreshes the files a target already holds and adds none, so
+without this section a project's rule set freezes at its install date while every
+file it does hold reports as current. That is the report's most confident wrong
+answer, since a clean result reads as a target holding everything the toolkit
+publishes.
+
+The list rides beside `newSkills`, which asks the same question about the plugin
+catalog. Both are names rather than paths, and neither queues a change, because
+the two remedies differ: a skill loads live from the plugin directory and needs
+nothing run, while a rule reaches a target only when someone runs
+`aitk gov install`.
+
+Read a clean section as reporting rather than as delivering. Nothing here
+installs, nothing counts toward `--exit-code`, and a target can read the list and
+act on none of it. The value stops at an operator reading it, which is the same
+contract the skills list already sets.
+
+The measurement anchors on governance's own stamp rather than on the oldest
+anchor across domains, since rules are domain-scoped and a shared anchor would
+let a snippets sync move the revision rules are measured from. A target carrying
+no governance anchor reports nothing at all: it has no date to measure against,
+and diffing from the start of history would read the whole catalog as new.
+
+An anchor this toolkit cannot resolve reports nothing by the same route, and that
+one is not visible. A stamp naming a revision the running clone has never seen,
+which is what a registry install without history or a shallow clone produces,
+fails the read and yields an empty list rather than a stated absence. It looks
+identical to a target holding every rule the toolkit publishes. `newSkills`
+behaves the same way, and neither carries the `historyUnavailable` flag the
+per-domain scan uses to separate the two. Treat an empty section on a toolkit
+that is not a full clone as unmeasured rather than clean.
+
+Entitlement is filtered, because a stack does not receive every rule. The base
+stack takes the `core` and `claude` folders whole and every other stack extends
+it with individually named rules, so an unfiltered list would tell a base
+consumer about rules it can never receive and train the reader to skip the
+section.
+
+The filter accepts a band on either of two grounds. A folder the base stack takes
+whole is entitled to every target, read from the stack file so a folder added to
+base later needs no code change. Every other band is read off the folders the
+target already carries, since `aitk gov install` records file hashes and never
+the stack it resolved, which leaves the installed tree as the only evidence of
+what a chain reached. One band can be reached by more than one stack, so the test
+over-reports inside a folder the target holds, which costs a line where
+under-reporting would cost the section its point.
+
+A rule the target already holds is dropped by name. That is what keeps a rule the
+toolkit moved between band folders out of the list, since a rename reaches this
+read as an addition and only the name tells the two apart.
+
+This closes the dangling-citation case as a side effect rather than checking for
+one. The live instance is a rule citing a sibling authored after the target's
+install, and the section names the sibling as new rather than naming the citation
+as broken. That is enough for an operator to act on, and it is not a citation
+check.
+
 #### The reverse walk
 
 `reverse` is the one section built by walking the target rather than the
@@ -249,6 +312,11 @@ documented and unreachable from any report.
 is: only the user can move content they wrote, so failing a job on it leaves the
 job red with no mechanical remedy.
 
+`newRules` is excluded on a different ground, since a command does close it. What
+excludes it is that installing a rule changes what a project is governed by, so
+gating on the count would pressure a target into adopting rules nobody chose.
+`newSkills` is excluded because it needs no command at all.
+
 The whole `reverse` section is excluded on the same grounds, and more strongly.
 Every entry in it is a judgment about a file the project may own, and one of its
 three verdicts is a labelled unknown by design. The unmigrated detection shipped

package/docs/agents/label-coverage.md

@@ -0,0 +1,73 @@
+---
+title: Label coverage
+description: Reading a changed set against the pull request label map, the two tables it matches, how a gap is separated from a decision, and why an absent map is an answer
+---
+
+# Label coverage
+
+`aitk labels audit` resolves the paths a branch changed against the label map a project declares, reports the labels the set earns, and names every path no row reaches. It closes a gap the map's own comment had predicted since the map shipped: nothing detected a surface added after the rows were written, so such a branch merged carrying no label and nobody heard about it.
+
+```bash
+aitk labels audit
+aitk labels audit --json
+aitk labels audit --base origin/main
+aitk labels audit src/cli.ts docs/index.md --json
+```
+
+| Option          | Behavior                                                          |
+| --------------- | ----------------------------------------------------------------- |
+| `--base <ref>`  | Far side of the range, defaulting to the merge base against trunk |
+| `--root <path>` | Repository to read, defaulting to the current directory           |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame        |
+
+Positional paths replace the range entirely. A caller holding a changed set already passes it rather than paying for a second git read, and the record then omits `base` to say the range was never resolved.
+
+Under `--json` the record holds stdout alone and the frame still renders on stderr, refusals included, which is the split `output-shape.md` fixes for every mode.
+
+## The map it reads
+
+The map sits at `.claude/aitk/pr-labels.toml` and carries two tables. `[domains]` keys a label name to the path prefixes that earn it, and `[declined]` keys a reason to the prefixes that earn no label on purpose.
+
+```toml
+[domains]
+api = ["services/api/"]
+web = ["apps/web/", "packages/ui/"]
+
+[declined]
+release-managed = ["CHANGELOG.md", "package.json"]
+generated = ["build/manifest.json"]
+```
+
+Matching is prefix-anchored, so a row written for an authoring root reaches nothing under the copy a project consumes. A path claimed by rows in both tables takes the label, since it already has a subject and reporting it as deliberately unlabelled would contradict the label the same run applies.
+
+## A gap and a decision are different findings
+
+The verb sorts every changed path into three buckets and keeps two of them apart:
+
+- **Labelled.** At least one `[domains]` row reaches the path. It contributes its label and nothing else.
+- **Declined.** A `[declined]` row reaches it. Somebody already decided the path earns no label, so the run names it and moves no exit code.
+- **Uncovered.** Neither table reaches it. This is the finding, and it wants either a prefix on the row that owns its subject or a `[declined]` row carrying the reason.
+
+Folding the last two together was the shape this replaced. A report that cannot tell a surface nobody has gotten to from one somebody refused is useful about neither, which is why the declined half moved out of the map's trailing comment and became data the command reads.
+
+## The range it reads
+
+The default range is the branch against the trunk, resolved as the merge base against `origin/main` and then local `main`. The changed set is that base diffed against the working tree, plus untracked files git does not ignore, rather than against `HEAD`.
+
+Reading the working tree is what lets the check run before the branch commits, which is the moment a session adds the surface nobody covered. The set is a superset of `base..HEAD`, so a caller running after the commits still sees the whole branch.
+
+## Exit codes and refusals
+
+| Code | Meaning                                        |
+| ---- | ---------------------------------------------- |
+| `0`  | every changed path is labelled or declined     |
+| `1`  | refused, with `reason` naming the cause        |
+| `2`  | at least one changed path is reached by no row |
+
+It reports and never gates. Whether an uncovered surface deserves a label is a judgment only whoever owns that surface can make, and a push failing on one teaches a contributor to route around the check while nothing about the surface has changed.
+
+A project declaring no map refuses with `no-map`, which is an answer rather than a fault. Such a project is labelled silently by design, and treating the absence as a break would make the map mandatory for every target. `aitk audits run` reads that one reason as an expected absence and every other refusal as a measure that did not run.
+
+## What it does not measure
+
+A prefix reaching no path is invisible here. A row left behind by a deleted folder stays in the map forever, and this verb has nothing to say about it. That is the map going stale from the other side and a second measure rather than this one.

package/docs/target-projects.md

@@ -130,13 +130,25 @@ Each domain holds its own toolkit commit, so syncing governance today does not m
 
 A project that has never synced under a toolkit new enough to write a stamp falls back to the toolkit's own git history. Installed content matching any version that history published proves the file untouched, so it reports `stale` naming the commit it came from, and content matching no published version stays `drifted`. That fallback needs the toolkit as a git checkout. Installed from the registry it ships source without history, and the report says attribution was unavailable rather than reading every file as a local edit.
 
-Four further causes sit outside the per-domain scan, each naming something that walk cannot see. A seed the project edited is reported under `seeds` and reconciled with `aitk:claude-seed-sync`, since no sync command touches a seed. A file a newer seed folder replaced is reported under `superseded`, such as `.claude/TASKS.md` against the `.claude/tasks/` that now ships, and nothing moves it because the content is the project's own. A domain sitting at the root layout with nothing under `.claude/` is reported under `unmigrated` and handed to `aitk:migration-standards`.
+Further causes sit outside the per-domain scan, each naming something that walk cannot see. A seed the project edited is reported under `seeds` and reconciled with `aitk:claude-seed-sync`, since no sync command touches a seed. A file a newer seed folder replaced is reported under `superseded`, such as `.claude/TASKS.md` against the `.claude/tasks/` that now ships, and nothing moves it because the content is the project's own. A domain sitting at the root layout with nothing under `.claude/` is reported under `unmigrated` and handed to `aitk:migration-standards`.
 
 That third one matters most on an older project. Before it existed, a target holding `snippets/` at its root reported zero entries for that domain, so a project that had never migrated was indistinguishable from one that was fully current. It covers snippets alone, since a root `standards/` folder in a target is the project's own authoring surface and nothing proposes moving it.
 
+#### Rules you never received
+
+A sync refreshes the files you already hold and adds none, so your rule set is frozen at the date you installed governance while every file in it reports as current. `newRules` names the rules the toolkit has authored since then, which is the one section that reads your absence rather than your contents.
+
+Take a clean section as reporting rather than as delivering. Nothing here installs, and it counts toward nothing, so pick the rules up with `aitk gov install <stack>` or take one with `--add <rule>`. That separation is deliberate: adopting a rule changes what your project is governed by, which is a choice a sync has no business making for you.
+
+The list is filtered to what your stack can receive, read off the rule folders you already carry plus the folders the base stack takes whole. A rule under `lang/` or `ui/` belongs to some stacks and not others, so an unfiltered list would name rules you can never install. A target that has never stamped governance reports nothing at all, since there is no date to measure against.
+
+An empty section is not proof either way when the toolkit running the check is not a full git clone. The read needs history to reach your anchor, and an install from the registry ships none, so the section goes quiet rather than saying it could not measure. Run the check from a clone before reading a clean result as a complete one.
+
+This also closes the case where a rule arrives citing a sibling you do not have. A sync refreshing a rule can land a version pointing at a file it never installs, and the section names the missing sibling rather than the broken citation, which is enough to act on.
+
 #### What the toolkit stopped shipping
 
-The fourth cause runs backwards. Every one above starts from what the toolkit ships and asks whether the target matches, so a folder the toolkit dropped appears in none of them. `reverse` walks the target instead and reports a folder sitting at a top-level path the toolkit once shipped and has since deleted.
+The last cause runs backwards. Every one above starts from what the toolkit ships and asks whether the target matches, so a folder the toolkit dropped appears in none of them. `reverse` walks the target instead and reports a folder sitting at a top-level path the toolkit once shipped and has since deleted.
 
 Each entry carries a verdict, since a dropped folder and one the project wrote are the same bytes at the same path.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/audits/catalog.ts

@@ -1,5 +1,6 @@
 import type { ReachRefusal } from '@/claude/skills-reach'
 import type { AuditRefusal } from '@/deps/audit'
+import type { LabelAuditRefusal } from '@/labels/audit'
 import type { ValidateRefusal as RecordRefusal } from '@/records/validate'
 import type { ScanRefusal } from '@/secrets/scan'
 import type { ValidateRefusal as BoardRefusal } from '@/tasks/validate'
@@ -334,6 +335,27 @@ function advisoryCounts(record: unknown): Record<string, number> | undefined {
   return counts
 }
 
+/**
+ * Reads the uncovered paths alone, which is the half that is a finding.
+ *
+ * The declined paths are deliberately not counted. They are whichever declined
+ * rows this branch happened to touch rather than a measure of the map, so a
+ * clean trunk reads zero while the map declares eight, and the number would
+ * describe the branch rather than the decision.
+ *
+ * Retaining it also broke the verdict. `classify` reads a clean run as quiet
+ * only when every count is zero, so a branch touching one declined path exited
+ * 0 and still reported as carrying findings.
+ */
+function labelCoverageCounts(
+  record: unknown,
+): Record<string, number> | undefined {
+  const root = asObject(record)
+  if (root === undefined) return undefined
+
+  return allOf({ uncovered: lengthOf(root.uncovered) })
+}
+
 function findingsOnly(record: unknown): Record<string, number> | undefined {
   const root = asObject(record)
   if (root === undefined) return undefined
@@ -499,6 +521,33 @@ export const AUDITS: readonly AuditSpec[] = [
     ] satisfies ScanRefusal[],
     counts: findingsOnly,
   },
+  {
+    id: 'labels',
+    label: 'Pull request label coverage',
+    argv: ['labels', 'audit', '--json'],
+    // Reports rather than gates, on the split this file already draws. Whether
+    // an uncovered surface deserves a label is a judgment, and a push failing
+    // on one would ask a contributor to answer a question only the person who
+    // owns the surface can.
+    gatingExits: [],
+    // The map is committed, so every clone reads the same rows and a delta is
+    // shared. The changed set the rows are read against is the branch's, which
+    // is what makes a clean trunk report zero rather than nothing.
+    corpus: 'tracked',
+    // Only `uncovered` is retained, for the reason its extractor states.
+    //
+    // The one reason that means this project declares no surfaces to cover,
+    // which is the recorded decision that a project without a map is labelled
+    // silently. A tracked corpus normally allows nothing absent, and this is
+    // the second exception beside the secret scan rather than a default.
+    //
+    // The other three are deliberately left out. A map that will not parse, a
+    // map with no usable row, and a range git could not answer are each a
+    // corpus that exists and went unread, so calling any of them an absence
+    // would report a pass over a branch nobody measured.
+    absentReasons: ['no-map'] satisfies LabelAuditRefusal[],
+    counts: labelCoverageCounts,
+  },
   {
     id: 'deps',
     label: 'Dependency advisories',

package/src/cli.ts

@@ -28,6 +28,7 @@ import { register as sessions } from '@/commands/sessions'
 import { register as audits } from '@/commands/audits'
 import { register as secrets } from '@/commands/secrets'
 import { register as deps } from '@/commands/deps'
+import { register as labels } from '@/commands/labels'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { palette } from '@/ui'
@@ -67,6 +68,7 @@ function showHelp(): void {
     `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
     `${GREY}│${NC}    secrets [cmd]      ${GREY}# Read the shipped tree for credential-shaped values (scan)${NC}`,
     `${GREY}│${NC}    deps [cmd]         ${GREY}# Read the resolved dependency set for advisories (audit)${NC}`,
+    `${GREY}│${NC}    labels [cmd]       ${GREY}# Read a changed set against the pull request label map (audit)${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
     `${GREY}│${NC}    upgrade            ${GREY}# Reinstall the CLI globally with the manager that installed it${NC}`,
     `${GREY}│${NC}`,
@@ -110,6 +112,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk sessions list --json`,
     `${GREY}│${NC}    aitk secrets scan --json`,
     `${GREY}│${NC}    aitk deps audit --json`,
+    `${GREY}│${NC}    aitk labels audit --json`,
     `${GREY}│${NC}    aitk audits run --json`,
     `${GREY}│${NC}    aitk upgrade --json`,
     `${GREY}└${NC}`,
@@ -156,6 +159,7 @@ records(program)
 sessions(program)
 secrets(program)
 deps(program)
+labels(program)
 audits(program)
 upgrade(program)
 

package/src/commands/labels.ts

@@ -0,0 +1,166 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { type LabelAuditRefusal, auditLabels } from '@/labels/audit'
+import { MAP_REL } from '@/labels/map'
+import { intro, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+
+interface AuditOptions {
+  readonly base?: string
+  readonly root?: string
+  readonly json?: boolean
+}
+
+/** What a reader does about each way the audit produced no reading. */
+const REFUSALS: Record<LabelAuditRefusal, string> = {
+  // An answer rather than a fault. A project declaring no map is labelled
+  // silently by design, so a refusal reading as a break would make the map
+  // mandatory for every target.
+  'no-map': `No ${MAP_REL} here, so this project labels nothing and declares no surfaces to cover.`,
+  'unreadable-map': `${MAP_REL} is not valid TOML, so no row could be read.`,
+  'no-domains': `${MAP_REL} carries no usable row under [domains], so every path would read as uncovered.`,
+  'no-base': 'No base resolves against the trunk. Fetch origin or pass --base.',
+  'bad-base':
+    'The ref passed to --base resolves to no commit here. Pass one this tree carries.',
+  'unreadable-changes':
+    'git could not list what this branch changed, so the set is unknown.',
+}
+
+export function register(program: Command): void {
+  const labels = program
+    .command('labels')
+    .description('Resolve a changed set against the pull request label map')
+    .helpOption('-h, --help', 'Show this help message')
+
+  labels
+    .command('audit')
+    .description(
+      'Report the labels a changed set earns and the paths no row reaches',
+    )
+    .argument(
+      '[paths...]',
+      'Changed set to read, defaulting to the branch range',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--base <ref>', 'Far side of the range, defaulting to the trunk')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Reads ${MAP_REL} and matches it prefix-anchored, which is the rule the`,
+        "map's own census was measured against. It reports and never gates,",
+        'because whether an uncovered surface deserves a label is a judgment.',
+        '',
+        'What it separates:',
+        '  uncovered  a surface no row reaches, which is a gap wanting a row',
+        '  declined   a path a [declined] row names, which is a decision already taken',
+        '',
+        'What it does not measure:',
+        '  a prefix reaching no path, which is the map going stale from the other',
+        '  side and a second measure rather than this one',
+        '',
+        'Exit codes:',
+        '  0  every changed path is labelled or declined',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  at least one changed path is reached by no row',
+        '',
+        'Examples:',
+        '  aitk labels audit',
+        '  aitk labels audit --json',
+        '  aitk labels audit --base origin/main',
+        '  aitk labels audit src/cli.ts docs/index.md --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (paths: string[], opts: AuditOptions) => {
+      process.exitCode = await runAudit(paths, opts)
+    })
+}
+
+async function runAudit(paths: string[], opts: AuditOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  const report = await auditLabels(root, {
+    base: opts.base,
+    ...(paths.length > 0 && { paths }),
+  })
+
+  intro('aitk labels audit')
+
+  // The frame renders on stderr in both modes and the record goes to stdout
+  // alone, so an operator reading the terminal sees the refusal rather than a
+  // command that appeared to do nothing.
+  if (report.kind === 'refused') {
+    logStep('Refused')
+    logWarn(REFUSALS[report.reason])
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: report.reason,
+          message: REFUSALS[report.reason],
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
+  const { coverage } = report
+
+  logStep('Scope')
+  logInfo(
+    report.base === undefined
+      ? `${plural(report.changed.length, 'path')} supplied by the caller`
+      : `${plural(report.changed.length, 'path')} changed since ${report.base.slice(0, 8)}`,
+  )
+
+  logStep('Labels')
+  logInfo(
+    coverage.labels.length === 0
+      ? 'this set earns no label'
+      : coverage.labels.join(', '),
+  )
+
+  // Named rather than counted into the uncovered line. A path somebody decided
+  // against wants nothing done, and folding it in would ask for a row that was
+  // already refused.
+  logStep('Declined')
+  if (coverage.declined.length === 0) {
+    logInfo('no changed path is deliberately unlabelled')
+  } else {
+    for (const entry of coverage.declined) {
+      logInfo(`${entry.path}: ${entry.reason}`)
+    }
+  }
+
+  logStep(coverage.uncovered.length === 0 ? 'Covered' : 'Uncovered')
+  if (coverage.uncovered.length === 0) {
+    logInfo('every changed path is reached by a row')
+  } else {
+    logWarn(
+      `${plural(coverage.uncovered.length, 'path')} reached by no row. Give each a prefix on the row that owns its subject, or a [declined] row with the reason it earns none.`,
+    )
+    for (const path of coverage.uncovered) logWarn(path)
+  }
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        ...(report.base !== undefined && { base: report.base }),
+        changed: report.changed,
+        labels: coverage.labels,
+        declined: coverage.declined,
+        uncovered: coverage.uncovered,
+      })}\n`,
+    )
+  }
+
+  return coverage.uncovered.length === 0 ? 0 : 2
+}

package/src/commands/sync.ts

@@ -162,6 +162,19 @@ function renderCheck(report: CheckReport): void {
     for (const name of report.newSkills) logInfo(name)
   }
 
+  // Warned where `newSkills` is noted, because a new skill loads live and needs
+  // nothing run while a rule reaches the target only when someone installs it.
+  // No sync closes any of this, so the remedy names the install command.
+  if (report.newRules.length > 0) {
+    logStep('New rules, never installed')
+    for (const name of report.newRules) logWarn(name)
+    // Names the stack as the reader's to supply, since no target records one
+    // and `--add` layers onto a resolved stack rather than standing in for it.
+    logInfo(
+      'Run `aitk gov install <stack>`, naming the stack yourself since no target records it. Add `--add <rule>` to take one.',
+    )
+  }
+
   renderUnclaimed(report)
   renderMigrations(report)
 

package/src/git-files.ts

@@ -1,6 +1,80 @@
 import { $ } from 'bun'
 import { gitEnv } from '@/git-env'
 
+/**
+ * Preferred first, matching `src/gov/test-order.ts` and `src/tasks/trunk.ts`. A
+ * local `main` trailing the remote pulls other people's merged commits into the
+ * range, so a check reading it decides against files the branch never touched.
+ */
+const TRUNK_REFS = ['origin/main', 'main'] as const
+
+/** Runs git under `root` with the resolution variables a hook exports stripped. */
+async function git(
+  root: string,
+  args: readonly string[],
+): Promise<string | undefined> {
+  const result = await $`git -C ${root} ${args}`.env(gitEnv()).quiet().nothrow()
+  return result.exitCode === 0 ? result.text().trimEnd() : undefined
+}
+
+/**
+ * The far side of a branch range: the ref a caller named, or the merge base
+ * against the first trunk this repository carries.
+ *
+ * A named ref that resolves to nothing refuses rather than falling back, since
+ * measuring the trunk range instead would answer a question nobody asked.
+ */
+export async function resolveBaseRef(
+  root: string,
+  ref?: string,
+): Promise<string | undefined> {
+  if (ref !== undefined) {
+    const resolved = await git(root, [
+      'rev-parse',
+      '--verify',
+      '--quiet',
+      `${ref}^{commit}`,
+    ])
+    return resolved === undefined || resolved === '' ? undefined : resolved
+  }
+
+  for (const trunk of TRUNK_REFS) {
+    const merged = await git(root, ['merge-base', 'HEAD', trunk])
+    if (merged !== undefined && merged !== '') return merged
+  }
+
+  return undefined
+}
+
+/**
+ * Every path a branch has touched since `base`: the diff against the working
+ * tree, plus untracked files git does not ignore.
+ *
+ * The working tree rather than `HEAD` on purpose. A check that runs before the
+ * branch is committed has to see the surface a session just added, and reading
+ * `HEAD` there returns a set the working tree has already moved past. Since the
+ * range is a superset of `base..HEAD`, a caller running after the commits still
+ * gets the whole branch.
+ *
+ * Returns undefined when git cannot answer, for the reason
+ * `listRepositoryFiles` states: an empty list reads as a clean branch.
+ */
+export async function listChangedFiles(
+  root: string,
+  base: string,
+): Promise<string[] | undefined> {
+  const changed = await git(root, ['diff', '--name-only', base])
+  const untracked = await git(root, [
+    'ls-files',
+    '--others',
+    '--exclude-standard',
+  ])
+  if (changed === undefined || untracked === undefined) return undefined
+
+  const paths = [...changed.split('\n'), ...untracked.split('\n')]
+  return [...new Set(paths.filter(Boolean))].sort()
+}
+
 /**
  * Lists the files under `root`: tracked, plus untracked files git does not
  * ignore. The untracked half is what keeps a file added on this branch in scope

package/src/labels/audit.ts

@@ -0,0 +1,82 @@
+import { listChangedFiles, resolveBaseRef } from '@/git-files'
+import { type Coverage, resolveCoverage } from '@/labels/coverage'
+import { type MapRefusal, readLabelMap } from '@/labels/map'
+
+/**
+ * Why an audit produced no reading.
+ *
+ * `no-map` travels through from the map reader and stays an answer rather than
+ * a fault. The git reasons are the opposite: a range this check asked for and
+ * could not get, which is a broken invocation rather than a project that
+ * declared nothing.
+ *
+ * A named ref that will not resolve is its own reason. Folding it into
+ * `no-base` sends the caller who already passed `--base` a message telling
+ * them to pass `--base`.
+ */
+export type LabelAuditRefusal =
+  | MapRefusal
+  | 'no-base'
+  | 'bad-base'
+  | 'unreadable-changes'
+
+export type LabelAudit =
+  | {
+      readonly kind: 'measured'
+      /** Absent when the caller supplied the changed set rather than a range. */
+      readonly base?: string
+      readonly changed: readonly string[]
+      readonly coverage: Coverage
+    }
+  | { readonly kind: 'refused'; readonly reason: LabelAuditRefusal }
+
+export interface LabelAuditOptions {
+  /** Far side of the range, defaulting to the merge base against the trunk. */
+  readonly base?: string
+  /** A changed set the caller already holds, which skips git entirely. */
+  readonly paths?: readonly string[]
+}
+
+/**
+ * Resolves a changed set against the map a project declares, and reports both
+ * what it earns and what it leaves uncovered.
+ *
+ * One verb for two readers by design. `git-pr` reads the labels at open time
+ * and the audit aggregate reads the uncovered count, and a verb shaped for the
+ * first alone returns nothing the second can retain.
+ */
+export async function auditLabels(
+  root: string,
+  options: LabelAuditOptions = {},
+): Promise<LabelAudit> {
+  const map = readLabelMap(root)
+  if (map.kind === 'refused') return { kind: 'refused', reason: map.reason }
+
+  if (options.paths !== undefined) {
+    return {
+      kind: 'measured',
+      changed: [...options.paths],
+      coverage: resolveCoverage(map, options.paths),
+    }
+  }
+
+  const base = await resolveBaseRef(root, options.base)
+  if (base === undefined) {
+    return {
+      kind: 'refused',
+      reason: options.base === undefined ? 'no-base' : 'bad-base',
+    }
+  }
+
+  const changed = await listChangedFiles(root, base)
+  if (changed === undefined) {
+    return { kind: 'refused', reason: 'unreadable-changes' }
+  }
+
+  return {
+    kind: 'measured',
+    base,
+    changed,
+    coverage: resolveCoverage(map, changed),
+  }
+}

package/src/labels/coverage.ts

@@ -0,0 +1,79 @@
+import type { LabelMap } from '@/labels/map'
+
+/** A path a row leaves unlabelled on purpose, carrying the reason it gives. */
+export interface DeclinedPath {
+  readonly path: string
+  readonly reason: string
+}
+
+export interface Coverage {
+  /** Distinct labels the whole set earns, ordered as the map declares them. */
+  readonly labels: readonly string[]
+  /**
+   * Paths a `[declined]` row covers, which are a decision rather than a gap.
+   *
+   * Kept apart from `uncovered` because the response to the two differs. A
+   * surface nobody has gotten to wants a row, and one somebody decided against
+   * wants nothing, so a report folding them together is useful about neither.
+   */
+  readonly declined: readonly DeclinedPath[]
+  /** Paths no row of either table reaches, which is the finding. */
+  readonly uncovered: readonly string[]
+}
+
+/**
+ * Prefix-anchored, matching what the map's own comment describes and what the
+ * census behind its 41 prefixes was measured against.
+ *
+ * A glob would reach every existing prefix and invalidate that measurement, so
+ * the rule stays a `startsWith` even where a glob would read more naturally.
+ */
+function matches(path: string, prefixes: readonly string[]): boolean {
+  return prefixes.some((prefix) => path.startsWith(prefix))
+}
+
+/**
+ * Resolves what a changed set earns from a map, and what it leaves behind.
+ *
+ * One pass answers both readers. `git-pr` wants the labels to apply, and the
+ * audit wants the paths that earned none, and a function shaped for the first
+ * alone returns nothing the second can count.
+ */
+export function resolveCoverage(
+  map: Extract<LabelMap, { kind: 'map' }>,
+  paths: readonly string[],
+): Coverage {
+  const earned = new Set<string>()
+  const declined: DeclinedPath[] = []
+  const uncovered: string[] = []
+
+  for (const path of paths) {
+    const labels = map.domains.filter((row) => matches(path, row.prefixes))
+
+    // A label wins over a decline. A path both tables claim already carries a
+    // subject, so reporting it as deliberately unlabelled would contradict the
+    // label the same run is about to apply.
+    if (labels.length > 0) {
+      for (const row of labels) earned.add(row.label)
+      continue
+    }
+
+    const row = map.declined.find((entry) => matches(path, entry.prefixes))
+    if (row !== undefined) {
+      declined.push({ path, reason: row.reason })
+      continue
+    }
+
+    uncovered.push(path)
+  }
+
+  return {
+    // Read back off the map rather than out of the set, so two runs over one
+    // branch produce one order and one string.
+    labels: map.domains
+      .map((row) => row.label)
+      .filter((label) => earned.has(label)),
+    declined,
+    uncovered,
+  }
+}

package/src/labels/map.ts

@@ -0,0 +1,101 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Where a project declares its pull request label map, spelled once.
+ *
+ * The file has already moved once, and that relocation rewrote every mention
+ * across four surfaces. Nothing in code spells it anywhere else, so the next
+ * move is one edit here rather than a sweep.
+ */
+export const MAP_REL = join('.claude', 'aitk', 'pr-labels.toml')
+
+/** A label name and the path prefixes that earn it, in the map's own order. */
+export interface DomainRow {
+  readonly label: string
+  readonly prefixes: readonly string[]
+}
+
+/** A reason a path is deliberately unlabelled, and the prefixes it covers. */
+export interface DeclinedRow {
+  readonly reason: string
+  readonly prefixes: readonly string[]
+}
+
+/**
+ * Why a map could not be read, which is never the same as a map with no rows.
+ *
+ * `no-map` is an answer rather than a fault. A project declaring no map is
+ * labelled silently by design, so a refusal read as a break would make the map
+ * mandatory for every target, which that decision declined. The other two are
+ * a file that exists and cannot be used, which is a defect in the map itself.
+ */
+export type MapRefusal = 'no-map' | 'unreadable-map' | 'no-domains'
+
+export type LabelMap =
+  | {
+      readonly kind: 'map'
+      readonly domains: readonly DomainRow[]
+      readonly declined: readonly DeclinedRow[]
+    }
+  | { readonly kind: 'refused'; readonly reason: MapRefusal }
+
+/**
+ * Reads a TOML table of string arrays into rows, dropping any key whose value
+ * carries no usable prefix.
+ *
+ * A malformed row is skipped rather than refused, because both tables are
+ * authored by hand and one bad entry should not blind the check to the other
+ * forty. What it costs is that a typo reads as a row nobody wrote, which the
+ * uncovered report surfaces from the other side.
+ */
+function readRows(table: unknown): { key: string; prefixes: string[] }[] {
+  if (typeof table !== 'object' || table === null || Array.isArray(table)) {
+    return []
+  }
+
+  const rows: { key: string; prefixes: string[] }[] = []
+  for (const [key, value] of Object.entries(table)) {
+    if (!Array.isArray(value)) continue
+    const prefixes = value.filter(
+      (entry): entry is string => typeof entry === 'string' && entry !== '',
+    )
+    if (prefixes.length > 0) rows.push({ key, prefixes })
+  }
+
+  return rows
+}
+
+/** Parses map text, so a caller holding the bytes skips the filesystem. */
+export function parseLabelMap(source: string): LabelMap {
+  let parsed: Record<string, unknown>
+  try {
+    parsed = Bun.TOML.parse(source) as Record<string, unknown>
+  } catch {
+    return { kind: 'refused', reason: 'unreadable-map' }
+  }
+
+  const domains = readRows(parsed.domains)
+  if (domains.length === 0) return { kind: 'refused', reason: 'no-domains' }
+
+  return {
+    kind: 'map',
+    domains: domains.map(({ key, prefixes }) => ({ label: key, prefixes })),
+    declined: readRows(parsed.declined).map(({ key, prefixes }) => ({
+      reason: key,
+      prefixes,
+    })),
+  }
+}
+
+/** Reads the map a project declares at `root`, or says why it could not. */
+export function readLabelMap(root: string): LabelMap {
+  let source: string
+  try {
+    source = readFileSync(join(root, MAP_REL), 'utf8')
+  } catch {
+    return { kind: 'refused', reason: 'no-map' }
+  }
+
+  return parseLabelMap(source)
+}

package/src/sync/check.ts

@@ -1,7 +1,9 @@
 import { existsSync } from 'node:fs'
-import { join } from 'node:path'
+import { basename, join, sep } from 'node:path'
 import { execa } from 'execa'
-import { createGovAdapter } from '@/gov/adapter'
+import { gitEnv } from '@/git-env'
+import { createGovAdapter, rulesSourceDir } from '@/gov/adapter'
+import { loadGovStack } from '@/gov/stacks'
 import { createSnippetsAdapter } from '@/snippets/adapter'
 import { planSync, type ScanEntry, type SyncAdapter } from '@/sync/engine'
 import {
@@ -154,6 +156,13 @@ export interface CheckReport {
   readonly superseded: readonly SupersededEntry[]
   readonly unmigrated: readonly UnmigratedDomain[]
   readonly newSkills: readonly string[]
+  /**
+   * Rules the toolkit authored after this target's governance anchor, filtered
+   * to what the target could receive. It rides beside `newSkills` rather than
+   * folding into it because the two answer the same question about different
+   * corpora and a reader acting on one runs a different command from the other.
+   */
+  readonly newRules: readonly string[]
   /**
    * The one section built by walking the target rather than the catalog. It
    * reports beside `superseded`, `unmigrated`, and `newSkills` rather than
@@ -336,6 +345,7 @@ export async function buildCheckReport(
       superseded: [],
       unmigrated: [],
       newSkills: [],
+      newRules: [],
       reverse: emptyReverseReport(),
       skew: await skewRead,
     }
@@ -350,6 +360,11 @@ export async function buildCheckReport(
     superseded: collectSuperseded(target),
     unmigrated,
     newSkills: await readNewSkills(toolkitRoot, anchors),
+    newRules: await readNewRules(
+      toolkitRoot,
+      target,
+      stampedCommit(stamp, 'governance'),
+    ),
     reverse: buildReverseReport(toolkitRoot, target),
     skew: await skewRead,
   }
@@ -411,6 +426,145 @@ export function parseNewSkills(paths: string): string[] {
   return [...new Set(names)].sort()
 }
 
+/**
+ * What the target's `.claude/rules/` proves about its entitlement. `held` is
+ * every rule name it carries and `bands` every band folder those names sit in.
+ *
+ * Read off the installed tree rather than off a stack name, because
+ * `gov install` records file hashes and never the stack it resolved, so the
+ * chain a target consumed survives nowhere else. `installRules` copies each
+ * rule into the subdirectory it was authored in, which is what makes the band
+ * folders legible as evidence.
+ */
+export function readInstalledRules(target: string): {
+  held: Set<string>
+  bands: Set<string>
+} {
+  const dir = join(target, ...INSTALL_MARKERS.governance)
+  const held = new Set<string>()
+  const bands = new Set<string>()
+  if (!isDirectory(dir)) return { held, bands }
+
+  for (const rel of new Bun.Glob('**/*.md').scanSync({
+    cwd: dir,
+    onlyFiles: true,
+    dot: true,
+  })) {
+    const posix = rel.split(sep).join('/')
+    const boundary = posix.indexOf('/')
+
+    held.add(basename(posix, '.md'))
+    if (boundary > 0) bands.add(posix.slice(0, boundary))
+  }
+
+  return { held, bands }
+}
+
+/**
+ * Narrows rules added upstream to the ones this target could receive and does
+ * not already hold.
+ *
+ * The band test is the entitlement filter, and `bands` carries two sources: the
+ * folders the target already holds, and the folders the base stack takes whole.
+ * A rule authored under `lang/` or `ui/` is named by an individual stack, so it
+ * belongs to some targets and not others, and listing every added file would
+ * tell a base consumer about rules it was never entitled to. The test
+ * over-reports inside a band a target already carries, since one folder can be
+ * reached by more than one stack, and that costs a line where under-reporting
+ * would cost the whole point of the section.
+ *
+ * The `held` test is what keeps a rule that moved bands upstream out. A rename
+ * reaches this diff as an addition, and the target already has the file under
+ * its old folder, so matching by name is what tells the two apart.
+ */
+export function selectNewRules(
+  paths: string,
+  held: ReadonlySet<string>,
+  bands: ReadonlySet<string>,
+): string[] {
+  const prefix = 'governance/rules/'
+  const names = new Set<string>()
+
+  for (const line of paths.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith(prefix) || !trimmed.endsWith('.md')) continue
+
+    const rel = trimmed.slice(prefix.length)
+    const boundary = rel.indexOf('/')
+    const band = boundary === -1 ? '' : rel.slice(0, boundary)
+    const name = basename(rel, '.md')
+
+    if (held.has(name)) continue
+    if (band !== '' && !bands.has(band)) continue
+
+    names.add(name)
+  }
+
+  return [...names].sort()
+}
+
+/**
+ * Band folders the base stack takes whole. Every governance stack extends base,
+ * so a rule authored under one of these is entitled to every target.
+ *
+ * This is what covers a band no target can carry yet. Entitlement is otherwise
+ * read off folders the target already holds, and a folder added to base later
+ * exists in no installed tree, so without this the rules inside it would reach
+ * nobody. Read from the stack file rather than fixed, so that addition needs no
+ * code change here.
+ *
+ * A folder only a leaf stack names is deliberately absent. It is entitled to
+ * some targets and not others, which is the distinction the band test makes and
+ * the installed tree is the only evidence of.
+ */
+export function baseBands(root: string): Set<string> {
+  const stack = loadGovStack(root, 'base')
+  if (stack === undefined) return new Set()
+
+  return new Set(
+    stack.rules.filter((entry) =>
+      isDirectory(join(rulesSourceDir(root), entry)),
+    ),
+  )
+}
+
+/**
+ * Rules are domain-scoped, so this measures from governance's own anchor rather
+ * than from the oldest anchor across domains the way `readNewSkills` does. A
+ * shared anchor would let a snippets sync move the revision rules are measured
+ * from and drop a rule out of the read.
+ *
+ * A target carrying no governance anchor reports nothing. It has no date to
+ * measure against, and diffing from the beginning of history would read every
+ * rule the toolkit ships as new.
+ *
+ * An anchor this clone cannot resolve reports nothing by a different route and
+ * says so nowhere. `read` yields an empty string on a non-zero exit, so a stamp
+ * naming a revision a registry install or a shallow clone has never seen reads
+ * as a target holding everything. `readNewSkills` carries the same gap, and
+ * neither has the `historyUnavailable` flag the per-domain scan uses to tell an
+ * unmeasured result from a clean one.
+ */
+export async function readNewRules(
+  root: string,
+  target: string,
+  since: string | undefined,
+): Promise<string[]> {
+  if (since === undefined) return []
+
+  const paths = await read(root, [
+    'diff',
+    '--name-only',
+    '--diff-filter=A',
+    `${since}..HEAD`,
+    '--',
+    'governance/rules/',
+  ])
+
+  const { held, bands } = readInstalledRules(target)
+  return selectNewRules(paths, held, bands.union(baseBands(root)))
+}
+
 async function readUpstream(
   root: string,
   since: string,
@@ -474,7 +628,7 @@ async function isAncestor(
   const result = await execa(
     'git',
     ['-C', root, 'merge-base', '--is-ancestor', candidate, reference],
-    { reject: false },
+    { reject: false, env: gitEnv(), extendEnv: false },
   )
 
   return result.exitCode === 0
@@ -483,9 +637,18 @@ async function isAncestor(
 /**
  * A toolkit outside a git clone, or a stamped revision this clone has never
  * seen, yields no range. The per-file report still stands on its own.
+ *
+ * Scrubbed through `gitEnv` because a git hook exports `GIT_DIR` and its
+ * siblings into every process it runs and they outrank `-C`. A check invoked
+ * from a hook would otherwise diff the hook's repository and report a range for
+ * a tree nobody asked about, which reads as an ordinary answer.
  */
 async function read(root: string, args: readonly string[]): Promise<string> {
-  const result = await execa('git', ['-C', root, ...args], { reject: false })
+  const result = await execa('git', ['-C', root, ...args], {
+    reject: false,
+    env: gitEnv(),
+    extendEnv: false,
+  })
   return result.exitCode === 0 ? result.stdout : ''
 }