@erclx/aitk 3.7.0 → 3.8.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.7.0",
+  "version": "3.8.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/create-rule/REQUIREMENT.md

@@ -7,7 +7,7 @@ description: Why a project-local rule needs a band, a number checked against two
 
 ## Gap
 
-Without this skill, a project rule is written straight into the rules folder on a number already taken, so two rules collide and one loses. The subtler collision is with the toolkit itself. A number free in the target today can be the number a shipped rule lands on tomorrow, and the next install double-books it, so a rule the project wrote gets overwritten by one it never chose.
+Without this skill, a project rule is written straight into the rules folder on a number already taken, so two rules collide and one loses. The subtler collision was with the toolkit itself: a number free in the target today could be the number a shipped rule landed on tomorrow, and the next install double-booked it, so a rule the project wrote got overwritten by one it never chose. Writing under `.claude/rules/project/` closes that half regardless of the number, since the sync engine orphans the file by location before it ever compares names, but the band still needs a free number to stay readable against the toolkit's own numbering.
 
 The band gets picked by feel, so a UI copy rule lands in the always-on range and loads on every session for the rest of the project's life. The scope key fails in both directions. An always-on rule carrying a path scope fires only on files it was never about, and a path-scoped rule missing it loads constantly. Written from memory rather than from the rule standard, the body comes out in a shape the rest of the catalog does not share.
 
@@ -15,6 +15,7 @@ The band gets picked by feel, so a UI copy rule lands in the always-on range and
 
 - Resolve what the rule enforces and where it applies, asking only for what the request leaves missing
 - Pick the band from the topic and take its number range and folder from that choice
+- Write under `.claude/rules/project/`, the subfolder the sync engine reads as project-authored by location
 - Check both the target's used prefixes and the toolkit catalog before taking a number
 - Read the rule standard before writing the body
 - Emit the path scope for a path-scoped rule and omit the key entirely for an always-on one

package/claude/skills/create-rule/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: create-rule
-description: Scaffolds a project-specific governance rule into `.claude/rules/<subdir>/<n>-<slug>.md` with correct frontmatter and a non-colliding number. Use when asked to "add a rule", "create a governance rule", "write a project rule", or when a project needs a coding rule the toolkit does not ship. Do NOT use to edit toolkit source rules under `governance/rules/`.
+description: Scaffolds a project-specific governance rule into `.claude/rules/project/<subdir>/<n>-<slug>.md` with correct frontmatter and a non-colliding number. Use when asked to "add a rule", "create a governance rule", "write a project rule", or when a project needs a coding rule the toolkit does not ship. Do NOT use to edit toolkit source rules under `governance/rules/`.
 ---
 
 # Create rule
 
-Author a project-local governance rule. The rule lives in the target project, not the toolkit, so it is never overwritten by `aitk gov sync` (sync skips rules with no toolkit source match).
+Author a project-local governance rule. The rule lives in the target project, not the toolkit, so `aitk gov sync` never overwrites it: the sync engine orphans anything under `.claude/rules/project/` by location, before it ever checks the rule's name against the toolkit catalog.
 
 ## Guards
 
@@ -21,7 +21,7 @@ Resolve both from the request, and ask only for what is missing. Attach a propos
 
 ## Step 2: resolve band and subdir
 
-Pick the band from the topic. Each band owns a number range and a subdir under `.claude/rules/`:
+Pick the band from the topic. Each band owns a number range and a subdir under `.claude/rules/project/`:
 
 - `core/` 000-099: global persona, testing, error handling, planning. Always-on, no `paths:`.
 - `lang/` 100-199: one programming language.
@@ -34,15 +34,15 @@ Pick the band from the topic. Each band owns a number range and a subdir under `
 
 Pick the lowest unused number in the band that collides with neither the project nor the toolkit catalog:
 
-- Scan the target's `.claude/rules/<subdir>/` for used prefixes.
-- Run `aitk gov list --json 2>/dev/null` and read the shipped rule numbers in the same range, so a later `aitk gov install` cannot double-book the number.
-- If `aitk` is not on PATH, scan the target only and warn that a future toolkit install could collide.
+- Scan the target's `.claude/rules/project/<subdir>/` for used prefixes.
+- Run `aitk gov list --json 2>/dev/null` and read the shipped rule numbers in the same range, so the band stays readable against the toolkit's own numbering even though location already keeps a later `aitk gov install` from touching this file.
+- If `aitk` is not on PATH, scan the target only and warn that the band could read confusingly against a later toolkit install.
 
 ## Step 4: write the rule
 
 Read `${CLAUDE_SKILL_DIR}/../../standards/rule.md` for frontmatter, body shape, and voice before writing the body. Do not work the shape from memory.
 
-Write `.claude/rules/<subdir>/<n>-<slug>.md` where `<slug>` is a 1-to-3-word kebab topic. Preview the resolved path, band, number, and frontmatter, then write immediately. The tool permission dialog is the confirmation gate.
+Write `.claude/rules/project/<subdir>/<n>-<slug>.md` where `<slug>` is a 1-to-3-word kebab topic. Preview the resolved path, band, number, and frontmatter, then write immediately. The tool permission dialog is the confirmation gate.
 
 Frontmatter carries the Claude shape. Path-scoped rules emit one `paths:` entry per glob. Always-on rules omit `paths:` entirely.
 
@@ -65,4 +65,4 @@ Title casing is sentence case, with proper nouns keeping their own casing (`# Ty
 
 ## After writing
 
