@erclx/aitk 0.23.0 → 0.25.0

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

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

package/claude/skills/claude-roadmap/references/roadmap.md

@@ -10,6 +10,17 @@ Applies to `.claude/ROADMAP.md`. Sequences the scope from `.claude/REQUIREMENTS.
 
 The roadmap is one scannable table. That is what keeps it distinct from `.claude/tasks/`: the roadmap is an overview read at a glance, while tasks are worked one file at a time.
 
+## Scope
+
+Governs the sequencing document at `.claude/ROADMAP.md`: the version table, its columns, and its lifecycle.
+
+Does not govern:
+
+- What the scope is, which the roadmap sequences rather than defines: `requirements.md`
+- Task files, outcomes, and board state: `tasks.md`
+- Phase-label format and semver discipline: `versioning.md`
+- Rationale for a technical choice: `architecture.md`
+
 ## What goes in
 
 - One row per version, ordered top to bottom by sequence
@@ -20,9 +31,8 @@ The roadmap is one scannable table. That is what keeps it distinct from `.claude
 
 ## What does not go in
 
-- Task breakdown, checkboxes, or per-feature file lists. Those live in `.claude/tasks/` and `.claude/plans/`.
+- Task breakdown, checkboxes, or per-feature file lists
 - Implementation detail, API names, or component references
-- Rationale for tech choices. That belongs in `.claude/ARCHITECTURE.md`.
 - Sentence-long cells. Keep each cell terse so the table stays scannable.
 
 ## Format

package/claude/skills/create-standard/references/snippets.md

@@ -6,6 +6,15 @@ consumers: create-standard
 
 # Snippet reference
 
+## Scope
+
+Governs a snippet file: what one is for, how it is invoked, and the structure of its body.
+
+Does not govern:
+
+- Skill folders, which carry frontmatter, references, and scripts a snippet has none of: `skill.md`
+- Voice, punctuation, and formatting in snippet prose: `prose.md`
+
 ## What a snippet is
 
 A snippet is a short, focused prompt stored as a plain markdown file. Invoke one to insert a prepared instruction into any AI chat without retyping it. Each snippet covers one purpose. If a prompt needs headers or multiple goals, use a system prompt instead.

package/claude/skills/git-branch/references/branch.md

@@ -6,6 +6,17 @@ consumers: git-branch, git-split, git-pr
 
 # Branch reference
 
+## Scope
+
+Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
+
+Does not govern:
+
+- Commit subject format, which shares the type vocabulary: `commit.md`
+- Pull request title and body: `pr.md`
+- Whether a phase label may appear in a branch name: `versioning.md`
+- Deriving an output filename from a branch name, which is a transform the skill running it owns
+
 ## Format
 
 - Structure: `<type>/<description>` or `<type>/<ticket>-<description>`

package/claude/skills/git-commit/references/commit.md

@@ -6,6 +6,16 @@ consumers: git-commit, git-stage
 
 # Commit message reference
 
+## Scope
+
+Governs a git commit message: subject structure, the type and scope vocabulary, and the body.
+
+Does not govern:
+
+- Branch naming, which shares the type vocabulary: `branch.md`
+- Pull request title and body, which share the subject form: `pr.md`
+- Whether a phase label or a semver tag may appear in a subject: `versioning.md`
+
 ## Format
 
 - Structure: `<type>(<scope>): <subject>`
@@ -26,7 +36,7 @@ consumers: git-commit, git-stage
 - `ci`: CI/CD pipeline changes (GitHub Actions)
 - `revert`: revert a previous commit
 
-## Scope
+## Scope vocabulary
 
 - Single lowercase word representing a system component
 - Prefer single word

package/claude/skills/git-issue/references/issue.md

@@ -6,6 +6,16 @@ consumers: git-issue
 
 # Issue reference
 
+## Scope
+
+Governs a tracker issue: its title, its labels, and the sections its body carries.
+
+Does not govern:
+
+- Pull request title and body: `pr.md`
+- Whether a phase label may appear in issue text: `versioning.md`
+- Voice, punctuation, and banned words in issue prose: `prose.md`
+
 ## Title
 
 - Format: `<type>: <subject>`

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

@@ -6,6 +6,17 @@ consumers: git-branch, git-split, git-pr
 
 # Branch reference
 
+## Scope
+
+Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
+
+Does not govern:
+
+- Commit subject format, which shares the type vocabulary: `commit.md`
+- Pull request title and body: `pr.md`
+- Whether a phase label may appear in a branch name: `versioning.md`
+- Deriving an output filename from a branch name, which is a transform the skill running it owns
+
 ## Format
 
 - Structure: `<type>/<description>` or `<type>/<ticket>-<description>`

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

@@ -6,6 +6,17 @@ consumers: git-split, git-pr
 
 # Pull request reference
 
+## Scope
+
+Governs a pull request title and body: their format and the sections the body carries.
+
+Does not govern:
+
+- Commit subject format, which shares the title form: `commit.md`
+- Branch naming: `branch.md`
+- Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
+- Voice, punctuation, and banned words in pull request prose: `prose.md`
+
 ## Title
 
 - Format: `<type>(<scope>): <subject>`

package/claude/skills/git-split/references/branch.md

@@ -6,6 +6,17 @@ consumers: git-branch, git-split, git-pr
 
 # Branch reference
 
+## Scope
+
+Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
+
+Does not govern:
+
+- Commit subject format, which shares the type vocabulary: `commit.md`
+- Pull request title and body: `pr.md`
+- Whether a phase label may appear in a branch name: `versioning.md`
+- Deriving an output filename from a branch name, which is a transform the skill running it owns
+
 ## Format
 
 - Structure: `<type>/<description>` or `<type>/<ticket>-<description>`

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

