@erclx/aitk 3.0.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.0.0",
+  "version": "3.2.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-design-extract/SKILL.md

@@ -35,7 +35,7 @@ Read these on both paths, skipping any that do not exist:
 - `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: word, punctuation, and formatting constraints
 - The `write-human` skill: tone and sentence construction constraints
 
-On the source path, also read the UI surfaces matched in Step 1 plus `docs/agents/output-shape.md` and `docs/index.md` for output shape or framing rules already documented.
+On the source path, also read the UI surfaces matched in Step 1 plus any `docs/agents/output-shape.md` and `docs/index.md` the project itself carries, for output shape or framing rules already documented. Those two are the toolkit's own spelling, so a project keeping its framing rules elsewhere is read there instead.
 
 On the greenfield path, also read `.claude/ARCHITECTURE.md` for platform, tech stack, and surface type. Do not scan `src/`, stylesheets, or UI modules. Step 1 already established they hold nothing.
 

package/claude/skills/claude-intake-answer/REQUIREMENT.md

@@ -43,6 +43,6 @@ The batching fails a fifth way. A folder holding thirty unread items put as thir
 
 - Filing a dump and writing the items, which is `claude-intake` and owns every other write into the folder
 - Promoting an answered item onto the board, which is `claude-tasks` and runs after the answers land
-- The item format, the answer contract, and retrieval, which `standards/intake.md` owns and this skill cites
+- The item format, the answer contract, and retrieval, which the toolkit's `standards/intake.md` owns and this skill cites
 - The comparable answer slots in groundwork and feature plans, which carry their own contracts and are a separate measurement
 - Deciding when to fire. The skill is user-invoked through `disable-model-invocation`, so answering is the operator's call rather than a description match.

package/claude/skills/decision-escalate/REQUIREMENT.md

@@ -15,7 +15,7 @@ A body written around a named tool fails a third way. A session on a surface car
 
 The opposite failure is the one that ships silently. A session that takes a preference decision itself produces work the operator did not ask for and never learns a choice was made, because nothing in the output says a fork was passed.
 
-`CLAUDE.md` states both branches of the rule, sending an ordinary judgment call to a pick with the tradeoff in one sentence and a preference-deciding call to the operator. The first branch has `snippets/decision-help.md` behind it and the second had no surface at all.
+`CLAUDE.md` states both branches of the rule, sending an ordinary judgment call to a pick with the tradeoff in one sentence and a preference-deciding call to the operator. The first branch has the toolkit's `snippets/decision-help.md` behind it, which installs into a project as `.claude/snippets/decision-help.md`, and the second had no surface at all.
 
 ## Must
 
@@ -40,6 +40,6 @@ The opposite failure is the one that ships silently. A session that takes a pref
 ## Out of scope
 
 - Making the ordinary judgment call, which is a pick plus a one-sentence tradeoff and needs no surface
-- The chat-side pick with no repository behind it, which `snippets/decision-help.md` covers and reaches a different reader
+- The chat-side pick with no repository behind it, which the toolkit's `snippets/decision-help.md` covers and reaches a different reader
 - Writing the decision into a plan, task, or architecture record, which each owning standard governs and this skill only routes to
 - Deciding when to fire. The skill is user-invoked through `disable-model-invocation`, so escalating is the operator's call rather than a description match.

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/claude/skills/setup-indexes/SKILL.md

@@ -111,7 +111,7 @@ grep -l '^## Indexes' CLAUDE.md 2>/dev/null
 
 If the section is present, skip the seed silently.
 
-If `CLAUDE.md` exists but has no `## Indexes` section, offer to install the canonical convention block. The text below is the source of truth and is mirrored in `tooling/claude/seeds/CLAUDE.md`. Paste it verbatim. Do not rewrite, paraphrase, condense, or add punctuation.
+If `CLAUDE.md` exists but has no `## Indexes` section, offer to install the canonical convention block. The text below is the source of truth and is mirrored in the toolkit's `tooling/claude/seeds/CLAUDE.md`. Paste it verbatim. Do not rewrite, paraphrase, condense, or add punctuation.
 
 ```markdown
 - When a folder has an `index.md`, check it before reading individual files in that folder.
@@ -147,5 +147,7 @@ Replace bracketed values with the values from this run. Drop the "Folders bootst
 
 ## Reference
 
-- `.claude/context/indexes.md`: system rationale, frontmatter contract, when to adopt
-- `docs/agents/indexes.md`: `aitk indexes regen` flags, exit codes, JSON shape
+Both pages sit in the toolkit and install nowhere, so a target reads them there rather than in its own tree.
+
+- The toolkit's `.claude/context/indexes.md`: system rationale, frontmatter contract, when to adopt
+- The toolkit's `docs/agents/indexes.md`: `aitk indexes regen` flags, exit codes, JSON shape

package/claude/skills/youtube-transcripts/SKILL.md

@@ -5,7 +5,7 @@ description: Fetches a YouTube video transcript with metadata frontmatter into t
 
 # YouTube transcripts
 
-Turn a pasted YouTube URL into a markdown file with YAML frontmatter and a cleaned prose body. The `aitk transcripts` command owns the fetch, VTT cleanup, and frontmatter. Do not reimplement that logic. See `.claude/context/transcripts.md` for the output format and field list.
+Turn a pasted YouTube URL into a markdown file with YAML frontmatter and a cleaned prose body. The `aitk transcripts` command owns the fetch, VTT cleanup, and frontmatter. Do not reimplement that logic. The output format and field list live in the toolkit's `.claude/context/transcripts.md`, which a target does not receive.
 
 ## Guards
 

package/docs/agents/audits.md

@@ -22,11 +22,11 @@ aitk audits list --json
 
 ## What it runs
 
-Fourteen 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.
 
-Twelve of the fourteen 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

@@ -46,9 +46,11 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk markdown audit`      | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                         |
 | `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                                 |
 | `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`)      |
+| `aitk claude skills reach` | Report the shipped bodies citing a toolkit path no target project receives, exiting 2 on an unqualified one                                    |
 | `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                                                          |