-Emit the full path on its own line: `.claude/rules/<subdir>/<n>-<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads a matching file, and always-on rules every session.
+Emit the full path on its own line: `.claude/rules/project/<subdir>/<n>-<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads a matching file, and always-on rules every session.

package/claude/skills/create-snippet/REQUIREMENT.md

@@ -11,10 +11,13 @@ Without this skill, a snippet is drafted the way any other markdown file is draf
 
 The write surface is the second failure. The toolkit authors at `snippets/` and a target project holds only the installed copy under `.claude/snippets/`, so a session picks whichever folder it noticed first. A toolkit snippet written into the consumed copy fails the drift assertion that regenerates that folder. A snippet written there in a target project is correct and looks identical, which is why the surface has to be resolved from what the project has rather than guessed.
 
+Inside the project surface, a third failure sits one level deeper. A project-authored snippet sharing a name with a toolkit one used to be indistinguishable from it, so `aitk snippets sync` could not tell which side owned the file. The sync engine now reads ownership by location for anything under `.claude/snippets/project/`, so the skill has to write there rather than beside the toolkit-installed files.
+
 ## Must
 
 - Read the bundled snippet reference before drafting, since the shape rules are what the invocation channels depend on
 - Resolve the write surface from which snippet folder the project has, rather than from whichever one the session noticed first
+- On the project surface, write under its `project/` subfolder so the sync engine reads the file as project-authored by location
 - Confirm the slug and the full body with the user before writing
 - Emit the written path in full, so the terminal can resolve it
 - State what the resolved surface implies after writing, since a root file needs the consumed copy regenerated and a project-local one needs copying to the toolkit to ship

package/claude/skills/create-snippet/SKILL.md

@@ -20,11 +20,11 @@ Creates one snippet file. Read these files in parallel:
 1. Resolve the write surface: `snippets/` at the root if present, which is the toolkit's own authoring source. Otherwise `.claude/snippets/`, a target project's installed copy.
 2. Draft the content from the user's description. The snippet reference governs structure, invocation, and authoring conventions.
 3. Confirm the slug and full content with the user before writing
-4. Write the file to `<surface>/<category>/<slug>.md`, or to `<surface>/<slug>.md` when the snippet takes no category
+4. Write the file. On the root surface: `<surface>/<category>/<slug>.md`, or `<surface>/<slug>.md` when the snippet takes no category. On the `.claude/` surface: the same shape nested one level deeper under `project/`, so the sync engine's location rule holds it apart from a toolkit-installed snippet regardless of what its name matches.
 
 ## After writing
 
 Emit the full path on its own line.
 
 - Root surface: this is the toolkit's authoring source. Remind the user to run `bun run check` to regenerate the consumed copy under `.claude/`.
-- `.claude/` surface: the file is project-local. `aitk snippets sync` leaves it alone, since sync only updates filenames it recognizes from the toolkit. Remind the user to copy it to the toolkit repo, under `snippets/<category>/<name>.md`, if it should ship to every project.
+- `.claude/` surface: the file is project-local, under `.claude/snippets/project/`. `aitk snippets sync` leaves everything there alone by location rather than by a name it fails to recognize. Remind the user to copy it to the toolkit repo, under `snippets/<category>/<name>.md`, if it should ship to every project.

package/claude/skills/restate/REQUIREMENT.md