@@ -6,6 +6,17 @@ consumers: git-split, git-pr
 
 # Pull request reference
 
+## Scope
+
+Governs a pull request title and body: their format and the sections the body carries.
+
+Does not govern:
+
+- Commit subject format, which shares the title form: `commit.md`
+- Branch naming: `branch.md`
+- Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
+- Voice, punctuation, and banned words in pull request prose: `prose.md`
+
 ## Title
 
 - Format: `<type>(<scope>): <subject>`

package/claude/skills/git-stage/references/commit.md

@@ -6,6 +6,16 @@ consumers: git-commit, git-stage
 
 # Commit message reference
 
+## Scope
+
+Governs a git commit message: subject structure, the type and scope vocabulary, and the body.
+
+Does not govern:
+
+- Branch naming, which shares the type vocabulary: `branch.md`
+- Pull request title and body, which share the subject form: `pr.md`
+- Whether a phase label or a semver tag may appear in a subject: `versioning.md`
+
 ## Format
 
 - Structure: `<type>(<scope>): <subject>`
@@ -26,7 +36,7 @@ consumers: git-commit, git-stage
 - `ci`: CI/CD pipeline changes (GitHub Actions)
 - `revert`: revert a previous commit
 
-## Scope
+## Scope vocabulary
 
 - Single lowercase word representing a system component
 - Prefer single word

package/claude/skills/setup-init/SKILL.md

@@ -63,7 +63,7 @@ Before executing, output:
 
 ## Execute
 
-Run the chain in order. Each step's permission dialog is the confirmation gate. Run from the target project's current directory.
+Run the chain in order, starting immediately after the preview. Each step's permission dialog is the confirmation gate. Do not pause for additional confirmation. Run from the target project's current directory.
 
 Step 1: `aitk init` installs base tooling, claude seeds, governance rules, standards, snippets, and wiki.
 

package/docs/agents.md

@@ -163,8 +163,16 @@ matches what the toolkit installed, `customized` when the project edited it,
 when the project authored it, or `drifted` when no stamp covers it. Use `--json`
 for the machine-readable report and `--exit-code` to fail a CI job. Orphaned
 files are excluded from that exit code, since a project-authored rule never
-converges. Attribution needs `.claude/aitk.json`, which every install and sync
-writes. Without it, every difference reports as `drifted`.
+converges. Attribution reads `.claude/aitk.json`, which every install and sync
+writes.
+
+A target installed before stamping shipped has no such file, and the report
+falls back to the toolkit's own git history. Installed content matching any
+version that history ever published proves the file is untouched, so it reports
+`stale` naming the commit it came from, and content matching no published
+version stays `drifted`. A toolkit reached outside a git clone, which is what a
+registry install is, cannot run that fallback and reports
+`historyUnavailable` alongside the unattributed files.
 
 Each domain carries its own toolkit anchor in that file, so syncing one domain
 never advances the revision another measures from, and each reports the upstream
@@ -238,7 +246,7 @@ The record carries every scenario with the arms that declare, plus `totalScenari
 
 `--skills` answers what the scenario count cannot, which is whether anything can fail a given skill. It adds `skills`, `totalSkills`, `asserted`, `shouldBeAsserted`, `exempt`, `staleExemptions`, and `supersededExemptions` to the record, and keeps the scenario view rather than replacing it. The two denominators disagree on purpose: an armed scenario under `infra/` or `tooling/` exercises a CLI domain and pairs with no skill at all.
 
-A skill pairs to a scenario by filename, `<category>-<command>` first and bare `<command>` second, so `claude/setup-init.sh` reaches the `setup-init` skill. `should-be-asserted` is the default and is the work queue for writing arms. `exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
+A skill pairs to a scenario by filename, `<category>-<command>` first and bare `<command>` second, so `claude/setup-init.sh` reaches the `setup-init` skill. `should-be-asserted` is the default rather than a queue to drain, and which of those skills earns an arm is a project decision the census does not make. `exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
 
 `scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.claude/.tmp/sandbox-runs/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit. Stdout carries the same bytes it did before the record existed.
 

package/docs/target-projects.md

@@ -100,7 +100,9 @@ When the toolkit updates, target projects pull changes per domain. There is one
 
 `aitk sync --check <path>` reports what has drifted without writing anything. It splits each difference by cause, which is the question that decides what to do next. A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision and `aitk:claude-seed-sync` is the tool for it. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is what `aitk:migration-standards` handles.
 
-That attribution comes from `.claude/aitk.json`, a stamp every install and sync writes recording a hash per installed file. Each domain holds its own toolkit commit, so syncing governance today does not move the revision standards measures against, and each domain reports the upstream commits touching its own source path. A project that has never synced under a toolkit new enough to write a stamp reports every difference as `drifted`, the unattributed verdict. Running any sync stamps that domain, and the report names the ones still unstamped.
+That attribution comes from `.claude/aitk.json`, a stamp every install and sync writes recording a hash per installed file. Each domain holds its own toolkit commit, so syncing governance today does not move the revision standards measures against, and each domain reports the upstream commits touching its own source path. Running any sync stamps that domain, and the report names the ones still unstamped.
+
+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.
 
 Add `--json` for the machine-readable report, and `--exit-code` to fail a CI job when a target falls behind. Files the project authored itself never count toward that exit code.
 
