@erclx/aitk 3.13.0 → 3.14.1

package/README.md

@@ -116,7 +116,7 @@ git init
 aitk init
 ```
 
-`aitk init` installs base tooling configs, Claude seeds, governance rules, and snippets in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/`. Each rule names the standard it answers to and reads it with `aitk standards <name>`, so no corpus is copied into your project. Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. Run `aitk tooling list --json` to see the catalog.
+`aitk init` installs base tooling configs, Claude seeds, and governance rules in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/`. Each rule names the standard it answers to and reads it with `aitk standards <name>`, so no corpus is copied into your project. Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. Snippets install only when you name a category with `--snippets <category>`, such as `--snippets essentials`. Run `aitk tooling list --json` to see the catalog.
 
 For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target-projects.md).
 

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

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

package/claude/skills/claude-address-review/SKILL.md

@@ -78,11 +78,14 @@ the `git-followup` skill, invoked with `reply-owned` so it stages, commits,
 pushes, and refreshes the open PR body without posting its own comment. This
 skill owns the reply. Do not reimplement that flow here.
 
-For in-place fixes to files the PR body already covers, `git-followup` leaves the body untouched and
-the reply comment carries the fix log. A rebase in step 5 rewrote the branch, so
-that push is a force-push and `git-followup` resolves it from the tracking
-branch. Worker branches are single-owner here, which is what makes overwriting
-the remote safe.
+`git-followup` syncs the body and title against the fix commit on every
+invocation, including `reply-owned`, so the merge record reflects what this pass
+changed rather than only what opened the PR. The reply comment still carries the
+fix log mapped to each finding, since the two serve different readers: the body
+is the merge record and the reply is the review's own thread. A rebase in step 5
+rewrote the branch, so that push is a force-push and `git-followup` resolves it
+from the tracking branch. Worker branches are single-owner here, which is what
+makes overwriting the remote safe.
 
 `git-followup` stops on an unchanged tree. A run that answered every finding as a
 conscious-accept and whose rebase left the generated files alone has nothing for

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

@@ -87,6 +87,8 @@ Then read the description's `## Testing` section, which is the one part of a pul
 
 Test every unchecked box against the testing discipline in `${CLAUDE_SKILL_DIR}/../../standards/pr.md`, which reserves an unchecked box for a capability the agent lacks. Raise the box when it names no human at all, when the human it names is a live agent session, or when it names a person for a step the repository ships a harness for, `scripts/sandbox/run.sh` and `scripts/eval/run.sh` being the two. Cost alone is not an answer, since authorizing a spend is the operator's and performing the run is not. A refusal the author actually met is an answer, and it names which one.
 
+Test every ticked box too, bounded to one naming a file or a command. Confirm what it names still exists at `<headRefOid>`, `git show <headRefOid>:<path>` for a file or `git grep <command> <headRefOid>` for a command, rather than re-running what it claims. A box naming neither stays untested, since nothing here can confirm a claim carrying no artifact. A box ticked before a later commit removed or replaced what it names is a `should-fix` finding on the body itself, filed under a `**PR body**` block ahead of the file blocks, since what it corrupts is the merge record rather than a file in the diff.
+
 Ask rather than grade. Whether a human is genuinely required is a reading the branch author may hold a reason this session cannot see, so the question carries no severity and enters no count. What it does carry is the heading and the dispatch, on the rule Step 4 states, because a question the author never receives corrects nothing and the author is the only party who can answer it. Answering it closes it, and the answer may be that the requirement holds.
 
 Read `## For the reviewer` the same way, bounded to the bullets under that heading rather than the Summary or the Technical Context around it. Those two carry the author's argument for the change, and reading them while judging it is most of what an independent pass exists to avoid, so the read stops at the section itself.
