@erclx/aitk 0.85.0 → 0.86.1

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

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

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

@@ -17,7 +17,7 @@ Without this skill, a pull request is reviewed only by the session that wrote it
 - Scope a later pass to the commits added since the prior one, once that commit is confirmed to still reach the head
 - Apply the integration, contract, and consumer lenses a self-review structurally cannot
 - Post the closing pass even with nothing to report, since a review left unanswered reads as one nobody closed
-- Key the body file on both the pull request number and the head commit, so no two passes overwrite each other
+- Key the body file on the pull request number and the head commit, and on the response it answers once the head repeats, so no two passes overwrite each other
 - Scan the comment for banned characters and internal phase labels before posting, since a finding phrased against a phase label reaches a reader with no task board
 
 ## Must not
@@ -32,6 +32,7 @@ Without this skill, a pull request is reviewed only by the session that wrote it
 
 - No open pull request for the target branch: stop and route to the local review skill
 - The fetch of the pull request head fails: stop rather than falling through to a full pass
+- The head repeats with no response since the prior pass: stop rather than posting a body restating one the folder holds
 
 ## Out of scope
 

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

@@ -95,6 +95,20 @@ Write the comment to `.claude/.tmp/pr-review/body-<number>-<short-sha>.md`. The
 
 Derive both segments from Step 1. Never pick a suffix by hand, and never reuse a name the folder already holds.
 
+When `<prior-oid>` from Step 2 equals `headRefOid`, the head repeats and the folder already holds `body-<number>-<short-sha>.md`. Add a third segment taking the id of the `## Review response` comment this pass answers, giving `body-<number>-<short-sha>-r<comment-id>.md`. That satisfies both prohibitions above rather than carving an exception into either.
+
+```bash
+gh pr view <number> --json reviews,comments --jq '([.reviews[] | select(.body // "" | split("\n")[0] | rtrimstr("\r") | . == "## Review" or . == "## Review closed")] | last | .submittedAt) as $prior | [.comments[] | select(.body // "" | split("\n")[0] | rtrimstr("\r") | . == "## Review response") | select(.createdAt > $prior)] | last | .url // empty | split("-") | last'
+```
+
+Scope the responses to those newer than the prior pass, never to every response the thread carries. A pass answering the newest response and a pass answering an older one derive the same third segment, so an unscoped read hands a re-run after a close-out the name its own prior pass already wrote. That is the collision this case exists to prevent, reached without a rebase or an error.
+
+Read the number off `.url`. The `id` field carries a GraphQL node id, which the thread never displays. Keep the `// empty` guard, since `split` aborts jq on the null an empty selection returns, and an aborted command reaches the session as an error rather than as the empty result the stop below reads.
+
+An empty result means no response arrived since the prior pass, so this pass would restate a body the folder already holds. Stop: `❌ No response since the prior pass on <short-sha>. Nothing new to review.`
+
+The response is also the whole read on a repeated head. Step 2 resolves an empty range, because a commit is its own ancestor and `<prior-oid>..<headRefOid>` spans nothing, so the delta cannot answer whether a prior finding landed. Read that comment for what the worker changed or accepted, and treat an accepted finding as closed rather than restating it.
+
 The comment is a rendered-for-human GitHub surface, so follow `.claude/standards/prose.md` for voice, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it: cut editorializing, and keep every sentence load-bearing. Match this shape on a first pass:
 
 ```markdown

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/operating-model.md

@@ -41,7 +41,7 @@ One feature travels this path end to end.
 3. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The worker builds, self-checks, opens a PR, and stops at the PR boundary.
 4. Orchestrator reviews the PR with `claude-pr-review` and posts findings to it.
 5. Worker addresses the findings with `claude-address-review`, rebases onto `origin/main` when a sibling landed first and left the branch unable to merge, then pushes a follow-up.
-6. Orchestrator closes the review out with `claude-pr-review` again. The second pass reads only the commits the follow-up added, and posts under `## Review closed` when it finds nothing open or under `## Review` when it does, so a reader learns the state from the heading. Repeat from step 5 until the review closes.
+6. Orchestrator closes the review out with `claude-pr-review` again. The second pass reads only the commits the follow-up added, or the worker's response alone when the follow-up added none, and posts under `## Review closed` when it finds nothing open or under `## Review` when it does, so a reader learns the state from the heading. Repeat from step 5 until the review closes.
 7. The human reads the result and merges. The orchestrator tells any trailing worker whose branch shares a seam with the merged one to run `claude-address-review`, which rebases whether or not the review left anything open.
 
 There is no loop construct here. Each worker is a single build that halts at the
@@ -68,6 +68,13 @@ the PR. `claude-address-review` reads them back, fixes each, replies or resolves
 the threads, and pushes a follow-up. `claude-pr-review` then runs again, reading
 only what the follow-up added.
 
+A finding answered without a commit leaves the head where the first pass read it,
+which a gitignored record and a finding accepted as recorded both produce. The
+close-out is still owed there, since the newest heading is what tells an operator
+whether the branch is blocked, so the pass reads the worker's response rather than
+a delta and names its body from that response instead of from a tree that did not
+change.
+
 A branch that stopped merging while the review was open is the worker's problem
 to close. `claude-address-review` rebases onto `origin/main` between the fixes
 and the push, so one force-push carries both and the reviewer reads one delta.

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.85.0",
+  "version": "0.86.1",
   "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'))
+}