@@ -110,7 +112,7 @@ Tooling is not covered by the stamp. Reconcile those configs with `aitk tooling
 
 `aitk sync <path>` runs every installed domain's sync in sequence. Safe to run on a cadence. It never touches user-owned seed files. Governance rules in `.claude/rules/`, tooling configs, and reference docs refresh in place. Stale `.claude/GOV.md` from earlier installs is removed.
 
-Standards are the exception inside that run, and the stamp narrows it. A standard the project customized is reported and left alone rather than overwritten. A standard still matching what was installed carries no local edits to lose, so a headless run updates it. On an unstamped project the old blanket rule holds and every drifted standard is left alone. To take the upstream version of a customized file, run `aitk standards sync <path>` interactively, or use `aitk:claude-seed-sync` below to merge section by section.
+Standards are the exception inside that run, and the stamp narrows it. A standard the project customized is reported and left alone rather than overwritten. A standard still matching what was installed carries no local edits to lose, so a headless run updates it. An unstamped project reaches the same split through the history fallback, so a headless run updates every standard it can prove untouched and refuses while any file resists attribution. To take the upstream version of a customized file, run `aitk standards sync <path>` interactively, or use `aitk:claude-seed-sync` below to merge section by section.
 
 ### Targeted
 

package/package.json

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

package/src/commands/sync.ts

@@ -99,7 +99,11 @@ function renderCheck(report: CheckReport): void {
     logStep(domain.domain)
 
     if (domain.commit === undefined) {
-      logWarn('Not stamped. Drift below is reported unattributed.')
+      logWarn(
+        domain.historyUnavailable
+          ? 'Not stamped, and this toolkit has no git history. Drift below is reported unattributed.'
+          : 'Not stamped. Drift below is attributed from toolkit history.',
+      )
     } else {
       logInfo(`Synced from ${domain.commit} on ${domain.syncedAt}`)
     }

package/src/sync/check.ts

@@ -54,6 +54,11 @@ export interface DomainReport {
   readonly counts: StateCounts
   readonly entries: readonly ScanEntry[]
   readonly upstream: readonly UpstreamCommit[]
+  /**
+   * Separates a toolkit that could not attribute from one that attributed and
+   * found a local edit. Only the first is a capability the install lacks.
+   */
+  readonly historyUnavailable: boolean
 }
 
 export interface UpstreamCommit {
@@ -145,6 +150,7 @@ async function buildDomainReport(
     syncedAt: record?.syncedAt,
     counts: countStates(plan.entries),
     entries: plan.entries,
+    historyUnavailable: plan.historyUnavailable,
     upstream:
       since === undefined
         ? []

package/src/sync/engine.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { rm } from 'node:fs/promises'
 import { isAbsolute, relative, resolve } from 'node:path'
 import { copyPreservingMode } from '@/copy'
+import { findInstalledOrigin, readHistoryIndex } from '@/sync/history'
 import {
   type DomainHashes,
   hashFile,
@@ -74,12 +75,16 @@ export type EntryState =
 export interface ScanEntry {
   readonly state: EntryState
   readonly rel: string
+  /** Toolkit revision this file's content came from, when history proved it. */
+  readonly since?: string
 }
 
 export interface SyncPlan {
   readonly entries: readonly ScanEntry[]
   readonly retired: readonly RetiredSurface[]
   readonly changes: readonly SyncChange[]
+  /** Set when a file needed history to attribute it and this toolkit has none. */
+  readonly historyUnavailable: boolean
 }
 
 /**
@@ -156,6 +161,7 @@ export function listInstalled(root: string, target: string): InstalledFile[] {
 export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
   const entries: ScanEntry[] = []
   const changes: SyncChange[] = []
+  const unattributed: UnattributedFile[] = []
 
   const hashes = stampedHashes(readStamp(target), adapter.stamp?.domain)
   const walked = new Set<string>()
@@ -176,7 +182,12 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
       continue
     }
 
-    entries.push({ state: attribute(hashes, file), rel: file.rel })
+    const state = attribute(hashes, file)
+    if (state === 'drifted') {
+      unattributed.push({ index: entries.length, source, path: file.path })
+    }
+
+    entries.push({ state, rel: file.rel })
     changes.push({
       kind: 'copy',
       source,
@@ -185,6 +196,8 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
     })
   }
 
+  const historyUnavailable = recoverAttribution(adapter, entries, unattributed)
+
   entries.push(...strandedByRelocation(target, hashes, walked))
 
   const retired = adapter.collectRetired?.(target) ?? []
@@ -192,7 +205,53 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
     changes.push({ kind: 'delete', dest: surface.path, rel: surface.rel })
   }
 
-  return { entries, retired, changes }
+  return { entries, retired, changes, historyUnavailable }
+}
+
+interface UnattributedFile {
+  readonly index: number
+  readonly source: string
+  readonly path: string
+}
+
+/**
+ * Second pass over the files the stamp could not attribute, which is every file
+ * in a target installed before stamping shipped. Matching the installed content
+ * against the toolkit's own history recovers the fact a stamp would have held,
+ * and a file matching no published version stays unattributed.
+ *
+ * Runs as one git call for the whole domain rather than one per file, and only
+ * when the first pass left something to attribute. Reports whether history was
+ * readable at all, so a registry install can say why it fell short instead of
+ * reporting every file as a local edit.
+ */
+function recoverAttribution(
+  adapter: SyncAdapter,
+  entries: ScanEntry[],
+  unattributed: readonly UnattributedFile[],
+): boolean {
+  const toolkitRoot = adapter.stamp?.toolkitRoot
+  if (toolkitRoot === undefined || unattributed.length === 0) return false
+
+  const index = readHistoryIndex(
+    toolkitRoot,
+    unattributed.map((file) => relative(toolkitRoot, file.source)),
+  )
+
+  if (index === undefined) return true
+
+  for (const file of unattributed) {
+    const since = findInstalledOrigin(
+      index,
+      relative(toolkitRoot, file.source),
+      file.path,
+    )
+
+    if (since === undefined) continue
+    entries[file.index] = { ...entries[file.index], state: 'stale', since }
+  }
+
+  return false
 }
 
 export async function applyChanges(
@@ -314,7 +373,12 @@ function report(adapter: SyncAdapter, plan: SyncPlan): void {
   for (const entry of plan.entries) {
     if (entry.state === 'matching') logInfo(entry.rel)
     else if (entry.state === 'drifted') logWarn(entry.rel)
-    else if (entry.state === 'stale') logWarn(`${entry.rel} (toolkit updated)`)
+    else if (entry.state === 'stale')
+      logWarn(
+        entry.since === undefined
+          ? `${entry.rel} (toolkit updated)`
+          : `${entry.rel} (toolkit updated since ${entry.since.slice(0, 7)})`,
+      )
     else if (entry.state === 'customized')
       logWarn(`${entry.rel} (locally customized)`)
     else if (entry.state === 'stranded')
@@ -325,6 +389,12 @@ function report(adapter: SyncAdapter, plan: SyncPlan): void {
   for (const surface of plan.retired) {
     logWarn(surface.notice)
   }
+
+  if (plan.historyUnavailable) {
+    logWarn(
+      'Attribution unavailable: this toolkit has no git history to match against.',
+    )
+  }
 }
 
 function sameContent(left: string, right: string): boolean {

package/src/sync/history.ts

@@ -0,0 +1,123 @@
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { sep } from 'node:path'
+import { execaSync } from 'execa'
+import { gitEnv } from '@/git-env'
+
+/** Blob SHA to the newest commit whose post-image for that path held it. */
+export type PathHistory = ReadonlyMap<string, string>
+
+/** Source path relative to the toolkit root, to that path's known blobs. */
+export type HistoryIndex = ReadonlyMap<string, PathHistory>
+
+const EMPTY_BLOB = '0000000000000000000000000000000000000000'
+
+/**
+ * Git's own object name for a file's contents: sha1 over `blob <len>\0` and the
+ * bytes. Computed here rather than shelled out to `git hash-object`, which would
+ * cost a process per file inside the attribution pass.
+ *
+ * A repository normalizing line endings on checkout stores a blob the working
+ * tree never holds, so this returns a name that matches no historical version.
+ * The caller treats an unmatched file as unattributed, which is the safe label.
+ */
+export function gitBlobHash(content: Buffer): string {
+  const header = Buffer.from(`blob ${content.length}\0`, 'utf8')
+  return createHash('sha1').update(header).update(content).digest('hex')
+}
+
+/**
+ * Reads `--raw` log output into blob-to-commit maps, one per path.
+ *
+ * Reverse-chronological input means the first commit naming a blob is the
+ * newest that produced it, so an existing key is never overwritten. Content
+ * reverted and restored therefore reports the recent commit rather than the
+ * original, which is the one an operator can act on.
+ */
+export function parseRawLog(output: string): HistoryIndex {
+  const index = new Map<string, Map<string, string>>()
+  let commit = ''
+
+  for (const line of output.split('\n')) {
+    if (line === '') continue
+
+    if (!line.startsWith(':')) {
+      commit = line.trim()
+      continue
+    }
+
+    const [meta, path] = line.split('\t')
+    if (path === undefined || commit === '') continue
+
+    const blob = meta.trim().split(/\s+/)[3]
+    if (blob === undefined || blob === EMPTY_BLOB) continue
+
+    const blobs = index.get(path) ?? new Map<string, string>()
+    if (!blobs.has(blob)) blobs.set(blob, commit)
+    index.set(path, blobs)
+  }
+
+  return index
+}
+
+/**
+ * Every historical version of the given toolkit-relative paths, or `undefined`
+ * when this toolkit has no history to read. A package installed from the
+ * registry ships source without `.git`, so absence is an ordinary state rather
+ * than a failure, and the caller degrades to the unattributed path.
+ *
+ * Renames are disabled so a raw line always carries exactly one path. Detection
+ * would emit a two-path form that the parser would read as an unknown blob.
+ */
+export function readHistoryIndex(
+  toolkitRoot: string,
+  paths: readonly string[],
+): HistoryIndex | undefined {
+  if (paths.length === 0) return new Map()
+
+  const result = execaSync(
+    'git',
+    [
+      '-C',
+      toolkitRoot,
+      'log',
+      '--all',
+      '--raw',
+      '--no-renames',
+      '--no-abbrev',
+      '--relative',
+      '--format=%H',
+      '--',
+      ...paths.map(toRepoPath),
+    ],
+    { reject: false, env: gitEnv(), extendEnv: false },
+  )
+
+  return result.exitCode === 0 ? parseRawLog(result.stdout) : undefined
+}
+
+/**
+ * Git prints and accepts posix separators on every platform, so a Windows
+ * caller's `relative()` output has to be converted before it can match a path
+ * the log emitted.
+ */
+function toRepoPath(path: string): string {
+  return path.split(sep).join('/')
+}
+
+/**
+ * The commit whose version of `sourceRel` matches what sits at `installedPath`.
+ * A match proves the file is untouched since it was installed, so the toolkit is
+ * what moved. No match means the content matches nothing this toolkit ever
+ * published, which is a local edit and stays unattributed.
+ */
+export function findInstalledOrigin(
+  index: HistoryIndex,
+  sourceRel: string,
+  installedPath: string,
+): string | undefined {
+  const blobs = index.get(toRepoPath(sourceRel))
+  if (blobs === undefined) return undefined
+
+  return blobs.get(gitBlobHash(readFileSync(installedPath)))
+}

package/standards/architecture.md

@@ -7,6 +7,16 @@ description: Shape and content rules for .claude/ARCHITECTURE.md
 
 Applies to `.claude/ARCHITECTURE.md`. Describes the system shape and the decisions behind it, not a tutorial, setup guide, or implementation walkthrough. Pair it with `CLAUDE.md`: principles live there, patterns and decisions live here. Update when a decision is made or a risk is resolved.
 
+## Scope
+
+Governs the system-shape document at `.claude/ARCHITECTURE.md`: the overview, the decision entries, and the open risks.
+
+Does not govern:
+
+- Per-domain structure and narrative: `context.md`
+- Setup commands and install instructions: `readme.md`
+- Product scope, goals, and non-goals: `requirements.md`
+
 ## What goes in
 
 - A high-level overview of how the system is structured and why
@@ -15,8 +25,6 @@ Applies to `.claude/ARCHITECTURE.md`. Describes the system shape and the decisio
 
 ## What does not go in
 
-- Per-domain structure and narrative. That belongs in `.claude/context/<domain>.md`, one file per domain.
-- Setup commands and install instructions. Those live in the README.
 - How individual functions work line by line. The code carries its own behavior.
 - Full type definitions. They live in code. Reference the shape conceptually if needed.
 

package/standards/bundled/branch.md

@@ -6,6 +6,17 @@ consumers: git-branch, git-split, git-pr
 
 # Branch reference
 
+## Scope
+
+Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
+
+Does not govern:
+
+- Commit subject format, which shares the type vocabulary: `commit.md`
+- Pull request title and body: `pr.md`
+- Whether a phase label may appear in a branch name: `versioning.md`
+- Deriving an output filename from a branch name, which is a transform the skill running it owns
+
 ## Format
 
 - Structure: `<type>/<description>` or `<type>/<ticket>-<description>`

package/standards/bundled/commit.md

@@ -6,6 +6,16 @@ consumers: git-commit, git-stage
 
 # Commit message reference
 
+## Scope
+
+Governs a git commit message: subject structure, the type and scope vocabulary, and the body.
+
+Does not govern:
+
+- Branch naming, which shares the type vocabulary: `branch.md`
+- Pull request title and body, which share the subject form: `pr.md`
+- Whether a phase label or a semver tag may appear in a subject: `versioning.md`
+
 ## Format
 
 - Structure: `<type>(<scope>): <subject>`
@@ -26,7 +36,7 @@ consumers: git-commit, git-stage
 - `ci`: CI/CD pipeline changes (GitHub Actions)
 - `revert`: revert a previous commit
 
-## Scope
+## Scope vocabulary
 
 - Single lowercase word representing a system component
 - Prefer single word

package/standards/bundled/issue.md

@@ -6,6 +6,16 @@ consumers: git-issue
 
 # Issue reference
 
+## Scope
+
+Governs a tracker issue: its title, its labels, and the sections its body carries.
+
+Does not govern:
+
+- Pull request title and body: `pr.md`
+- Whether a phase label may appear in issue text: `versioning.md`
+- Voice, punctuation, and banned words in issue prose: `prose.md`
+
 ## Title
 
 - Format: `<type>: <subject>`

package/standards/bundled/pr.md

@@ -6,6 +6,17 @@ consumers: git-split, git-pr
 
 # Pull request reference
 
+## Scope
+
+Governs a pull request title and body: their format and the sections the body carries.
+
+Does not govern:
+
+- Commit subject format, which shares the title form: `commit.md`
+- Branch naming: `branch.md`
+- Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
+- Voice, punctuation, and banned words in pull request prose: `prose.md`
+
 ## Title
 
 - Format: `<type>(<scope>): <subject>`

package/standards/bundled/roadmap.md

@@ -10,6 +10,17 @@ Applies to `.claude/ROADMAP.md`. Sequences the scope from `.claude/REQUIREMENTS.
 
 The roadmap is one scannable table. That is what keeps it distinct from `.claude/tasks/`: the roadmap is an overview read at a glance, while tasks are worked one file at a time.
 