@@ -58,25 +60,26 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 
 Each domain exposes a consistent shape where applicable: `list`, `install`, `sync`, `create`.
 
-| Domain      | Subcommands                                                                                 |
-| ----------- | ------------------------------------------------------------------------------------------- |
-| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                      |
-| `snippets`  | `list`, `install`, `sync`, `create`                                                         |
-| `standards` | `list`, `<name>`                                                                            |
-| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`                                   |
-| `claude`    | `init`, `sync`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `setup [dest]` |
-| `wiki`      | `init`                                                                                      |
-| `design`    | `render`                                                                                    |
-| `slides`    | `render`, `list`                                                                            |
-| `tasks`     | `archive`, `validate`                                                                       |
-| `intake`    | `list`, `answer`                                                                            |
-| `teach`     | `list`, `open`, `resource`, `glossary`                                                      |
-| `comments`  | `scan`                                                                                      |
-| `context`   | `audit`                                                                                     |
-| `markdown`  | `audit`                                                                                     |
-| `secrets`   | `scan`                                                                                      |
-| `deps`      | `audit`                                                                                     |
-| `audits`    | `run`, `list`                                                                               |
+| Domain      | Subcommands                                                                                                 |
+| ----------- | ----------------------------------------------------------------------------------------------------------- |
+| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                                      |
+| `snippets`  | `list`, `install`, `sync`, `create`                                                                         |
+| `standards` | `list`, `<name>`                                                                                            |
+| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`                                                   |
+| `claude`    | `init`, `sync`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `setup [dest]` |
+| `wiki`      | `init`                                                                                                      |
+| `design`    | `render`                                                                                                    |
+| `slides`    | `render`, `list`                                                                                            |
+| `tasks`     | `archive`, `validate`                                                                                       |
+| `intake`    | `list`, `answer`                                                                                            |
+| `teach`     | `list`, `open`, `resource`, `glossary`                                                                      |
+| `comments`  | `scan`                                                                                                      |
+| `context`   | `audit`                                                                                                     |
+| `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
@@ -26,6 +27,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, the liveness confidence field, the unresolved reasons, and what the read depends on
 - [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
+- [Citation reach](skills-reach.md): Reporting the shipped skill bodies that cite a path no target project receives, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
 - [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports
 - [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree
 - [Teach](teach.md): Listing learning workspaces and the ordinal a new one takes, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, the refusal reasons, and why every write here runs through a verb

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/agents/skills-reach.md

@@ -0,0 +1,57 @@
+---
+title: Citation reach
+description: Reporting the shipped skill bodies that cite a path no target project receives, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
+---
+
+# Citation reach
+
+`aitk claude skills reach [path]` reports every shipped skill body citing a path that exists in the toolkit and reaches no target project. It reads and reports. Repairing what it finds is separate work.
+
+```bash
+aitk claude skills reach
+aitk claude skills reach --json
+```
+
+| Option   | Behavior                                                   |
+| -------- | ---------------------------------------------------------- |
+| `--json` | Add a machine-readable record on stdout, keeping the frame |
+
+## The defect it reads for
+
+A plugin skill installs into a project and the toolkit's own tree is not there. A body naming `.claude/context/transcripts.md` resolves for a session running in this repository and sends every other reader to nothing, and no stage asked the question until this one. The shape is wider than one folder: a seed naming a standard with no route and a machine-readable field naming a toolkit-only path are the same claim, true here and false in a target.
+
+## What counts as a citation
+
+A backticked token carrying a separator and an extension, which is how every body spells a path it means a reader to open. Three forms are skipped by construction.
+
+- A placeholder such as `.claude/context/<domain>.md`, which names a shape rather than a file
+- A path resolved through `${CLAUDE_SKILL_DIR}`, which is self-contained wherever the plugin loads
+- A sibling named relatively, such as `references/labels.md`, which matches no authoring root and travels with the body
+
+The same sibling named from the repository root as `claude/skills/<name>/references/<file>.md` is reported rather than skipped. The plugin loads from a cache rather than from the project tree, so that spelling resolves for nobody and the report is correct.
+
+A path the toolkit does not hold is dropped rather than reported. The measure asks whether a claim true here is false in a target, and a path true in neither is a different defect that `aitk context audit` already reports against its own corpus.
+
+## The ownership key
+
+A cited path counts when it sits under an authoring root no install channel delivers. Standards install nowhere and are read through the plugin corpus, snippets land under `.claude/snippets/`, governance rules under `.claude/rules/`, and the rest is this repository's own source, catalogs, and contract pages.
+
+`src/`, `scripts/`, and bare `docs/` are deliberately outside the list. A body naming one of those is describing the reader's own tree, so listing them reports a correct citation on every run and buries the finding under the pass.
+
+A path a seed installs is disowned twice, under its own name and under the folder spelling it takes once a project splits the entry. A domain that outgrows one file becomes `<domain>/`, which is still the entry the seed delivered, so reporting the split form would fail a project for growing.
+
+## The qualifier
+
+A correct citation and a defective one are the same string, and the sentence around it is the difference. A citation counts as decided when its line names the toolkit as the owner, matching the bodies that already spell it that way. The repair for a finding is to say whose copy the path is, never to delete the citation, since the paths name real documents a reader wants.
+
+```markdown
+Read `.claude/context/indexes.md` from the toolkit if context on the system is needed.
+```
+
+A line mentioning the toolkit for an unrelated reason exempts a citation on it. That is the accepted cost of a word over a notation every future body would have to learn.
+
+## Exit codes
+
+Exit codes are `0` when every citation names its owner, `1` for a refusal, and `2` when at least one is unqualified. The refusal is a tree carrying no `claude/skills/`, which ships no plugin body to measure, and it reports the reason rather than a clean count over nothing.
+
+The verb reports rather than gates. A toolkit-scoped instruction is sometimes meant for a session in this repository, so failing a push on one would make the check something to route around. `aitk audits run` registers it with no gating exit for the same reason, and carries `unqualifiedCitations` as its retained count.

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.0.0",
+  "version": "3.2.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {