@erclx/aitk 0.84.0 → 0.86.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.84.0",
+  "version": "0.86.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/commands.md

@@ -47,7 +47,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | ----------- | --------------------------------------------------------------------------- |
 | `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`      |
 | `snippets`  | `list`, `install`, `sync`, `create`                                         |
-| `standards` | `list`, `install`, `sync`                                                   |
+| `standards` | `list`, `install`, `sync`, `<name>`                                         |
 | `gov`       | `list`, `install`, `sync`, `build`                                          |
 | `claude`    | `init`, `sync`, `seeds list`, `skills list`, `skills audit`, `setup [dest]` |
 | `wiki`      | `init`                                                                      |

package/docs/agents/markdown-audit.md

@@ -27,7 +27,13 @@ A bare run measures every markdown file git lists, tracked plus untracked-and-no
 
 ## Where the rules come from
 
-Both ban sets and all five checkpoints are read out of the standards per run, resolved under `.claude/standards/` first and the authoring root second, so a target project measures against the copy it actually has. Holding the lists in code was the alternative and it puts each ban in two places, where an author adding one gets no enforcement until someone edits TypeScript.
+Both ban sets and all five checkpoints are read out of the standards per run, resolved under `.claude/standards/` first, the authoring root second, and the corpus inside the `aitk` package last, so a target project measures against the copy it actually has and a project that installed none is measured all the same. Holding the lists in code was the alternative and it puts each ban in two places, where an author adding one gets no enforcement until someone edits TypeScript.
+
+A project copy wins wherever one exists. An installed standard is a seed a project edits, so a package copy overriding it would discard that edit with nothing said, and the fallback answers absence rather than staleness. The package copy is reachable because `package.json` ships `standards/` beside the code doing the reading, which is what leaves the install optional for every machine consumer.
+
+The report names the copy it read on every run, spelling a package copy under `<aitk>/` rather than as a path anything would join to a project root. A published package can lag the toolkit a session reads from, the same two-speed skew `.claude/ARCHITECTURE.md` records between the plugin cache and the CLI, and naming the source is what keeps that diagnosable instead of invisible.
+
+`aitk standards <name>` resolves the same three roots in the same order and prints the standard, so the human catalog reads without a project copy on disk too.
 
 The trade is a reader of prose that a reformat can break. `src/markdown/bans.test.ts` answers it by asserting the parsed sets against the shipped standards, so a rewrite that narrows a set fails there rather than passing quietly. A checkpoint falls back per number rather than per file, and the depth legend names every checkpoint that fell back on the run that used one.
 
@@ -116,7 +122,9 @@ Four surfaces read the ban sets and two of them go through this verb. `.claude/h
 
 The other two read the standards directly and neither is a consolidation left half done. `claude/skills/claude-standards-audit/SKILL.md` greps the banned tokens agent-side, which is a session reading prose rather than a process it can shell out to, and it ships to every target. The seed copy of the hook keeps its awk, because a scaffolded project may carry no `aitk` and `scripts/core/check-seed-independence.sh` exists to catch seed content depending on the toolkit CLI. Both are the likelier place for the next drift, since nothing compares either against the verb.
 
-The hook prefers a checkout's own `src/cli.ts` over a globally installed binary, so it and the push stage read one build. A published binary lags a branch by whatever has not been released, which would put a ban kind added on the branch into the push and not into the edit. It reads its findings out of the `--json` record rather than off the exit code, so an older binary still reports where the fallback applies. It reads `bans.missingStandards` out of the same record, so a standard the verb found under neither root reaches the author as a check narrowed to what it could read.
+The hook prefers a checkout's own `src/cli.ts` over a globally installed binary, so it and the push stage read one build. A published binary lags a branch by whatever has not been released, which would put a ban kind added on the branch into the push and not into the edit. It reads its findings out of the `--json` record rather than off the exit code, so an older binary still reports where the fallback applies. It reads `bans.missingStandards` out of the same record, so a standard the verb found under none of the three roots reaches the author as a check narrowed to what it could read.
+
+The package fallback leaves that message reachable in one case rather than none. A CLI running out of a package carrying the corpus always resolves a standard, so the narrowed-check path fires only for a checkout whose own source tree lacks the file. The message stays right for that case and the hook keeps reading the field, since a reader cannot tell a narrowed check from a clean one without it.
 
 A machine with neither runner still blocks no edit, and it says so rather than exiting clean. The push stage holds either way. An edit nobody checked and an edit carrying no violation are one silence to a reader, so the enforcement a machine lacks is reported rather than inferred.
 

package/docs/target-projects.md

@@ -83,7 +83,7 @@ Run `aitk tooling list --json` and `aitk gov list --json` to see the current cat
 `governance`, `standards`, and `wiki` are skippable:
 
 - `--skip governance`: leave `.claude/rules/` empty. Standards still install, so `.claude/standards/prose.md` lands with nothing pointing at it and 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 standards`: leave standards out. The governance rules still reference `.claude/standards/`, so their authority lines resolve to nothing. Toolkit skills are unaffected, since each falls back to the copy in its own plugin root.