+## Scope
+
+Governs the sequencing document at `.claude/ROADMAP.md`: the version table, its columns, and its lifecycle.
+
+Does not govern:
+
+- What the scope is, which the roadmap sequences rather than defines: `requirements.md`
+- Task files, outcomes, and board state: `tasks.md`
+- Phase-label format and semver discipline: `versioning.md`
+- Rationale for a technical choice: `architecture.md`
+
 ## What goes in
 
 - One row per version, ordered top to bottom by sequence
@@ -20,9 +31,8 @@ The roadmap is one scannable table. That is what keeps it distinct from `.claude
 
 ## What does not go in
 
-- Task breakdown, checkboxes, or per-feature file lists. Those live in `.claude/tasks/` and `.claude/plans/`.
+- Task breakdown, checkboxes, or per-feature file lists
 - Implementation detail, API names, or component references
-- Rationale for tech choices. That belongs in `.claude/ARCHITECTURE.md`.
 - Sentence-long cells. Keep each cell terse so the table stays scannable.
 
 ## Format

package/standards/bundled/snippets.md

@@ -6,6 +6,15 @@ consumers: create-standard
 
 # Snippet reference
 
+## Scope
+
+Governs a snippet file: what one is for, how it is invoked, and the structure of its body.
+
+Does not govern:
+
+- Skill folders, which carry frontmatter, references, and scripts a snippet has none of: `skill.md`
+- Voice, punctuation, and formatting in snippet prose: `prose.md`
+
 ## What a snippet is
 
 A snippet is a short, focused prompt stored as a plain markdown file. Invoke one to insert a prepared instruction into any AI chat without retyping it. Each snippet covers one purpose. If a prompt needs headers or multiple goals, use a system prompt instead.

package/standards/context.md

@@ -7,6 +7,17 @@ description: Shape and content rules for .claude/context/<domain>.md entries
 
 Applies to per-domain narrative entries under `.claude/context/`. Skip for `index.md`, which is regenerated by `aitk indexes regen`.
 
+## Scope
+
+Governs per-domain narrative entries under `.claude/context/`: their structure, the decisions and gotchas they carry, and what they leave to the code.
+
+Does not govern:
+
+- Cross-domain decisions and system-wide risks: `architecture.md`
+- Product scope, goals, and non-goals: `requirements.md`
+- Path-scoped coding rules: `rule.md`
+- Diagrams and wireframes, which answer structure and layout questions an entry hands off: `diagrams.md` and `wireframes.md`
+
 ## Organizing principle
 
 Weight the entry toward what cannot be re-derived from the repo. That single rule sorts every section below.

package/standards/design.md

@@ -7,6 +7,15 @@ description: Shape and content rules for .claude/DESIGN.md
 
 Applies to `.claude/DESIGN.md`. Captures visual intent and the decisions behind how things look, not a style guide, component spec, or framework reference. Update when a visual decision is made or a rule changes.
 
+## Scope
+
+Governs the visual-intent document at `.claude/DESIGN.md`: tokens described as intent, layout constraints, and the omissions that keep visual scope closed.
+
+Does not govern:
+
+- Screen layout, on-screen copy, and interaction intent: `wireframes.md`
+- Per-domain implementation narrative: `context.md`
+
 ## What goes in
 
 - Tokens described as intent ("mid gray, muted text"), not computed values. Exact values live in code.
@@ -17,7 +26,6 @@ Applies to `.claude/DESIGN.md`. Captures visual intent and the decisions behind
 ## What does not go in
 
 - CSS classes, computed values, component filenames, and prop names. Those live in code.
-- UX copy and interaction flows. Those live in the wireframes.
 - Anything that needs updating every time the code is refactored
 
 ## Format

package/standards/diagrams.md

@@ -9,6 +9,17 @@ Applies to per-kind entries under `.claude/diagrams/`. Skip for `index.md`, whic
 
 A diagram entry answers one question about the system with one or more Mermaid diagrams and the prose that makes them readable. It is not a rendering of the file tree. The check for any single line: does it tell a reader something the code layout would not have told them? If not, it belongs in `.claude/context/`.
 
+## Scope
+
+Governs per-kind diagram entries under `.claude/diagrams/`: which question each answers, the Mermaid source, the accessibility fields, and the explanation prose beneath. It states the voice for that prose, which is the yield `prose.md` grants a surface whose own standard sets one.
+
+Does not govern:
+
+- Punctuation, formatting, and language in explanation prose and node labels: `prose.md`, whose bans the yield does not lift
+- The mechanism behind any component a diagram draws: `context.md`
+- UI layout, on-screen copy, and interaction intent: `wireframes.md`
+- The decision record a components diagram is drawn from: `architecture.md`
+
 ## What a working entry looks like
 
 An entry works when a reader who has not opened the repository can answer its question:
@@ -82,7 +93,7 @@ A second entry for one kind takes a suffixed name (`request-flow-admin.md`) and
 - Do not duplicate prose across entries. An entry that restates its neighbor has taken the neighbor's job.
 - The audience is mixed, so vocabulary runs as a gradient across the set. `System context` assumes no knowledge of the repository. `Deployment` may assume the reader has read the others.
 
-This section states the voice for the surface, which is what claims the yield `standards/prose.md` grants to a surface whose own standard sets it. Explanation prose is pedagogical here and the default developer-facing voice does not apply. The yield covers voice alone. Punctuation, formatting, and language bans stay in force, and the standards-audit hook enforces them on every write.
+This section states the voice for the surface, which is what claims the yield `prose.md` grants to a surface whose own standard sets it. Explanation prose is pedagogical here and the default developer-facing voice does not apply. The yield covers voice alone. Punctuation, formatting, and language bans stay in force.
 
 ## Verification
 
@@ -109,5 +120,5 @@ Reference the context entry by path when a reader needs the mechanism. The diagr
 - `System context` has no named source signal beyond `.claude/REQUIREMENTS.md`, so nothing tells a session it went stale. Re-read it when the boundary or the set of external dependencies moves.
 - The `claude-docs` sweep watches two things and writes frontmatter only. It appends `stale` when a path an entry cites leaves the tree, and it stubs a kind when a diff adds the source signal that kind is drawn from. Diagram bodies and explanation paragraphs are off limits to it, because a change that removes a module does not carry the new correct shape of the picture.
 - That watch samples thinly. It sees the one or two paths an entry happened to cite and nothing else, so a change elsewhere leaves the entry looking current. `verified` is what covers the gap, and an entry whose date sits far behind the branch is due a read whether or not anything flagged it.
-- Mermaid blocks are inside fenced code, so the prose-standards hook ignores them. The explanation paragraphs around them are still prose. Follow `standards/prose.md`.
+- The explanation paragraphs around a Mermaid block are prose and follow `prose.md`. The fenced block itself is not, which is why a check scoped to prose is the wrong thing to rely on for what sits inside it.
 - The punctuation bans still apply to node and subgraph labels, and nothing checks them there. An em dash in a label passes every gate the repository has, so read the labels before shipping the entry.

package/standards/prose.md

@@ -7,6 +7,17 @@ description: Voice, structure, formatting, and language rules for reference mark
 
 Applies to markdown reference docs, READMEs, and inline documentation in repos. It is the default voice for `.md` files and yields to any surface with its own voice, such as blogs, emails, changelogs, or commit messages. It also yields wherever another standard states the voice for the surface it governs, which is how a surface claims the exemption without this file having to name it. The yield covers voice alone. Punctuation, formatting, and language rules below stay in force on every surface, including the surfaces no automated check reaches, which is what the scan below is for.
 
+## Scope
+
+Governs voice, punctuation, formatting, and word choice wherever prose is written. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and yields on voice alone where that standard states one.
+
+Does not govern:
+
+- What sections a document has, or what belongs in each: the standard for that document type
+- Which frontmatter fields a document carries, which is that standard's own subject. This file governs the wording of a `title` and a `description` and nothing else about them.
+- Phase-label and semver discipline: `versioning.md`
+- Code style and language conventions, which are governance rules rather than a standard
+
 ## Voice
 
 - Write for a developer who is scanning, not studying. Every sentence should be understandable on first read.

package/standards/readme.md

@@ -9,6 +9,15 @@ Applies to every `README.md`. The `## Voice` section states the voice for a repo
 
 The reader is what changes. Reference prose serves someone who already committed to the project and is scanning for a fact. A root README meets someone deciding whether to commit at all, and it is often the only file they read.
 