@@ -140,6 +142,8 @@ X critical, Y should-fix, Z minor. Reviewed against project docs and the board.
 🤖 Reviewed by Claude Code
 ```
 
+A stale ticked box goes in a `**PR body**` block, in place of a `**`path/to/file.ext`**` block and ahead of every one of those, since it precedes the code the diff carries rather than sitting inside it.
+
 A later pass carrying findings keeps that shape and changes only the summary line:
 
 ```markdown

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 the toolkit's `snippets/decision-help.md` behind it, which installs into a project as `.claude/snippets/decision-help.md`. The second branch now states how a question is shaped and where it is put, so this skill inherits both and adds only what a batch needs on top of one question.
+`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 that took snippets as `.claude/snippets/decision-help.md`. The second branch now states how a question is shaped and where it is put, so this skill inherits both and adds only what a batch needs on top of one question.
 
 ## Must
 

package/claude/skills/git-followup/REQUIREMENT.md

@@ -11,6 +11,8 @@ Without this skill, an edit made after a pull request is already open ships as a
 
 A caller that rebased the branch before handing over hits a rejected push, since the tracking branch no longer reaches the head. A branch entered through a worktree hits the opposite shape, carrying an open pull request with no tracking ref at all, which read as a branch that had never been pushed.
 
+A fix commit answering a review is the sharpest case of the first paragraph, since it always changes what shipped. The routing that once picked whether to sync the body keyed off the same branch that decides whether to reply, so reaching `reply-owned` or a nonzero comment count meant the sync never ran at all. The description a merge record carries was true when the pull request opened and false by the time review finished, with nothing between the two that read it back.
+
 ## Must
 
 - Refuse unless the branch has an open pull request, since every later step addresses it

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

@@ -8,7 +8,7 @@ description: Ships a small self-review edit on the current PR branch by staging,
 Ship a small self-review edit on the current PR branch in one pass.
 
 When invoked with `reply-owned`, a caller such as `claude-address-review` posts
-its own reply, so skip the comment in step 6. The push and body sync still run.
+its own reply, so skip the comment in step 7. The push and body sync still run.
 
 ## Guards
 
@@ -30,10 +30,14 @@ A missing tracking ref is no longer a guard. An open pull request proves the bra
    The lease is what stops the force from overwriting a commit this session never read. Run the ancestry test only where an upstream resolves, since it reads `@{u}`.
 
 5. Check for existing review comments: `gh api 'repos/{owner}/{repo}/pulls/<number>/comments' --jq 'length'`, resolving `<number>` from `gh pr view --json number`.
-6. Route on the invocation and the comment count.
-   - When invoked with `reply-owned`, skip this step's comment: the caller posts the reply.
+6. Sync the body and title on every invocation, before the routing below decides on the reply.
+   - Run `gh pr view --json url,title,body` and update the body with `gh pr edit --body` when the new commit changes scope, and the title with `gh pr edit --title` when the scope shifted enough to make it inaccurate.
+   - A fix commit answering a review changes what shipped exactly as much as an ordinary followup does, so the sync cannot wait on the invocation or the comment count below.
+   - A body a person edited by hand between rounds gets no special handling: judge it against the tree the same way regardless of who wrote it last, since a hand-edit the fix commit has made stale is the exact drift this sync exists to close.
+7. Route on the invocation and the comment count for the reply alone.
+   - When invoked with `reply-owned`, skip this step: the caller posts its own reply.
    - Otherwise, if the count is above zero, the followup addresses review feedback: post a one-line summary of the fix with `gh pr comment --body`, first running the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against it, since the hook does not see an inline comment body.
-   - If it is zero, run `gh pr view --json url,title,body` and update the body with `gh pr edit --body` when the new commit changes scope, and the title with `gh pr edit --title` when the scope shifted enough to make it inaccurate.
+   - If it is zero, nothing further runs. The sync in step 6 already did this branch's job.
 
 ## After completion
 

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

@@ -363,9 +363,17 @@ which is what makes it scriptable.
 
 `--stack` defaults to `base`, and the default
 does not read as a passed flag, so a bare `aitk init` installs governance and
-still prompts. `--skip` takes `wiki` and `governance`, and warns without aborting
-on any other value. There is no `--standards`, since no run writes a standard
-into the target.
+still prompts. `--skip` takes `wiki`, `governance`, and `snippets`, and warns
+without aborting on any other value. There is no `--standards`, since no run
+writes a standard into the target.
+
+`--snippets` carries no default. A bare `aitk init` installs no snippets and
+reports the domain as skipped, the same way an explicit `--skip snippets`
+does, both naming `aitk snippets install essentials <target>` as the recovery
+command. `--snippets none` is a distinct, deliberate way to reach the same
+zero-file result while still running the step, which is what lets a scripted
+caller assert "install nothing" without depending on an empty string, which
+`aitk snippets install` refuses.
 
 ## Unguarded tooling primitives
 

package/docs/target-projects.md

@@ -70,7 +70,7 @@ Each diagram entry records the commit and date it was last verified against, and
 
 ### Stack decision
 
-The default path is `base`. `aitk init` on `base` installs base tooling configs, Claude seeds, governance core rules, and snippets, and scaffolds an empty `.claude/wiki/`. Most projects need nothing more.
+The default path is `base`. `aitk init` on `base` installs base tooling configs, Claude seeds, and governance core rules, and scaffolds an empty `.claude/wiki/`. Most projects need nothing more.
 
 Escalate only for real web apps. The `setup-init` skill reads `package.json` and root configs, then picks the matching tooling stack (`vite-react` today) and the matching governance stack (`react`, `astro`, `node`).
 
@@ -84,13 +84,16 @@ Run `aitk tooling list --json` and `aitk gov list --json` to see the current cat
 
 ### Core domains and skips
 
-`aitk init` installs base tooling, Claude workflow, governance, and snippets, and scaffolds `.claude/wiki/`. Governance defaults to the `base` stack, so a bare init carries the rules that route a project. Pass `--stack <name>` to install a framework stack instead.
+`aitk init` installs base tooling, Claude workflow, and governance, and scaffolds `.claude/wiki/`. Governance defaults to the `base` stack, so a bare init carries the rules that route a project. Pass `--stack <name>` to install a framework stack instead.
 
 No standard is written into the project. Each governance rule's authority line names `aitk standards <name>`, which answers from the corpus inside the CLI's own package, and every toolkit skill names the copy in its own plugin root. `aitk markdown audit` needs no standard at all, its ban sets and checkpoints shipping with the package as data.
 
-`governance` and `wiki` are skippable:
+Snippets does not install by default. Pass `--snippets <category>`, such as `--snippets essentials`, to take it. Its own rule describing the `@` reference convention installs alongside it, so a project that declines snippets never receives a rule for a behavior it holds no snippet to exercise.
+
+`governance`, `snippets`, and `wiki` are skippable:
 
 - `--skip governance`: leave `.claude/rules/` empty, so no coding standard loads on a file match. The preview names any `--add` rules the skip drops, and the run prints the `aitk gov install <stack> <path>` command to add rules afterward, carrying those extras so one paste restores what the skip declined.
+- `--skip snippets`: the explicit spelling for what a bare init already does, since `--snippets` carries no default. Both print the `aitk snippets install essentials <path>` command afterward.
 - `--skip wiki`: skip the `.claude/wiki/` scaffold. A target that already carries a root `wiki/` keeps it, since the verb reports that folder rather than migrating it.
 
 The plugin corpus carries runtime behavior rather than reference prose alone, because the pre-publish scan and the branch-slug transform each have a standard of their own, `publish.md` and `slug.md`, cited by the skills that run them.

package/governance/rules/snippets/505-at-references.md

@@ -0,0 +1,9 @@
+---
+description: Execute an @-referenced snippet's instructions immediately using session context
+---
+
+# Snippet reference standards
+
+## Execution
+
+- When a snippet is referenced with `@`, execute its instructions immediately using available session context

package/package.json

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

package/scripts/core/install-check.sh

@@ -67,7 +67,7 @@ mkdir -p "$TARGET_DIR"
 log_info "Initialized git in $TARGET_DIR"
 
 log_step "Run aitk init"
-(cd "$TARGET_DIR" && AITK_NON_INTERACTIVE=1 bun run "$CLONE_DIR/src/cli.ts" init --stack base 2>&1 | pipe_output) || log_error "aitk init failed"
+(cd "$TARGET_DIR" && AITK_NON_INTERACTIVE=1 bun run "$CLONE_DIR/src/cli.ts" init --stack base --snippets essentials 2>&1 | pipe_output) || log_error "aitk init failed"
 log_info "aitk init completed"
 
 log_step "Assert scaffold"
@@ -80,10 +80,12 @@ log_step "Assert scaffold"
 # reads a standard through `aitk standards <name>`, which resolves against the
 # copy inside the package.
 #
-# The snippets path has to name a slug the default preset still carries, since
-# init resolves snippets through `essentials`. Editing that preset without
-# editing this line fails the gate on a correct install.
-for path in "CLAUDE.md" ".claude/snippets/decision-help.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".claude/diagrams/index.md" \
+# Snippets carries no default, so the run above passes `--snippets essentials`
+# explicitly. The snippets path has to name a slug that preset still carries;
+# editing the preset without editing this line fails the gate on a correct
+# install. The rule path confirms the domain's own convention rule installs
+# alongside it, since a target that declined snippets never receives it.
+for path in "CLAUDE.md" ".claude/snippets/decision-help.md" ".claude/rules/snippets/505-at-references.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".claude/diagrams/index.md" \
   ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
   ".claude/rules/core/000-constitution.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then

package/scripts/core/verify.sh

@@ -20,10 +20,14 @@ CHANGED_FILES=""
 SANDBOX_UNDECLARED_CEILING=47
 
 # Rules no stack reaches, space separated and sorted the way `aitk gov list`
-# emits them. Both are opt-in libraries a project may not want, so they are
-# recorded here rather than in a config file: the list is what a reader compares
-# a new arrival against, and a config file would absorb the arrival silently.
-GOV_EXPECTED_UNREFERENCED="260-shadcn 320-tanstack-query"
+# emits them. `260-shadcn` and `320-tanstack-query` are opt-in libraries a
+# project may not want; `505-at-references` ships with no stack on purpose,
+# since a rule under `claude/` would reach every base consumer through the
+# folder-whole entry, and only `aitk snippets install` writes it, alongside
+# the snippets a caller took. All three are recorded here rather than in a
+# config file: the list is what a reader compares a new arrival against, and a
+# config file would absorb the arrival silently.
+GOV_EXPECTED_UNREFERENCED="260-shadcn 320-tanstack-query 505-at-references"
 
 # The retained counts the audit stage compares each run against. Spelled here
 # rather than derived, because this script only ever names the file in a remedy
@@ -292,12 +296,13 @@ main() {
   # A stack entry naming a rule folder takes every rule in it, which is what
   # stops a new rule from needing a second edit to reach a target. The failure
   # it leaves open is a rule authored into a folder no stack names, which
-  # installs for nobody and reports nothing on its own.
+  # `aitk gov install` never reaches on its own, whether or not another domain
+  # installs the file by a different route.
   #
-  # This reports and never fails. Both standing findings are opt-in libraries
-  # this repository ships on purpose, so gating would fail every push over the
-  # deliberate case and teach a reader to route around the stage. Revisit when a
-  # third appears and the pattern is either a library set or an accident.
+  # This reports and never fails. All three standing findings ship this way on
+  # purpose, so gating would fail every push over the deliberate case and teach
+  # a reader to route around the stage. Revisit if the set keeps growing and
+  # the pattern turns out to be an accident rather than a design.
   log_step "Unreferenced rules"
   local gov_json gov_status=0 unreferenced
   gov_json=$(cd "$PROJECT_ROOT" && bun src/cli.ts gov list --json 2>/dev/null) || gov_status=$?
@@ -331,10 +336,10 @@ main() {
     elif [ -z "$unreferenced" ]; then
       log_info "Every rule is reached by a stack"
     elif [ "$unreferenced" = "$GOV_EXPECTED_UNREFERENCED" ]; then
-      log_info "Reached by no stack: $unreferenced (opt-in, install with --add)"
+      log_info "Reached by no stack: $unreferenced (each recorded above with why)"
     else
       log_warn "Reached by no stack: $unreferenced"
-      log_warn "Expected: $GOV_EXPECTED_UNREFERENCED. Name the new rule in a stack, or update GOV_EXPECTED_UNREFERENCED in this script and say why it ships opt-in."
+      log_warn "Expected: $GOV_EXPECTED_UNREFERENCED. Name the new rule in a stack, or update GOV_EXPECTED_UNREFERENCED in this script and say why it reaches no stack."
     fi
   fi
 

package/src/commands/init.ts

@@ -12,7 +12,7 @@ interface InitOptions {
   /** Always present: the option falls back to `DEFAULT_STACK`. */
   readonly stack: string
   readonly add?: string
-  readonly snippets: string
+  readonly snippets?: string
   readonly skip?: string
 }
 

package/src/commands/snippets.ts

@@ -6,6 +6,7 @@ import { BASE_CATEGORY } from '@/snippets/categories'
 import {
   ALL_CATEGORY,
   installSnippets,
+  installSnippetsRule,
   installableCategories,
   resolveSnippets,
 } from '@/snippets/install'
@@ -176,6 +177,9 @@ async function runInstall(
   for (const rel of await installSnippets(resolution.files, resolved)) {
     logAdd(rel)
   }
+  for (const rel of await installSnippetsRule(PROJECT_ROOT, resolved)) {
+    logAdd(rel)
+  }
   await recordStamp(createSnippetsAdapter(PROJECT_ROOT), resolved, new Date())
 
   const { GREEN, NC } = palette(process.stderr)

package/src/init/flags.ts

@@ -29,8 +29,7 @@ export const INIT_OPTIONS: readonly InitOptionSpec[] = [
   {
     key: 'snippets',
     flags: '--snippets <category>',
-    description: "Snippets preset, category, or 'all'",
-    defaultValue: 'essentials',
+    description: "Snippets preset, category, 'none', or 'all'. Omit to skip",
   },
   {
     key: 'skip',

package/src/init/plan.ts

@@ -1,4 +1,4 @@
-export const SKIPPABLE_DOMAINS = ['wiki', 'governance'] as const
+export const SKIPPABLE_DOMAINS = ['wiki', 'governance', 'snippets'] as const
 
 export type SkippableDomain = (typeof SKIPPABLE_DOMAINS)[number]
 
@@ -30,10 +30,23 @@ export interface InitPlan {
 export interface InitFlags {
   readonly stack?: string
   readonly add?: string
-  readonly snippets: string
+  /** Absent when `--snippets` was never passed, which installs none. */
+  readonly snippets?: string
   readonly skip: SkipPlan
 }
 
+/**
+ * Reads why the snippets step will not run, or `undefined` when it will.
+ * Omitting `--snippets` reaches the same skip as `--skip snippets` explicitly,
+ * so a plain `aitk init` installs none and both routes share one recovery
+ * line rather than two behaviors with one spelling each.
+ */
+export function snippetsSkipReason(flags: InitFlags): string | undefined {
+  if (flags.skip.skipped.has('snippets')) return '--skip snippets'
+  if (flags.snippets === undefined) return 'no --snippets given'
+  return undefined
+}
+
 /**
  * Resolves the stack the run will install. An empty `--stack` reads as absent
  * rather than as a way to decline, so the flag carries a real name or nothing
@@ -98,7 +111,11 @@ export function planInit(flags: InitFlags): InitPlan {
     })
   }
 
-  preview.push({ level: 'info', text: `snippets (${flags.snippets})` })
+  if (snippetsSkipReason(flags) !== undefined) {
+    preview.push({ level: 'warn', text: 'snippets (skipped)' })
+  } else {
+    preview.push({ level: 'info', text: `snippets (${flags.snippets})` })
+  }
 
   if (!flags.skip.skipped.has('wiki')) {
     preview.push({

package/src/init/steps.ts

@@ -1,4 +1,4 @@
-import { type InitFlags, resolveStack } from '@/init/plan'
+import { type InitFlags, resolveStack, snippetsSkipReason } from '@/init/plan'
 import type { DomainStep } from '@/init/run'
 
 /** Builds the child-process invocation for one domain. */
@@ -48,11 +48,25 @@ export function buildSteps(
     })
   }
 
-  steps.push({
-    kind: 'run',
-    label: 'Snippets',
-    run: child(['snippets', 'install', flags.snippets, resolved]),
-  })
+  // `snippets === undefined` here can never fire on its own: `snippetsSkipReason`
+  // already returns a reason whenever `flags.snippets` is undefined. It is what
+  // narrows `snippets` to `string` for the child() call below, since TypeScript
+  // cannot narrow a property through a function call.
+  const snippets = flags.snippets
+  const skipReason = snippetsSkipReason(flags)
+  if (skipReason !== undefined || snippets === undefined) {
+    steps.push({
+      kind: 'skip',
+      label: 'Snippets',
+      notice: `Skipped: ${skipReason ?? 'no --snippets given'}. Run 'aitk snippets install essentials ${target}' to install snippets.`,
+    })
+  } else {
+    steps.push({
+      kind: 'run',
+      label: 'Snippets',
+      run: child(['snippets', 'install', snippets, resolved]),
+    })
+  }
 
   if (!flags.skip.skipped.has('wiki')) {
     steps.push({

package/src/snippets/categories.ts

@@ -3,6 +3,8 @@ import { join } from 'node:path'
 import { isDirectory } from '@/target'
 
 export const BASE_CATEGORY = 'base'
+/** A real category resolving to zero entries, for a caller declining on purpose. */
+export const NONE_CATEGORY = 'none'
 
 export function snippetsSourceDir(root: string): string {
   return join(root, 'snippets')
@@ -39,8 +41,13 @@ export function categoryDir(root: string, category: string): string {
  * Tests for a directory rather than mere existence. `snippets/` holds files
  * alongside its category folders, so an argument naming one of them resolves
  * to a real path that cannot be scanned as a category.
+ *
+ * An empty category refuses rather than resolving, since `join(source, '')`
+ * is `source` and would otherwise report the base directory as the category,
+ * widening an unset value to every base entry instead of naming none.
  */
 export function categoryExists(root: string, category: string): boolean {
+  if (category === '') return false
   return isDirectory(categoryDir(root, category))
 }
 

package/src/snippets/install.ts

@@ -7,9 +7,11 @@ import {
   categoryExists,
   listCategories,
   listEntries,
+  NONE_CATEGORY,
   snippetsSourceDir,
 } from '@/snippets/categories'
 import { findPreset, loadPresets } from '@/snippets/presets'
+import { isDirectory } from '@/target'
 
 export const ALL_CATEGORY = 'all'
 
@@ -72,6 +74,15 @@ export function resolveSnippets(
     return { ok: true, step: 'Resolving all categories', files, missing: [] }
   }
 
+  if (category === NONE_CATEGORY) {
+    return {
+      ok: true,
+      step: 'Resolving category: none',
+      files: [],
+      missing: [],
+    }
+  }
+
   const preset = findPreset(root, category)
   if (preset) {
     const files: SnippetFile[] = []
@@ -123,3 +134,39 @@ export async function installSnippets(
 
   return installed
 }
+
+function snippetsRuleSourceDir(root: string): string {
+  return join(root, 'governance', 'rules', 'snippets')
+}
+
+function installedSnippetsRuleDir(target: string): string {
+  return join(target, '.claude', 'rules', 'snippets')
+}
+
+/**
+ * Installs the `@`-reference convention rule alongside the snippets a caller
+ * took. No stack names this folder, so a project that declined snippets never
+ * receives a rule describing a behavior it holds no snippet to exercise.
+ */
+export async function installSnippetsRule(
+  root: string,
+  target: string,
+): Promise<string[]> {
+  const dir = snippetsRuleSourceDir(root)
+  if (!isDirectory(dir)) return []
+
+  const installed: string[] = []
+
+  for (const rel of new Bun.Glob('*.md').scanSync({
+    cwd: dir,
+    onlyFiles: true,
+  })) {
+    await copyPreservingMode(
+      join(dir, rel),
+      join(installedSnippetsRuleDir(target), rel),
+    )
+    installed.push(join('.claude', 'rules', 'snippets', rel))
+  }
+
+  return installed
+}

package/standards/pr.md

@@ -51,6 +51,7 @@ Does not govern:
 - Run the check before writing its line. A `- [ ]` reports a check that has not run rather than one that is planned.
 - Tick the box and state the observed result. `- [x] npm test passes, 42 tests` beats `- [ ] run npm test`.
 - Quote the count or output the run reported, never a figure carried from elsewhere.
+- A ticked box describes the tree as it stands, not as it stood when it was written. A later commit that removes or replaces what it names makes the box false, and the branch that made that commit corrects it in the same pass, the same as any other stale claim in the body.
 - Leave a box unchecked only when a human is required, and name which human and why on the same line.
 - Human-only covers visual or aesthetic judgment, anything needing credentials or a live third-party service, anything needing a second machine or a fresh OS, and judgment about whether a boundary or an abstraction reads correctly. The agent runs everything else.
 - What makes a human required is a capability the agent lacks, never the cost of the run. Authorizing a spend is the operator's and performing the run is not, so an arm the repository ships a harness for gets driven once the operator has cleared the spend, and the box records what it returned.

package/tooling/claude/seeds/CLAUDE.md

@@ -65,10 +65,6 @@
 - When cspell flags a word, rewrite typos. Add real terms to the appropriate dictionary in `cspell.json`.
 - Keep dictionary files sorted alphabetically
 
-## Snippets
-
-- When a snippet is referenced with `@`, execute its instructions immediately using available session context
-
 ## Tasks
 
 - `.claude/tasks/` is gitignored local session scratch, one file per task. Edit freely. No staging or revert before commits.