+- `--skip standards`: leave standards out. The governance rules still reference `.claude/standards/`, so their authority lines resolve to nothing for a reader following the path. Toolkit skills are unaffected, since each falls back to the copy in its own plugin root, and so is the CLI, which searches the corpus inside its own package behind both project roots. `aitk markdown audit` and `aitk standards <name>` therefore answer in a project that skipped the install, and what the skip costs is the editable copy rather than the enforcement.
 - `--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.
 
 That standards fallback 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/claude/520-wireframes.md

@@ -6,7 +6,15 @@ paths:
 
 # Wireframe standards
 
+## Layout and intent
+
+- Draw each surface as an ASCII block inside a `plaintext` fence, one fence per distinct layout.
+- Label a region with its role. Never label one with a class name, a token name, or a computed value.
+- Carry on-screen copy verbatim, and mark copy the surface templates.
+- State interaction intent, never the mechanism behind it. Send algorithms, handlers, and thresholds to a `.claude/context/` entry.
+- Update a surface's wireframe in the same pull request that changes its layout or its interaction.
+
 ## Authority
 
 - Follow `.claude/standards/wireframes.md` for layout and interaction intent: ASCII layout, region labels, variants, copy, and what moves to `.claude/context/`. It is the single source.
-- A wireframe carries layout and intent, not implementation. Read the standard before adding or revising a surface.
+- Read it before adding or revising a surface.

package/governance/rules/claude/530-requirements.md

@@ -6,6 +6,14 @@ paths:
 
 # Requirements standards
 
+## Scope and non-goals
+
+- State a goal as a user-facing outcome, never as the implementation delivering it.
+- Record explicit non-goals. Mark a deferred item `(deferred)`.
+- Leave the MVP list as written once its features ship. Do not renumber it, extend it, or annotate an entry with status.
+- Add later scope as a new section rather than as an extension of the MVP list.
+- Drop a section rather than pad it. Include `## Distribution` only when the project ships outside its own repository.
+
 ## Authority
 
 - Follow `.claude/standards/requirements.md` for what belongs in the problem, goals, non-goals, MVP features, tech stack, and constraints. It is the single source.

package/governance/rules/claude/540-architecture.md

@@ -6,6 +6,16 @@ paths:
 
 # Architecture standards
 
+## Decisions
+
+- Give each decision its own H3 under `## Key technical decisions`, naming what it chose and the alternative it passed over.
+- Keep line-by-line function behavior and full type definitions out.
+
+## Verification anchors
+
+- Close a decision citing a measured number with `Measured at <short-sha> on <YYYY-MM-DD>.` Leave a decision citing none unanchored.
+- Refresh that anchor whenever the number is re-read, whether or not it moved.
+
 ## Authority
 
 - Follow `.claude/standards/architecture.md` for the overview, named decision entries, and risks. It is the single source.

package/governance/rules/claude/550-design.md

@@ -6,6 +6,14 @@ paths:
 
 # Design standards
 
+## Tokens
+
+- Describe a token as intent rather than as a computed value.
+- Keep CSS classes, component filenames, and prop names out.
+- Carry a token system as a table, one row per token, and a component rule as a short bullet.
+- Keep the token table headers verbatim.
+- Record a non-obvious omission, such as no motion or no custom icons.
+
 ## Authority
 
 - Follow `.claude/standards/design.md` for visual intent, the token tables, and the render contract. It is the single source.

package/governance/rules/claude/555-tasks.md

@@ -6,6 +6,14 @@ paths:
 
 # Tasks standards
 
+## What a task carries
+
+- Name where the task came from, through a `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` line under the title.
+- Size the outcomes so one pull request closes all of them. Split the task before handing it off.
+- Use `## Outcomes` and `## Findings` and add no third heading. Note status inline on an outcome.
+- Keep class names, file paths, function names, and prop names out of every entry and title.
+- Never delete a task file. A shipped task moves to the archive under its own name.
+
 ## Authority
 
 - Follow `.claude/standards/tasks.md` for filenames, frontmatter, what belongs, and the task file format. It is the single source.

package/governance/rules/claude/580-readme.md

@@ -6,6 +6,14 @@ paths:
 
 # README standards
 
+## Audience and voice
+
+- Write a repository-root README for someone deciding whether to commit to the project. A nested README keeps the reference voice.
+- Address the reader in second person.
+- Ground a claim in a command, a number, or a named constraint rather than an adjective.
+- Name what the project does not do.
+- Link out to full API documentation, license text, contribution guidelines, and troubleshooting rather than carrying them.
+
 ## Authority
 
 - Follow `.claude/standards/readme.md` for voice, structure, required and optional sections, heading hierarchy, badge classes, per-project-type content, and what to link out rather than inline. It is the single source.

package/governance/rules/claude/590-rule-authoring.md

@@ -6,6 +6,17 @@ paths:
 
 # Rule authoring standards
 
+## Numbering
+
+- Name a rule `.claude/rules/<subdirectory>/<n>-<slug>.md`, taking a number that collides with neither the project's rules nor any installed shared set.
+- Give every rule a numeric prefix and keep the slug to one to three kebab words.
+
+## Body
+
+- State one directive per bullet in imperative voice. Do not explain the reasoning behind a rule.
+- Cut a rule that resists crisp one-line phrasing.
+- Do not restate a rule a sibling rule or `CLAUDE.md` already owns. Point once.
+
 ## Authority
 
 - Follow `.claude/standards/rule.md` for rule frontmatter, body shape, and voice. It is the single source.

package/governance/rules/claude/591-standard-authoring.md

@@ -7,6 +7,14 @@ paths:
 
 # Standard authoring standards
 
+## The scope statement
+
+- Govern one document type per standard, or one attribute across every document.
+- Open with a `## Scope` section naming what the standard governs and a `Does not govern:` list, placed above the shape rules.
+- Put the governed path in backticks in the first sentence, anchored deep enough to resolve from a project root. Keep an attribute standard's first sentence free of backticks and say in it that it governs an attribute.
+- Give each `Does not govern:` entry an excluded concern and the owner it goes to. Cut an entry naming no owner.
+- Declare a yield, an exemption, or a handoff from both sides of the boundary.
+
 ## Authority
 
 - Follow `.claude/standards/standard.md` for a standard's frontmatter, shape, scope, and success criterion. It is the single source.

package/package.json

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

package/src/cli.ts

@@ -24,7 +24,7 @@ import { register as comments } from '@/commands/comments'
 import { register as context } from '@/commands/context'
 import { register as markdown } from '@/commands/markdown'
 import { register as records } from '@/commands/records'
-import { PROJECT_ROOT } from '@/exec'
+import { PROJECT_ROOT } from '@/project-root'
 
 const GREY = '\x1b[0;90m'
 const WHITE = '\x1b[1;37m'