+## Scope
+
+Governs every `README.md`: voice, heading structure, required and optional sections, badge selection, and what the page links out to instead of carrying.
+
+Does not govern:
+
+- Punctuation, formatting, spelling, and banned words in README prose: `prose.md`, which yields the voice and keeps the rest
+- Product scope and goals: `requirements.md`
+
 ## Voice
 
 Scoped to the README at a repository root. A nested README documenting a folder, a harness, or an internal tool keeps the reference voice in `prose.md`, since its reader has already committed and arrived looking for a fact.

package/standards/requirements.md

@@ -7,6 +7,16 @@ description: Shape and content rules for .claude/REQUIREMENTS.md
 
 Applies to `.claude/REQUIREMENTS.md`. Describes what the product does and why, not how it works. Update when scope changes, goals shift, or a non-goal is promoted to a feature.
 
+## Scope
+
+Governs the product-scope document at `.claude/REQUIREMENTS.md`: problem, goals, non-goals, MVP features, distribution, stack, and constraints.
+
+Does not govern:
+
+- Rationale for a technical choice: `architecture.md`
+- Sequencing the scope into ordered versions: `roadmap.md`
+- Per-domain structure and narrative: `context.md`
+
 ## What goes in
 
 - The problem being solved and for whom
@@ -19,7 +29,6 @@ Applies to `.claude/REQUIREMENTS.md`. Describes what the product does and why, n
 ## What does not go in
 
 - Implementation details, API names, or internal component references