@@ -0,0 +1,41 @@
+---
+name: restate
+description: Why a plain restatement is asked for by name, and where its boundary sits against the skill that drafts and the command that measures
+---
+
+# Restate requirement
+
+## Gap
+
+Without this skill, a reader who cannot follow a dense answer has to ask for it again in ordinary words, and the second answer is drafted by the same session that produced the first. Nothing tells that session which half of its own text carried the decision, so the rewrite shortens the passage and keeps the abstraction that made it hard to read.
+
+The corpus around it covers the neighboring jobs and not this one. `write-human` governs a passage being drafted or revised and arrives on a markdown edit, so it never sees an answer in chat and never reaches a document nobody is editing. `aitk markdown audit` reports sentence spread and repeated openings against a stated range, which measures how a passage moves and says nothing about whether a reader can act on it.
+
+A restatement also fails in a way a rewrite does not. A run that compresses by dropping what supports a claim leaves a reader who acts on the plain version and meets a different answer in the source, and that failure is invisible in the restatement itself.
+
+## Must
+
+- Take a named markdown path or the preceding answer, resolving the path first, since a reader pointing at a file has already said which one they mean
+- Keep every point that changes a decision and cut what only supports one, which is the split that separates a restatement from a summary
+- Preserve a hedge the source carries, since dropping it manufactures a certainty
+- Cite the carrier of the rhythm and density rules rather than restating them, because a second copy drifts with nothing comparing the two
+- Fire on an explicit request and refuse the model's own judgment about its own output
+
+## Must not
+
+- Write a file. A restatement is read once to reach a decision, and a file makes a record nobody opens twice.
+- Add a fact, number, or name the source does not carry
+- Restate the voice, rhythm, or density rules, which live in the skill this body cites
+- Claim the restatement is verified. Nothing checks whether a plain version kept the deciding half, so the sandbox arm asserts what the run did rather than that the output is good.
+
+## Guards
+
+- A named path that does not resolve stops the run rather than falling back to the preceding answer, since the two inputs are different requests
+- A request with no path and nothing preceding it stops rather than restating the request itself
+
+## Out of scope
+
+- Drafting or revising a passage, which is `write-human` on a markdown edit
+- Measuring cadence in finished output, which `aitk markdown audit` reports from package data
+- Rewriting a document into a file, which is a proposal against the source rather than a restatement of it
+- The banned words, characters, and spellings, which `markdown.md` states and the audit gates

package/claude/skills/restate/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: restate
+description: Restates a dense answer or a named markdown document in plain language, cutting jargon and keeping only what changes a decision. Use when asked to "restate that in plain language", "say that plainly", "what does this actually mean", "cut the jargon", "give me the plain version", or "restate this document". Do NOT use to draft or revise prose, which is `write-human`, and do NOT fire on the model's own judgment that its own output was dense.
+---
+
+# Restate
+
+Return the plain version of something already written. The reader asked because they stopped to decode rather than to decide, so the restatement earns its place by getting them to the decision.
+
+## What to restate
+
+- Restate the file when the request names a markdown path, and the preceding answer in the conversation when it names none. A named path wins over an answer sitting in the same turn.
+- Stop when the request names a path that does not resolve: `❌ No file at <path>. Name a path that exists, or ask for the preceding answer instead.`
+- Stop when nothing precedes the request and no path is named: `❌ Nothing to restate. Name a markdown path, or ask right after the answer you want in plain words.`
+- Refuse a request to restate output on the model's own initiative. A person asks for this by name.
+
+## What survives
+
+- Keep every point that changes a decision, and cut every point that only supports one. A reader who acts on the restatement and is surprised by the original has been given the wrong half.
+- Name the thing the source names. Replace a term of art with its plain equivalent, and keep the term where the reader has to search for it later.
+- Say what is uncertain where the source hedges, and say it plainly. Dropping a hedge invents a certainty the source does not carry.
+- Introduce no fact, number, or name the source lacks. A restatement changes wording and never claims.
+- Report the reasoning, not the metaphor. An abstraction standing in for a mechanism is what made the source dense.
+
+## How it reads
+
+Load the `write-human` skill before writing the restatement. Compression is where a plain version turns into a list of verbless fragments, and that skill states the rhythm and density rules this one does not copy.
+
+## Output
+
+Answer in chat. Write no file, since a restatement is read once to reach a decision.
+
+Lead with the plain version in prose. Close with one line naming what was cut and why, so the reader can go back for it:
+
+```plaintext
+Cut: <what left, and why it changes no decision>
+```
+
+Name the source path on its own line when the restatement came from a file.

package/claude/skills/write-human/REQUIREMENT.md

@@ -41,6 +41,6 @@ Importing that catalog wholesale fails on a different measurement. External mate
 
 - The banned words, characters, and spellings, which `markdown.md` states for a reader and `aitk markdown audit` gates from package data
 - Markdown mechanics, being headings, lists, code spans, punctuation, and file references
-- Restating text that already exists in plainer words, which is a different job on a different trigger, since a restatement is asked for by name and this arrives on a glob match
+- Restating text that already exists in plainer words, which `restate` owns on a different trigger, since a restatement is asked for by name and this arrives on a glob match. The rules here still govern how that restatement reads, and that body cites this one rather than carrying a copy.
 - What voice a given surface declares, which belongs to the standard governing that surface
 - Measuring whether finished output followed these rules, which needs a check this skill does not carry

package/claude/skills/write-human/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: write-human
-description: Carries the voice, rhythm, sentence construction, and information density rules a banned-word list cannot express, plus the catalog of machine tells that survive a clean ban scan. Use when writing or revising prose a person will read, when a passage reads flat or uniform, or when asked to "make this read like a person", "fix the cadence", "this reads like AI wrote it", "vary the sentences", or "tighten this without gutting it". Do NOT use for banned words, characters, or spellings, which `markdown.md` states and `aitk markdown audit` gates, and do NOT use to restate text that already exists in plainer words.
+description: Carries the voice, rhythm, sentence construction, and information density rules a banned-word list cannot express, plus the catalog of machine tells that survive a clean ban scan. Use when writing or revising prose a person will read, when a passage reads flat or uniform, or when asked to "make this read like a person", "fix the cadence", "this reads like AI wrote it", "vary the sentences", or "tighten this without gutting it". Do NOT use for banned words, characters, or spellings, which `markdown.md` states and `aitk markdown audit` gates, and do NOT use to restate text that already exists in plainer words, which is `restate`, whose body loads these rules from here.
 ---
 
 # Write human