@@ -40,7 +40,7 @@ function showHelp(): void {
     `${GREY}│${NC}    sync [path]        ${GREY}# Sync all installed domains in a project${NC}`,
     `${GREY}│${NC}    sandbox [cat:cmd]  ${GREY}# Provision and run sandbox scenarios${NC}`,
     `${GREY}│${NC}    gov [command]      ${GREY}# Governance commands (install, sync)${NC}`,
-    `${GREY}│${NC}    standards [cmd]    ${GREY}# Standards commands (install, sync)${NC}`,
+    `${GREY}│${NC}    standards [cmd]    ${GREY}# Standards commands (install, sync, list, <name>)${NC}`,
     `${GREY}│${NC}    snippets [cmd]     ${GREY}# Snippets commands (install, sync)${NC}`,
     `${GREY}│${NC}    tooling [cmd]      ${GREY}# Manage tooling stacks (sync, ref, create)${NC}`,
     `${GREY}│${NC}    claude [cmd]       ${GREY}# Claude workflow (init, sync, setup)${NC}`,

package/src/commands/claude.ts

@@ -29,7 +29,8 @@ import {
   writeSettings,
 } from '@/claude/settings'
 import { copyPreservingMode } from '@/copy'
-import { execScript, PROJECT_ROOT } from '@/exec'
+import { execScript } from '@/exec'
+import { PROJECT_ROOT } from '@/project-root'
 import { isDirectory, resolveTarget } from '@/target'
 import { injectGitignore, pruneGitignore } from '@/tooling/inject'
 import {

package/src/commands/docs.ts

@@ -1,7 +1,8 @@
 import type { Command } from 'commander'
 import { registerPassThroughVerbs } from '@/commands/pass-through'
 import { listTopics, readTopic, resolveTopic } from '@/docs/read'
-import { execScript, PROJECT_ROOT } from '@/exec'
+import { execScript } from '@/exec'
+import { PROJECT_ROOT } from '@/project-root'
 import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
 
 export function register(program: Command): void {

package/src/commands/feedback.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import { deriveSlug, deriveTitle } from '@/commands/feedback-format'
-import { PROJECT_ROOT } from '@/exec'
+import { PROJECT_ROOT } from '@/project-root'
 import { createGithubIssue } from '@/github'
 import { frameError, frameSuccess } from '@/ui'
 

package/src/commands/gov.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 import { mkdir, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, resolve } from 'node:path'
 import type { Command } from 'commander'
-import { PROJECT_ROOT } from '@/exec'
+import { PROJECT_ROOT } from '@/project-root'
 import { createGovAdapter } from '@/gov/adapter'
 import { regenConsumedRules } from '@/gov/consumed'
 import { hasStandards, installRules, lookupRules } from '@/gov/install'

package/src/commands/init.ts

@@ -1,6 +1,6 @@
 import type { Command } from 'commander'
 import { cliPath, cliRun } from '@/cli-run'
-import { PROJECT_ROOT } from '@/exec'
+import { PROJECT_ROOT } from '@/project-root'
 import { applyInitOptions, flagsProvided } from '@/init/flags'
 import { type InitFlags, parseSkip, planInit } from '@/init/plan'
 import { runDomains } from '@/init/run'

package/src/commands/markdown.ts

@@ -69,8 +69,10 @@ export function register(program: Command): void {
         'what markdown.md reserves the span for.',
         '',
         'Bans and checkpoints are read from markdown.md and prose.md, resolved',
-        'under .claude/standards/ then standards/. No folder has to resolve and',
-        'no index.md has to exist, so .claude/rules/, governance/, and snippets/',
+        'under .claude/standards/, then standards/, then the corpus inside the',
+        'aitk package, so a project that installed neither is still measured.',
+        'The report names the copy it read. No folder has to resolve and no',
+        'index.md has to exist, so .claude/rules/, governance/, and snippets/',
         'are in reach.',
         '',
         'Examples:',
@@ -206,7 +208,7 @@ function reportBans(reports: readonly FileReport[], bans: BanReport): void {
 
   if (bans.missing.length > 0) {
     logWarn(
-      `Not measured. Found neither copy of: ${bans.missing.join(', ')}. Looked under .claude/standards/ then standards/.`,
+      `Not measured. Found no copy of: ${bans.missing.join(', ')}. Looked under .claude/standards/, then standards/, then the aitk package.`,
     )
     if (bans.sources.length === 0) return
   }

package/src/commands/sandbox.ts

@@ -2,7 +2,8 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type { Command } from 'commander'
-import { PROJECT_ROOT, execScript } from '@/exec'
+import { execScript } from '@/exec'
+import { PROJECT_ROOT } from '@/project-root'
 import {
   assertedPercent,
   collectCensus,

package/src/commands/snippets.ts

@@ -1,6 +1,6 @@
 import type { Command } from 'commander'
 import { registerPassThroughVerbs } from '@/commands/pass-through'
-import { PROJECT_ROOT } from '@/exec'
+import { PROJECT_ROOT } from '@/project-root'
 import { createSnippetsAdapter } from '@/snippets/adapter'
 import { BASE_CATEGORY } from '@/snippets/categories'
 import {

package/src/commands/standards.ts

@@ -1,7 +1,7 @@
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import { registerPassThroughVerbs } from '@/commands/pass-through'
-import { PROJECT_ROOT } from '@/exec'
+import { PROJECT_ROOT } from '@/project-root'
 import { createStandardsAdapter, standardsSourceDir } from '@/standards/adapter'
 import { ALL_SELECTION, selectStandards } from '@/standards/closure'
 import {
@@ -10,6 +10,7 @@ import {
   standardsInstallDir,
 } from '@/standards/index-refresh'
 import { applyInstall, planInstall } from '@/standards/install'
+import { listStandards, readStandard, resolveStandard } from '@/standards/read'
 import { recordStamp, runDomainSync } from '@/sync/engine'
 import { resolveTarget } from '@/target'
 import {
@@ -35,8 +36,35 @@ interface InstallOptions {
 export function register(program: Command): void {
   const standards = program
     .command('standards')
-    .description('Standards commands (install, sync, list)')
+    .description('Standards commands (install, sync, list, <name>)')
+    .argument('[name]', 'Standard to print, by name with or without .md')
     .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'A name resolves under .claude/standards/, then standards/, then the',
+        'corpus inside the aitk package, so a standard prints without a project',
+        'copy on disk. The frame names the copy it read.',
+        '',
+        'Examples:',
+        '  aitk standards prose',
+        '  aitk standards markdown.md',
+        '',
+      ].join('\n'),
+    )
+    .action((name: string | undefined, _options: unknown, cmd: Command) => {
+      if (name === undefined) {
+        // Registering an action replaces commander's own no-action fallback,
+        // which writes this help to stderr. Help is UI rather than data, and
+        // the default here is stdout.
+        cmd.outputHelp({ error: true })
+        process.exitCode = 1
+        return
+      }
+
+      process.exitCode = print(name)
+    })
 
   standards
     .command('sync')
@@ -82,6 +110,35 @@ export function register(program: Command): void {
   registerPassThroughVerbs(standards, 'standards', ['list'])
 }
 
+/**
+ * Writes the standard to stdout and every frame line to stderr, so a caller
+ * capturing the output with `$(...)` receives the document alone.
+ *
+ * The root is the caller's directory rather than the toolkit's, since a project
+ * copy is what governs wherever one exists and the package copy answers only
+ * its absence.
+ */
+function print(name: string): number {
+  intro('aitk standards')
+
+  const root = process.cwd()
+  const resolved = resolveStandard(root, name)
+
+  if (!resolved) {
+    logWarn(`Unknown standard: ${name}`)
+    logStep('Available standards')
+    for (const each of listStandards(root)) logInfo(each)
+    logError("Run 'aitk standards list' for descriptions.")
+    outro()
+    return 1
+  }
+
+  logStep(resolved.source)
+  process.stdout.write(readStandard(resolved))
+  outro()
+  return 0
+}
+
 async function runInstall(target: string, selection: string): Promise<number> {
   intro('aitk standards')
 

package/src/commands/sync.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import { cliPath, cliRun } from '@/cli-run'
-import { PROJECT_ROOT } from '@/exec'
+import { PROJECT_ROOT } from '@/project-root'
 import {
   buildCheckReport,
   type CheckReport,

package/src/commands/tooling.ts

@@ -1,6 +1,7 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
-import { execScript, PROJECT_ROOT } from '@/exec'
+import { execScript } from '@/exec'
+import { PROJECT_ROOT } from '@/project-root'
 import {
   applyReferences,
   injectConfigs,

package/src/commands/wiki.ts

@@ -1,6 +1,6 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
-import { PROJECT_ROOT } from '@/exec'
+import { PROJECT_ROOT } from '@/project-root'
 import {
   intro,
   logAdd,

package/src/exec.ts

@@ -1,7 +1,6 @@
-import { join, resolve } from 'node:path'
+import { join } from 'node:path'
 import { execa } from 'execa'
-
-export const PROJECT_ROOT = resolve(import.meta.dir, '..')
+import { PROJECT_ROOT } from '@/project-root'
 
 export async function execScript(
   script: string,

package/src/github.ts

@@ -1,5 +1,5 @@
 import { execa } from 'execa'
-import { PROJECT_ROOT } from '@/exec'
+import { PROJECT_ROOT } from '@/project-root'
 import { buildIssueArgs, type CreateIssueOptions } from '@/github-format'
 
 const GH_TIMEOUT_MS = 30_000

package/src/markdown/bans.ts

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
 import { linesOutsideFences } from '@/markdown/scan'
+import { resolveStandard } from '@/standards/read'
 
 /**
  * Headings the two standards state their closed sets under.
@@ -17,13 +17,6 @@ export const CHARACTER_BAN_HEADING = '## Punctuation'
 const BAN_LEAD = '- Do not use '
 const SPELLING_LEAD = '- Use American English spelling'
 
-/**
- * Roots searched in order. The installed copy wins over the authoring root, so
- * a target project measures against the standard it actually has rather than
- * one only the toolkit carries.
- */
-const STANDARD_ROOTS = ['.claude/standards', 'standards']
-
 const BACKTICKED = /`([^`]+)`/g
 const WORD = /^[a-z]+$/
 const SUFFIX = /^-[a-z]+$/
@@ -35,12 +28,16 @@ export interface BanReport {
   readonly words: readonly string[]
   /** Spellings derived from the prose standard's own examples. */
   readonly spellings: readonly string[]
-  /** Repo-relative paths of the standards read, in the order read. */
+  /**
+   * Paths of the standards read, in the order read. Repo-relative for a project
+   * copy, and spelled under `<aitk>/` for the package copy, so a reader can
+   * tell which root answered without joining a path that resolves nowhere.
+   */
   readonly sources: readonly string[]
   /**
-   * Standards that resolved under neither root. Absent is a distinct state from
-   * empty: a scan with no terms finds nothing, and reporting that as a clean
-   * file claims the prose passed when nothing was looked for.
+   * Standards that resolved under none of the roots. Absent is a distinct state
+   * from empty: a scan with no terms finds nothing, and reporting that as a
+   * clean file claims the prose passed when nothing was looked for.
    */
   readonly missing: readonly string[]
 }
@@ -155,7 +152,7 @@ export function parseSpellingBans(markdown: string): string[] {
 }
 
 export interface StandardText {
-  /** Repo-relative path of the copy read, so a report says which root won. */
+  /** Path of the copy read, so a report says which root won. */
   readonly source: string
   readonly text: string
 }
@@ -164,29 +161,24 @@ export interface Standards {
   readonly markdown: StandardText | undefined
   readonly prose: StandardText | undefined
   /**
-   * Standards that resolved under neither root. Absent is a distinct state from
-   * empty: a scan with no terms finds nothing, and reporting that as a clean
-   * file claims the prose passed when nothing was looked for.
+   * Standards that resolved under none of the roots. Absent is a distinct state
+   * from empty: a scan with no terms finds nothing, and reporting that as a
+   * clean file claims the prose passed when nothing was looked for.
    */
   readonly missing: readonly string[]
 }
 
-async function readStandard(
+async function loadStandard(
   root: string,
   name: string,
 ): Promise<StandardText | undefined> {
-  for (const standardRoot of STANDARD_ROOTS) {
-    const path = resolve(root, standardRoot, name)
-    const file = Bun.file(path)
-    if (!(await file.exists())) continue
-
-    return {
-      source: `${standardRoot}/${name}`,
-      text: await readFile(path, 'utf8'),
-    }
-  }
+  const resolved = resolveStandard(root, name)
+  if (!resolved) return undefined
 
-  return undefined
+  return {
+    source: resolved.source,
+    text: await readFile(resolved.path, 'utf8'),
+  }
 }
 
 /**
@@ -199,8 +191,8 @@ async function readStandard(
  */
 export async function loadStandards(root: string): Promise<Standards> {
   const [markdown, prose] = await Promise.all([
-    readStandard(root, 'markdown.md'),
-    readStandard(root, 'prose.md'),
+    loadStandard(root, 'markdown.md'),
+    loadStandard(root, 'prose.md'),
   ])
 
   return {

package/src/project-root.ts

@@ -0,0 +1,19 @@
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * The root of the package this CLI is running out of, which is the repository
+ * root in a checkout and the installed package directory in a target.
+ *
+ * Derived from `import.meta.url` rather than Bun's `import.meta.dir`, since the
+ * test runner resolves the first and leaves the second undefined, which puts
+ * every module reading this root out of reach of a test.
+ *
+ * It sits in a module of its own rather than beside `execScript`, because a
+ * path constant and a process spawn share no reason to change and an importer
+ * of the first would otherwise load `execa` to read one string.
+ */
+export const PROJECT_ROOT = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+)

package/src/standards/read.ts

@@ -0,0 +1,97 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { stripFrontmatter } from '@/frontmatter'
+import { PROJECT_ROOT } from '@/project-root'
+import { standardsSourceDir } from '@/standards/adapter'
+import { INDEX_FILE } from '@/standards/index-refresh'
+
+/**
+ * Spells the package root in a report where every other root spells a
+ * project-relative path. The `source` field promises a path inside the project
+ * and a package copy is the one source that promise cannot cover, so the
+ * spelling has to be one nothing will join to a project root.
+ */
+const PACKAGE_LABEL = '<aitk>'
+
+export interface StandardRoot {
+  /** Absolute directory to search. */
+  readonly dir: string
+  /** How a report spells a copy found under this root. */
+  readonly label: string
+}
+
+export interface ResolvedStandard {
+  readonly path: string
+  /** The label of the root that won, joined to the filename. */
+  readonly source: string
+}
+
+/**
+ * The three roots a standard resolves against, in precedence order.
+ *
+ * A project copy wins wherever one exists. An installed standard is a seed a
+ * project edits, so a package copy overriding it would discard that edit with
+ * nothing said, and the fallback answers absence rather than staleness. The
+ * package root is what lets a project that installed no standards still be
+ * measured against one, since `package.json` ships the corpus beside the code
+ * doing the reading.
+ */
+export function standardRoots(root: string): StandardRoot[] {
+  return [
+    {
+      dir: join(root, '.claude', 'standards'),
+      label: join('.claude', 'standards'),
+    },
+    { dir: join(root, 'standards'), label: 'standards' },
+    {
+      dir: standardsSourceDir(PROJECT_ROOT),
+      label: join(PACKAGE_LABEL, 'standards'),
+    },
+  ]
+}
+
+function filename(name: string): string {
+  return name.endsWith('.md') ? name : `${name}.md`
+}
+
+/** Resolves a standard by name, with or without the extension. */
+export function resolveStandard(
+  root: string,
+  name: string,
+): ResolvedStandard | undefined {
+  const file = filename(name)
+
+  for (const { dir, label } of standardRoots(root)) {
+    const path = join(dir, file)
+    if (existsSync(path)) return { path, source: join(label, file) }
+  }
+
+  return undefined
+}
+
+/**
+ * Names every standard a resolve could reach, deduplicated across the roots and
+ * sorted. Shown when a name misses, so it doubles as the answer to what the
+ * caller should have typed.
+ */
+export function listStandards(root: string): string[] {
+  const names = new Set<string>()
+
+  for (const { dir } of standardRoots(root)) {
+    if (!existsSync(dir)) continue
+
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isFile()) continue
+      if (!entry.name.endsWith('.md')) continue
+      if (entry.name === INDEX_FILE) continue
+
+      names.add(basename(entry.name, '.md'))
+    }
+  }
+
+  return [...names].sort()
+}
+
+export function readStandard(standard: ResolvedStandard): string {
+  return stripFrontmatter(readFileSync(standard.path, 'utf8'))
+}