-- Rationale for tech choices. That belongs in `.claude/ARCHITECTURE.md`.
 - Anything that describes how a feature is built rather than what it does
 
 ## Sections

package/standards/rule.md

@@ -9,6 +9,16 @@ description: Rule frontmatter, body shape, and voice for .claude/rules files
 
 Rules give Claude Code coding constraints scoped to file paths. Claude Code discovers `.claude/rules/**/*.md` at session start. A rule with no `paths:` field always applies, at the same priority as `CLAUDE.md`. A rule with `paths:` applies when Claude reads a file matching the glob. Author one rule per topic so the scope stays precise.
 
+## Scope
+
+Governs governance rules under `.claude/rules/`: their location, numbering, frontmatter, and body shape.
+
+Does not govern:
+
+- Authoring conventions for a document type, which are standards rather than rules. A rule points at the standard that owns one and never restates it.
+- Skill folders and skill frontmatter: `skill.md`
+- Cross-domain behavior rules, which live in `CLAUDE.md` at the project root
+
 ## Location
 
 - Rules live at `.claude/rules/<subdirectory>/<n>-<slug>.md`

package/standards/skill.md

@@ -9,6 +9,17 @@ description: Claude skill structure and authoring rules
 
 Skills give Claude Code domain-specific constraints and rules inline, so it can act immediately without reading all docs. Each skill body contains actionable rules for its domain. Full reference docs are the fallback for edge cases and deeper context. Skills use progressive disclosure: Claude reads only frontmatter at session start (~100 tokens each), matches a query against descriptions, then loads the full skill body.
 