package/docs/agents/commands.md

@@ -47,6 +47,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `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 claude routing`      | Report per `CLAUDE.md` section how many bullets name a path and how many of those a path-scoped rule already covers (`--json`)                 |
 | `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                        |
 | `aitk gov superseded`      | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value (`--json`)                             |
 | `aitk secrets scan`        | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`)                          |
@@ -63,27 +64,27 @@ 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`, `superseded`                                     |
-| `claude`    | `init`, `sync`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `setup [dest]` |
-| `demo`      | `compile`, `run`                                                                                            |
-| `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`                                                                                               |
+| 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`, `superseded`                                                |
+| `claude`    | `init`, `sync`, `routing`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `setup [dest]` |
+| `demo`      | `compile`, `run`                                                                                                       |
+| `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

@@ -24,6 +24,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [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
 - [Records](records.md): Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
+- [Routing report](routing.md): Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [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

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

@@ -11,7 +11,9 @@ The behavior notes behind the verbs listed in `commands.md`. Each one records wh
 
 `aitk gov sync` updates only rules already present under `.claude/rules/` and
 never adds new ones. A rule the toolkit does not ship is left alone, which is
-how project-authored rules survive. It also removes a stale `.claude/GOV.md`
+how project-authored rules survive, and one under `.claude/rules/project/`
+is left alone regardless of its name, since that subfolder is project-authored
+by location. It also removes a stale `.claude/GOV.md`
 from the retired build. Use `aitk gov install` to add rules.
 
 There is no `aitk standards sync` and no `aitk standards install`. The corpus
@@ -23,7 +25,9 @@ the catalog.
 `aitk snippets sync` matches by path relative to `.claude/snippets/`. It
 matches by path relative to that directory, so a snippet the toolkit no longer
 ships, or one authored directly in the target, is reported and skipped rather
-than deleted. It is not preset-aware, so a project that installed `essentials`
+than deleted, and a snippet under `.claude/snippets/project/` skips the same
+way regardless of path, since that subfolder is project-authored by location.
+It is not preset-aware, so a project that installed `essentials`
 does not grow new snippets on a sync. Use `aitk snippets install` to add them.
 
 ## Install guards

package/docs/agents/routing.md

@@ -0,0 +1,61 @@
+---
+title: Routing report
+description: Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates
+---
+
+# Routing report
+
+`aitk claude routing` reports, per `CLAUDE.md` section, how many top-level bullets name a path and how many of those a path-scoped rule already covers. It answers the tier test in `.claude/rules/claude/592-claude-md.md`, which asks whether a fact applies every session or fires on one path, and which until this verb existed was a judgment nothing counted.
+
+```bash
+aitk claude routing
+aitk claude routing --json
+aitk claude routing ../my-app
+```
+
+| Option   | Behavior                                                     |
+| -------- | ------------------------------------------------------------ |
+| `[path]` | Repository root to read, defaulting to the current directory |
+| `--json` | Add a machine-readable record on stdout, keeping the frame   |
+
+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 root is the argument rather than the toolkit, matching the reach and drift verbs, so a linked worktree reads its own branch and a target reads its own file.
+
+## What it reads
+
+Every H2 and H3 owning at least one top-level bullet. An H3 is reported under the H2 containing it, as `Behavior / Scope discipline`, so a section and its subsections are counted apart rather than summed.
+
+Three things are read past. A nested bullet belongs to the one above it rather than to the section. A bullet inside a fenced block is example text rather than instruction. A heading carrying no bullet answers nothing the report asks, so it is dropped rather than listed at zero.
+
+## What counts as naming a path
+
+A bullet is path-scoped here when it names a path. That is evidence for the tier judgment rather than the judgment itself, and the gap runs both ways: a bullet naming a folder can still apply every session, and one firing on a path it never spells is invisible to the count. Read a section's number as a place to look rather than as a verdict on it.
+
+A backticked token counts when it carries a separator or an alphabetic extension, which admits `src/cli.ts` and `cspell.json` while leaving a flag, a bare word, and a version string out.
+
+A shape counts as the folder above its placeholder. `.claude/context/<domain>.md` names `.claude/context/` and nothing narrower, so dropping the token whole would report the section carrying it as naming no path at all. A placeholder opening the first segment has no openable prefix and is dropped.
+
+## When a rule counts as covering it
+
+A rule covers a named path only when its glob anchors to a location. A glob opening `**` reaches every folder in the tree, so it answers that a file type is governed and never that a named path is.
+
+The corpus-wide markdown rules are what force that. Counting one reports every markdown path as covered, which collapses the column to a constant and tells a reader nothing about which folder somebody actually scoped a rule to.
+
+A folder is probed with a handful of extensions rather than matched literally, because a glob narrowed by file type reaches under a folder without ever matching the folder's own name. Globs are read from each rule's frontmatter block alone, so a rule quoting a path in its body does not register a scope it never declared.
+
+The paths a section names that no rule reaches are listed beside it, which is where a reader looks first when deciding what a new rule would cover.
+
+## Refusals
+
+Two, each naming what a reader does about it. `no-claude-md` is a tree with no always-loaded file. `no-rules` is a tree carrying no path-scoped rule under `.claude/rules/`, where every path would report as uncovered and the column would say nothing.
+
+An always-on rule declaring no `paths` is skipped rather than refused. It applies at the same priority as the always-loaded file, so it covers no path in particular.
+
+## Exit codes
+
+Exit codes are `0` when the file was read and `1` for a refusal. No finding moves the exit code.
+
+Nothing wires this into `bun run check` or into a hook. Whether a bullet belongs in a rule is a judgment, and gating a measure that counts a judgment forces an escape hatch for every deliberate case.
+
+An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the JSON record's `sections` array rather than the exit when a skill consumes this.

package/docs/ai-workflow.md

@@ -288,6 +288,7 @@ This section is the corpus the coverage claim is measured against: every name `a
 | `aitk:youtube-transcripts` | When a video transcript is wanted in the repo as context                       |
 | `aitk:claude-teach`        | To learn a subject across sessions, in a workspace that holds the progress     |
 | `aitk:write-human`         | Before drafting or revising prose, for voice, rhythm, and density              |