+## Scope
+
+Governs a skill folder as one artifact: `SKILL.md`, its optional sibling `REQUIREMENT.md`, and the bundled `references/`, `scripts/`, and `assets/` beside them.
+
+Does not govern:
+
+- Path-scoped coding rules, which load on a file match rather than on a request match: `rule.md`
+- Single-purpose chat prompts carrying no frontmatter, references, or scripts: `snippets.md`
+- Voice, punctuation, and formatting in a skill body: `prose.md`
+- The domain conventions a skill cites, each of which belongs to the standard that owns it
+
 ## Skill types
 
 Pick the type before writing. It decides the body shape.

package/standards/standard.md

@@ -9,22 +9,42 @@ Applies to each authored standard in the folder. Skip for `index.md`, which is g
 
 ## Overview
 
-A standard is a target-facing authoring convention for one document type. It installs into a project under `.claude/standards/` and is consumed by skills and developers alike. This file governs itself, so every rule below applies to it.
+A standard is a target-facing authoring convention for one document type, or for one attribute carried across every document. It installs into a project under `.claude/standards/` and is consumed by skills and developers alike. This file governs itself, so every rule below applies to it.
+
+## Scope
+
+Governs what an authored standard contains: its stated jurisdiction, success criterion, frontmatter, structure, and rule phrasing.
+
+Does not govern:
+
+- The voice, punctuation, and formatting a standard is written in: `prose.md`
+- The shape of any artifact a standard governs, which is that standard's own subject
 
 ## What a working standard looks like
 
 A standard answers these questions. Each can be answered wrong, which is what makes them a test rather than a preamble.
 