+| `aitk:restate`             | When an answer or a document has to be read again in plain words               |
 
 Every row answers a question rather than marking a point in a project's life, so a phase above would send a reader to the wrong group.
 

package/package.json

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

package/src/claude/routing.ts

@@ -0,0 +1,283 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const CLAUDE_MD = 'CLAUDE.md'
+const RULES_DIR = join('.claude', 'rules')
+
+/** A backticked token, which is how the always-loaded file spells a path. */
+const TOKEN = /`([^`\s]+)`/g
+
+/**
+ * A path a reader could open. Admits no `$`, `*`, or `=`, so an assignment
+ * (`AITK_NON_INTERACTIVE=1`) and a variable are both excluded.
+ */
+const PATH_TOKEN = /^[.A-Za-z0-9_][A-Za-z0-9._/-]*$/
+
+/** A placeholder segment, which a shape carries and a real path does not. */
+const SHAPE = /<[^>]*>/
+
+/** An alphabetic extension, which separates `cspell.json` from `3.6.0`. */
+const EXTENSION = /\.[a-z]{2,5}$/
+
+/** Extensions a folder is probed with, so a glob narrowed by type still hits. */
+const PROBES = ['probe.md', 'probe.ts', 'probe.tsx', 'probe.sh', 'probe.json']
+
+export interface RuleGlobs {
+  /** Path under `.claude/rules/`, which is how a reader cites a rule. */
+  readonly rule: string
+  readonly globs: readonly string[]
+}
+
+export interface Section {
+  /** `Behavior` for an H2, `Behavior / Scope` for the H3 beneath it. */
+  readonly heading: string
+  /** The top-level bullet lines the heading owns, in reading order. */
+  readonly lines: readonly string[]
+}
+
+export interface SectionReport {
+  readonly heading: string
+  readonly bullets: number
+  /** Bullets naming at least one path, which is the reading this measures. */
+  readonly pathScoped: number
+  /** Path-scoped bullets whose named path some rule glob already reaches. */
+  readonly covered: number
+  /** Distinct named paths no rule glob reaches, in reading order. */
+  readonly uncovered: readonly string[]
+}
+
+/** Why a scan produced no reading, which is never the same as a clean one. */
+export type RoutingRefusal = 'no-claude-md' | 'no-rules'
+
+export type RoutingReport =
+  | {
+      readonly kind: 'measured'
+      readonly rules: number
+      readonly sections: readonly SectionReport[]
+    }
+  | { readonly kind: 'refused'; readonly reason: RoutingRefusal }
+
+/**
+ * Every distinct path one bullet names, in reading order.
+ *
+ * Naming a path is what this measures, not firing only on it. A bullet can
+ * name a folder and still apply every session, and one can fire on a path it
+ * never spells, so the count is a reading a person still has to judge.
+ */
+export function namedPaths(line: string): string[] {
+  const paths: string[] = []
+
+  for (const match of line.matchAll(TOKEN)) {
+    const token = concretePrefix(match[1])
+    if (token === undefined) continue
+    if (!PATH_TOKEN.test(token)) continue
+    if (!token.includes('/') && !EXTENSION.test(token)) continue
+    if (!paths.includes(token)) paths.push(token)
+  }
+
+  return paths
+}
+
+/**
+ * The openable part of a token, which for a shape is the folder above the
+ * placeholder.
+ *
+ * `.claude/context/<domain>.md` names `.claude/context/` and nothing narrower,
+ * so dropping the whole token would report the section that carries it as
+ * naming no path at all. A token whose placeholder sits in the first segment
+ * has no openable prefix and is dropped.
+ */
+function concretePrefix(token: string): string | undefined {
+  if (!SHAPE.test(token)) return token
+
+  const prefix = token.slice(0, token.indexOf('<'))
+  return prefix.endsWith('/') ? prefix : undefined
+}
+
+/**
+ * Splits the file into the sections a reader sees, counting top-level bullets.
+ *
+ * A nested bullet belongs to the one above it rather than to the section, and
+ * a fenced block holds example text rather than instruction, so neither is
+ * counted. A heading carrying no bullet is dropped, since the report answers
+ * how many bullets are path-scoped and a section with none answers nothing.
+ */
+export function splitSections(text: string): Section[] {
+  const sections: Section[] = []
+  let parent = ''
+  let heading: string | undefined
+  let lines: string[] = []
+  let fenced = false
+
+  const flush = (): void => {
+    if (heading !== undefined && lines.length > 0)
+      sections.push({ heading, lines })
+  }
+
+  const open = (next: string): void => {
+    flush()
+    heading = next
+    lines = []
+  }
+
+  for (const line of text.split('\n')) {
+    if (line.startsWith('```')) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+
+    const h2 = line.match(/^## (.+)$/)
+    if (h2) {
+      parent = h2[1]
+      open(parent)
+      continue
+    }
+
+    const h3 = line.match(/^### (.+)$/)
+    if (h3) {
+      open(parent === '' ? h3[1] : `${parent} / ${h3[1]}`)
+      continue
+    }
+
+    if (line.startsWith('- ')) lines.push(line)
+  }
+
+  flush()
+  return sections
+}
+
+/**
+ * Every path-scoped rule the tree installs, with the globs it declares.
+ *
+ * An always-on rule declares no `paths` and applies at the same priority as
+ * the always-loaded file, so it covers no path in particular and is skipped.
+ */
+export function readRuleGlobs(root: string): RuleGlobs[] {
+  const rulesRoot = join(root, RULES_DIR)
+  if (!existsSync(rulesRoot)) return []
+
+  const rules: RuleGlobs[] = []
+  const files = [
+    ...new Bun.Glob('**/*.md').scanSync({ cwd: rulesRoot, onlyFiles: true }),
+  ].sort()
+
+  for (const file of files) {
+    const text = readFileSync(join(rulesRoot, file), 'utf8')
+    const globs = [...frontmatter(text).matchAll(/^\s*-\s*'([^']+)'\s*$/gm)]
+      .map((match) => match[1])
+      .filter((glob) => glob.includes('*') || glob.includes('.'))
+
+    if (globs.length === 0) continue
+    rules.push({ rule: file.replaceAll('\\', '/'), globs })
+  }
+
+  return rules
+}
+
+/**
+ * The block between the opening and closing `---`, or nothing for a rule
+ * carrying no frontmatter.
+ *
+ * Bounding the read is what keeps a body bullet out of the glob list. A rule
+ * quoting a path in prose would otherwise register it as a scope the rule
+ * never declared, and the resulting coverage would be wrong with nothing
+ * reporting it.
+ */
+function frontmatter(text: string): string {
+  if (!text.startsWith('---\n')) return ''
+
+  const end = text.indexOf('\n---', 3)
+  return end === -1 ? '' : text.slice(4, end)
+}
+
+/**
+ * Whether a glob scopes itself to a location rather than to a file type.
+ *
+ * A glob opening `**` reaches every folder in the tree, so it answers that a
+ * file type is governed and never that a named path is. Counting one would
+ * report every markdown path covered by `501-markdown` and leave the column
+ * saying nothing a reader could act on.
+ */
+function isAnchored(glob: string): boolean {
+  return !glob.startsWith('**/')
+}
+
+/**
+ * The first rule scoping itself to a named path, or undefined for none.
+ *
+ * A folder is probed with a handful of extensions rather than matched as a
+ * literal, because a glob narrowed by file type reaches under the folder
+ * without ever matching the folder's own name.
+ */
+export function coveringRule(
+  path: string,
+  rules: readonly RuleGlobs[],
+): string | undefined {
+  const bare = path.replace(/\/+$/, '')
+  const candidates = [bare, ...PROBES.map((probe) => `${bare}/${probe}`)]
+
+  for (const { rule, globs } of rules) {
+    for (const glob of globs) {
+      if (!isAnchored(glob)) continue
+      const matcher = new Bun.Glob(glob)
+      if (candidates.some((candidate) => matcher.match(candidate))) return rule
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Reads the always-loaded file against the rules installed beside it.
+ *
+ * Measures the tree it is pointed at rather than the toolkit root, so a linked
+ * worktree reads its own branch and a target reads its own file.
+ */
+export function scanRouting(root: string): RoutingReport {
+  const file = join(root, CLAUDE_MD)
+  if (!existsSync(file)) return { kind: 'refused', reason: 'no-claude-md' }
+
+  const rules = readRuleGlobs(root)
+  if (rules.length === 0) return { kind: 'refused', reason: 'no-rules' }
+
+  const sections = splitSections(readFileSync(file, 'utf8')).map((section) =>
+    classify(section, rules),
+  )
+
+  return { kind: 'measured', rules: rules.length, sections }
+}
+
+/** Counts one section's bullets against the rules installed beside the file. */
+function classify(
+  section: Section,
+  rules: readonly RuleGlobs[],
+): SectionReport {
+  let pathScoped = 0
+  let covered = 0
+  const uncovered: string[] = []
+
+  for (const line of section.lines) {
+    const paths = namedPaths(line)
+    if (paths.length === 0) continue
+    pathScoped += 1
+
+    const reached = paths.filter(
+      (path) => coveringRule(path, rules) !== undefined,
+    )
+    if (reached.length > 0) covered += 1
+
+    for (const path of paths) {
+      if (reached.includes(path) || uncovered.includes(path)) continue
+      uncovered.push(path)
+    }
+  }
+
+  return {
+    heading: section.heading,
+    bullets: section.lines.length,
+    pathScoped,
+    covered,
+    uncovered,
+  }
+}

package/src/commands/claude.ts

@@ -21,6 +21,11 @@ import {
   type SkillFinding,
   type SkillsAudit,
 } from '@/claude/skills-audit'
+import {
+  type RoutingRefusal,
+  type RoutingReport,
+  scanRouting,
+} from '@/claude/routing'
 import { type DriftReport, readDrift } from '@/claude/skills-drift'
 import { listSkills } from '@/claude/skills-list'
 import {
@@ -79,6 +84,10 @@ interface SkillsReachOptions {
   readonly json?: boolean
 }
 
+interface RoutingOptions {
+  readonly json?: boolean
+}
+
 const SEEDED_FILES: readonly string[] = [
   'ARCHITECTURE.md',
   'REQUIREMENTS.md',
@@ -91,7 +100,7 @@ const STATUSLINE = 'statusline-command.sh'
 export function register(program: Command): void {
   const claude = program
     .command('claude')
-    .description('Claude workflow (init, seeds, sync, setup)')
+    .description('Claude workflow (init, seeds, sync, setup, routing)')
     .helpOption('-h, --help', 'Show this help message')
     .addHelpText(
       'after',
@@ -167,6 +176,42 @@ export function register(program: Command): void {
       process.exitCode = await runSeedsList(opts)
     })
 
+  claude
+    .command('routing')
+    .description('Report per CLAUDE.md section how many bullets name a path')
+    .argument('[path]', 'Repository root, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Scope:',
+        '  Every H2 and H3 in CLAUDE.md that owns at least one top-level',
+        '  bullet, counted against the path-scoped rules under .claude/rules/.',
+        '  A bullet is path-scoped here when it names a path, which is not the',
+        "  same as firing only on one. A rule's glob covers a named folder",
+        '  only when the glob is anchored to a location rather than to a file',
+        '  type, so **/*.md covers README.md and no folder at all.',
+        '',
+        'Exit codes:',
+        '  0  the file was read',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Reports rather than gates. Whether a bullet belongs in a rule is the',
+        'judgment 592-claude-md states, and naming a path is evidence for it',
+        'rather than the answer.',
+        '',
+        'Examples:',
+        '  aitk claude routing',
+        '  aitk claude routing --json',
+        '',
+      ].join('\n'),
+    )
+    .action((path: string | undefined, opts: RoutingOptions) => {
+      process.exitCode = runRouting(path, opts)
+    })
+
   const skills = claude
     .command('skills')
     .description('Plugin skill catalog (list, audit, drift, reach)')
@@ -612,6 +657,90 @@ function reportSkew(skew: SkewReport): void {
   else logInfo(describeSkew(skew))
 }
 
+/** What a reader does about each way the reading cannot be taken. */
+const ROUTING_REFUSALS: Record<RoutingRefusal, string> = {
+  'no-claude-md': 'No CLAUDE.md here, so this tree has no always-loaded file.',
+  'no-rules':
+    'No path-scoped rules under .claude/rules/, so nothing covers a path yet.',
+}
+
+/**
+ * Measures the cwd rather than the toolkit root, matching the reach and drift
+ * verbs, so a linked worktree reads its own branch instead of `main`.
+ */
+function runRouting(path: string | undefined, opts: RoutingOptions): number {
+  const root = resolve(path ?? process.cwd())
+  const report = scanRouting(root)
+
+  if (report.kind === 'refused') {
+    frameError(ROUTING_REFUSALS[report.reason])
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: report.reason,
+          message: ROUTING_REFUSALS[report.reason],
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
+  intro('aitk claude routing')
+  reportRouting(report)
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        rules: report.rules,
+        sections: report.sections,
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
+/**
+ * States the corpus on every run, so a section naming no path reads as
+ * measured rather than as skipped. A reader deciding what to cut needs the
+ * sections that stay as much as the ones that move.
+ */
+function reportRouting(
+  report: Extract<RoutingReport, { kind: 'measured' }>,
+): void {
+  const bullets = report.sections.reduce(
+    (total, section) => total + section.bullets,
+    0,
+  )
+  const pathScoped = report.sections.reduce(
+    (total, section) => total + section.pathScoped,
+    0,
+  )
+
+  logStep('Corpus')
+  logInfo(
+    `${plural(report.sections.length, 'section')} carrying ${plural(bullets, 'bullet')}, read against ${plural(report.rules, 'path-scoped rule')}`,
+  )
+
+  logStep('Sections')
+  logInfo(`${pathScoped} of ${bullets} bullets name a path`)
+  pipeOutput(
+    report.sections
+      .map(
+        (section) =>
+          `${section.pathScoped}/${section.bullets} path-scoped, ${section.covered} covered  ${section.heading}${
+            section.uncovered.length === 0
+              ? ''
+              : `  [uncovered: ${section.uncovered.join(', ')}]`
+          }`,
+      )
+      .join('\n'),
+  )
+}
+
 /** What a reader does about the one way the corpus fails to build. */
 const REACH_REFUSALS: Record<ReachRefusal, string> = {
   'no-skills':

package/src/gov/adapter.ts

@@ -54,6 +54,7 @@ export function createGovAdapter(root: string): SyncAdapter {
     locateSource: (file: InstalledFile) =>
       index.get(basename(file.path, '.md')),
     collectRetired: (target: string) => collectRetiredGov(target),
+    projectSubdir: 'project',
     stamp: { domain: 'governance', toolkitRoot: root },
   }
 }

package/src/snippets/adapter.ts

@@ -21,6 +21,7 @@ export function createSnippetsAdapter(root: string): SyncAdapter {
     unit: 'snippets',
     installedRoot: (target: string) => join(target, '.claude', 'snippets'),
     locateSource: (file: InstalledFile) => locateSource(sourceDir, file),
+    projectSubdir: 'project',
     stamp: { domain: 'snippets', toolkitRoot: root },
   }
 }

package/src/sync/engine.ts

@@ -121,6 +121,13 @@ export interface SyncAdapter {
   collectRetired?(target: string): RetiredSurface[]
   /** Dropped from the walk, so neither matching nor orphaned. */
   isExcluded?(file: InstalledFile): boolean
+  /**
+   * Top-level folder under `installedRoot` that is project-authored by
+   * location rather than by the name inference `locateSource` runs.
+   * Checked before `locateSource`, so a file here is orphaned even when its
+   * name also matches a toolkit source, and never enters the stamp.
+   */
+  readonly projectSubdir?: string
   /** Defaults to applying. */
   readonly nonInteractive?: NonInteractivePolicy
   /** Runs on a completed sync, including one with no changes. */
@@ -168,6 +175,11 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
     if (adapter.isExcluded?.(file) === true) continue
     walked.add(toStampKey(file.rel))
 
+    if (isProjectAuthored(adapter, file)) {
+      entries.push({ state: 'orphaned', rel: file.rel })
+      continue
+    }
+
     const source = adapter.locateSource(file)
 
     if (source === undefined || !existsSync(source)) {
@@ -439,6 +451,16 @@ function strandedByRelocation(
   return entries
 }
 
+/**
+ * `Bun.Glob` reports `relToRoot` with `/` separators regardless of platform,
+ * so the declared subfolder is compared against the walk's first segment
+ * rather than through a path-aware join.
+ */
+function isProjectAuthored(adapter: SyncAdapter, file: InstalledFile): boolean {
+  if (adapter.projectSubdir === undefined) return false
+  return file.relToRoot.split('/')[0] === adapter.projectSubdir
+}
+
 function isInside(target: string, path: string): boolean {
   const rel = relative(target, path)
   return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)
@@ -457,7 +479,8 @@ function hasUnattributedDrift(plan: SyncPlan): boolean {
 /**
  * Records what the toolkit placed, after the copies land, so a partial apply
  * that throws leaves the previous stamp rather than a claim the target does not
- * meet. Files with no source are project-authored and stay out.
+ * meet. A file with no source, or one orphaned by location, is
+ * project-authored and stays out.
  *
  * Reads the installed tree rather than the caller's file list, so a partial
  * install still stamps the domain's whole installed set.
@@ -474,6 +497,7 @@ export async function recordStamp(
 
   for (const file of listInstalled(adapter.installedRoot(target), target)) {
     if (adapter.isExcluded?.(file) === true) continue
+    if (isProjectAuthored(adapter, file)) continue
 
     const source = adapter.locateSource(file)
     if (source === undefined || !existsSync(source)) continue