-- Which single document type does this govern, and where does that document live?
+- Which single document type or attribute does this govern, and where does it apply?
 - Can an author who has seen no example produce a conforming document from this file alone?
 - Does every rule state a shape the document must have, rather than a fact about the repository that happens to store it?
 - What does a conforming document achieve, stated so a reviewer can call one non-conforming without appealing to taste?
 
 A standard failing these questions is non-conforming even when it satisfies every shape rule below.
 
-## Scope
+## Scoping rules
+
+### Declaring scope
+
+- Govern one document type per standard, or one attribute across every document. Split unrelated conventions into separate files.
+- Open with a `## Scope` section stating what the standard governs and what it does not, placed above the shape rules. A standard that specifies shape exhaustively and jurisdiction nowhere cannot refuse a rule, so the rule with no obvious owner lands in whichever standard sits nearest.
+- Write it as one line naming the artifact or attribute and where it applies, then a `Does not govern:` list. Give each entry the excluded concern and the owner it goes to. Name a sibling standard by bare filename, since standards install as siblings, and name the surface instead where the owner is one, such as a coding rule, a project policy, or the code.
+- Cut an entry that names no owner at all. It is either excluding something nothing was going to claim, or it is a content exclusion, which the rule below sends to the shape rules instead.
+- Declare a boundary from both sides. A yield, an exemption, or a handoff stated in one standard alone is never checked against the standard on the other side of it, which is how two files come to claim the same rule or neither does.
+- Separate a jurisdiction exclusion from a content exclusion. The first names a concern another standard owns and belongs in `## Scope`. The second names what does not belong inside the document and stays with the shape rules. Merging them puts a boundary claim where no sibling will read it.
+- Stay silent on a section the standard holds today but should not own. Claiming it makes the scope statement false the moment it moves, and the mismatch is the evidence that moves it.
+
+### Staying inside it
 
-- Govern one document type per standard. Split unrelated conventions into separate files.
 - Name no path, filename, or folder outside the document type the standard governs. A standard reaches projects whose layout is their own, so a path borrowed from the authoring repository is wrong in a target and nothing reports it.
 - State the rule, never the mechanism enforcing it. Hooks, scripts, checks, and skill catalogs are facts about one repository. Name the condition the document must meet and let the enforcing surface name its own case.
 - Invent inline examples rather than citing a real file elsewhere in the project. A cited file moves or is deleted and the standard goes stale in silence.

package/standards/tasks.md

@@ -9,6 +9,17 @@ Applies to `.claude/tasks/`. Tracks what is being built and why, at the level of
 
 The folder is gitignored. Board state changes when work ships rather than when a branch is written, so committing it would put a claim about the future into the diff of an unrelated pull request. The git log records what shipped.
 
+## Scope
+
+Governs the task board under `.claude/tasks/`: folder layout, filenames, frontmatter, file format, origin lines, and archiving.
+
+Does not govern:
+
+- Phase-label format and which surfaces a label may appear on: `versioning.md`
+- Sequencing across versions and why the order is what it is: `roadmap.md`
+- Architectural reasoning that outlives a task: `architecture.md`
+- When a project opens a task at all, which is project policy rather than a shape rule
+
 ## Layout
 
 ```plaintext

package/standards/versioning.md

@@ -7,6 +7,17 @@ description: Phase label vs semver discipline across tasks, PRs, reviews, issues
 
 Two namespaces, kept separate.
 
+## Scope
+
+Governs the two version namespaces, phase labels and semver tags, and which surfaces each may appear on. It is an attribute standard rather than a document-type one, so it applies wherever either namespace is written.
+
+Does not govern:
+
+- The format of a phase label, which is project-specific by the rule below
+- Task filenames and board layout: `tasks.md`
+- Commit subject, branch name, and pull request title format: `commit.md`, `branch.md`, and `pr.md`
+- Voice, punctuation, and formatting in any text carrying a label: `prose.md`
+
 ## Phase labels
 
 Internal coordination vocabulary used in the task board and chat.

package/standards/wireframes.md

@@ -9,6 +9,16 @@ Applies to per-surface entries under `.claude/wireframes/`. Skip for `index.md`,
 
 A wireframe file captures the spatial layout and interaction intent of one UI surface. It is not an implementation log. The check for any single line: would it still be true if the surface were rebuilt in a different framework? If not, it belongs in `.claude/context/`.
 
+## Scope
+
+Governs per-surface wireframe entries under `.claude/wireframes/`: layout, variants, on-screen copy, and interaction intent.
+
+Does not govern:
+
+- Tokens, typography, spacing, and the rest of the visual system: `design.md`
+- The mechanism behind a surface: `context.md`
+- Voice, punctuation, and formatting in wireframe prose: `prose.md`
+
 ## What a working wireframe looks like
 
 A wireframe works when someone can rebuild the surface from it without opening the components:
@@ -64,4 +74,4 @@ Reference the context entry from the wireframe by path when a reader needs the m
 ## Maintenance
 
 - When a surface's layout or interaction changes, update its wireframe file in the same PR. A wireframe showing a defunct layout is worse than none.
-- ASCII blocks sit inside fenced code, so the prose-standards hook ignores them. The Behavior and Copy prose around them is still prose. Follow `standards/prose.md`.
+- The Behavior and Copy prose around an ASCII block is prose and follows `prose.md`. The fenced block itself is not, so a check scoped to prose is the wrong thing to rely on for what sits inside it.