@erclx/canon 4.62.0 → 4.63.0

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

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

package/claude/skills/canon-cli/REQUIREMENT.md

@@ -1,6 +1,6 @@
 ---
 name: canon-cli
-description: Why the overwrite contract is stated before a sync runs, and why the skill reads rather than executes
+description: Why a session is pointed at the verb catalog, the reference docs, and the overwrite contract from one place, and why the skill reads rather than writes
 ---
 
 # Canon cli requirement
@@ -17,17 +17,20 @@ Being reachable is a separate problem from being right. This is a pure reference
 
 The two bodies now carrying an inline pointer are `claude-seed-sync` and `canon-operator`, each at the point it runs or prints an overwriting command.
 
+A third gap sits beside the first two, aimed at a different question. `canon --help` lists every top-level verb and `canon docs` emits the toolkit's own reference corpus, but no reference skill pointed a session at either. The one skill that does, `canon-operator`, is user-invoked only and reaches them as a side effect of its own orientation step. A session guessing at a verb's name, or restating what a doc already answers, is the same missing-fact failure the overwrite gap names.
+
 ## Must
 
 - State per surface and per command whether an existing file is overwritten, merged, written once, or left alone
 - Warn about a destructive run before it happens, naming the surface that will be lost
 - Name the section-preserving path for a standard or seed the project has customized
 - Defer to the toolkit's own context docs when they and this summary disagree, since the summary is a copy and they are the source
+- Point to `canon docs agents` for the verb catalog and to `canon docs` for the reference corpus, rather than restating either
 
 ## Must not
 
-- Run any `canon` command. The skill is read before acting.
-- Restate the full semantics. It is a target-session summary and the detail lives with its owner.
+- Run, or send the session to run, a `canon` command that writes or installs. The skill is read before acting on a sync.
+- Restate the verb catalog or a reference doc's content. Point to `canon docs agents` or `canon docs <topic>` instead. The overwrite table is this skill's one authored exception, and it too is a target-session summary, with the detail living with its owner.
 - Take a mention in a sibling's requirement file as an inbound route. The three bodies named in the gap above carry the pointer, and adding a fourth means editing that body rather than its requirement.
 
 ## Guards
@@ -39,3 +42,4 @@ The two bodies now carrying an inline pointer are `claude-seed-sync` and `canon-
 - Executing the sync, which the user runs or `canon-operator` routes
 - Reconciling a customized seed section by section: `claude-seed-sync`
 - Deciding which stack, rule, or standard a project should install, which the setup skills resolve from live catalogs
+- Diagnosing what a project is behind on, or executing the fix: `canon-operator`

package/claude/skills/canon-cli/SKILL.md

@@ -1,11 +1,17 @@
 ---
 name: canon-cli
-description: Reference for what canon sync and install commands overwrite, merge, or leave untouched in a target project. Use before running `canon tooling`, `canon standards`, `canon claude sync`, or `canon init`, or when asked "will this overwrite my changes". Do NOT use to run the commands, only to know their effect.
+description: Reference for what a canon verb does before you run it. Run `canon docs agents` for the full command catalog, `canon docs` for any other reference doc, and read this skill's own table for what a sync or install command overwrites, merges, or leaves untouched in a target project. Use when asked "which canon command do I run", "is there a doc for X", "will this overwrite my changes", or before running `canon tooling`, `canon standards`, `canon claude sync`, or `canon init`. Do NOT use to execute a sync, an install, or a docs lookup, only to know which command answers the question.
 ---
 
 # Toolkit CLI contract
 
-What each `canon` sync or install command does to existing files in a target project. Consult before running one, then warn the user about anything destructive. This skill is reference only. It does not run commands.
+Consult before running an unfamiliar `canon` verb, before a sync or install, or when asked "will this overwrite my changes". This skill is reference only. It never runs a sync or an install.
+
+## Verb catalog and reference docs
+
+- Run `canon docs agents` for the full command catalog and invocation contract, rather than guessing at a verb from its name.
+- Run `canon docs list` for every other reference doc, then `canon docs <topic>` by name.
+- State neither list here. Both read live off the CLI, and a copy in this body ships on a different cadence than the commands it names.
 
 ## Overwrite contract
 

package/claude/skills/{context-draft → draft-context}/REQUIREMENT.md

@@ -1,5 +1,5 @@
 ---
-name: context-draft
+name: draft-context
 description: Why a brand-new .claude/context/<domain>.md entry needs a catalog collision check and a confirm step, not the refresh path claude-docs already owns
 ---
 
@@ -32,6 +32,6 @@ Without this skill, a session documenting a domain that has no context entry yet
 ## Out of scope
 
 - Refreshing an existing `.claude/context/<domain>.md` entry against a diff: `claude-docs`
-- Drafting a `.claude/wireframes/<surface>.md` file: `wireframe-draft`
-- Drafting a `docs/*.md` page: `docs-draft`
+- Drafting a `.claude/wireframes/<surface>.md` file: `draft-wireframes`
+- Drafting a `docs/*.md` page: `draft-docs`
 - Drafting a standard, a snippet, or a governance rule: `create-standard`, `create-snippet`, `create-rule`

package/claude/skills/{context-draft → draft-context}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: context-draft
+name: draft-context
 description: Drafts a brand-new `.claude/context/<domain>.md` entry against the context standard, checks the catalog for a name-or-topic collision, decides flat-file placement, confirms with the user, then writes. Use when asked to "write a context entry for X", "document the X domain", "add a context entry for X", or "create a .claude/context page for X" where no existing entry covers the domain. Do NOT use to refresh an existing entry against a diff, which is `claude-docs`.
 ---
 

package/claude/skills/{docs-draft → draft-docs}/REQUIREMENT.md

@@ -1,5 +1,5 @@
 ---
-name: docs-draft
+name: draft-docs
 description: Why a brand-new docs/*.md page needs a placement decision and a confirm step, not the rewrite path docs-sync already owns
 ---
 

package/claude/skills/{docs-draft → draft-docs}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: docs-draft
+name: draft-docs
 description: Drafts a brand-new `docs/*.md` page against the docs standard, decides its placement in the existing catalog, confirms with the user, then writes. Use when asked to "add a docs page for X", "write a new doc for X", "document X under docs/", or "create a docs page for X" where no existing page covers the topic. Do NOT use to rewrite or sync an existing `docs/*.md` section against a diff, which is `docs-sync`.
 ---
 

package/claude/skills/{wireframe-draft → draft-wireframes}/REQUIREMENT.md

@@ -1,5 +1,5 @@
 ---
-name: wireframe-draft
+name: draft-wireframes
 description: Why a brand-new .claude/wireframes/<surface>.md file needs a real draft and a tier-detect step, not the stub the wireframe-sweep already writes
 ---
 
@@ -32,7 +32,7 @@ Without this skill, a session drafting a wireframe for a surface with no file ye
 ## Out of scope
 
 - Stubbing a surface a diff touched, or reporting drift in an existing wireframe against a diff: `claude/skills/claude-docs/references/wireframe-sweep.md`
-- Drafting a `.claude/context/<domain>.md` entry: `context-draft`
-- Drafting a `docs/*.md` page: `docs-draft`
+- Drafting a `.claude/context/<domain>.md` entry: `draft-context`
+- Drafting a `docs/*.md` page: `draft-docs`
 - Drafting a standard, a snippet, or a governance rule: `create-standard`, `create-snippet`, `create-rule`
 - Building or wiring an actual tier-1 or tier-2 rendering pipeline: the visual design workflow's own tier guidance, out of reach of a hand-drafting skill

package/claude/skills/{wireframe-draft → draft-wireframes}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: wireframe-draft
+name: draft-wireframes
 description: Drafts a brand-new `.claude/wireframes/<surface>.md` file against the wireframes standard, walks the tree for a name collision, detects an existing higher visual-design tier without building one, confirms with the user, then writes. Use when asked to "draft a wireframe for X", "write the wireframe for this surface", "add a .claude/wireframes entry for X", or "wireframe this screen" where no surface file covers it yet. Do NOT use to fix a stale TODO stub or report wireframe drift against a diff, which is `claude-docs`'s wireframe-sweep step.
 ---
 

package/claude/skills/repo-metadata/SKILL.md

@@ -19,13 +19,14 @@ Reads what `canon repo metadata propose` computes locally and reports it against
 
 1. Run `canon repo metadata propose --json`.
 2. Read `diff` and `repo` from the record. `repo` is the `--repo` value the later apply step must carry. An empty `diff` means the remote already matches what this run computed: report that and stop, since there is nothing to answer.
-3. For each field `diff` carries, put the change to the operator through the structured question surface: which of the differing fields to write. Rank accepting the proposed value first for a field whose current value is stale or wrong, and give the reject option the cost of leaving the remote as it stands. Never pre-select an answer for the operator.
-4. Report the fields the proposal left absent as unchanged, naming that neither the README nor `package.json` carried a source for them.
-5. Stop. Do not run apply here even when the operator answers immediately, since answering is not yet an apply invocation.
+3. When `diff` carries a `description` field, compress its proposed value, the raw opening line `canon repo metadata propose` computed, into a single short phrase. Leave the shape and length of the phrase to judgment on each run. No numeric target applies. Keep the raw proposed value beside the compressed phrase in what gets reported, so the operator can check the phrase against the README line it came from.
+4. For each field `diff` carries, put the change to the operator through the structured question surface: which of the differing fields to write. For `description`, the value offered to accept is the compressed phrase from step 3, not the raw line beside it. Rank accepting the proposed value first for a field whose current value is stale or wrong, and give the reject option the cost of leaving the remote as it stands. Never pre-select an answer for the operator.
+5. Report the fields the proposal left absent as unchanged, naming that neither the README nor `package.json` carried a source for them.
+6. Stop. Do not run apply here even when the operator answers immediately, since answering is not yet an apply invocation.
 
 ## Apply
 
-1. Confirm every field about to be written was answered by the operator in this conversation. Carry no field forward unanswered.
+1. Confirm every field about to be written was answered by the operator in this conversation. Carry no field forward unanswered. For `description`, the answered value is the compressed phrase Propose offered, never the raw README line reported beside it.
 2. Run `canon repo metadata apply`, always passing `--repo <owner/name>` from the propose record's `repo` field, plus the flags for the answered fields: `--description <text>`, `--homepage <url>`, `--topics <comma-separated list>`. `--topics` is the full desired set, and the command reads the current set itself to compute what to add and remove. The command refuses rather than writing when `--repo` does not match what `--root` resolves to, so never omit it and never guess it from anything but the propose record's `repo` field.
 3. Report the written state from the JSON record.
 
@@ -35,7 +36,7 @@ Propose:
 
 ```plaintext
 📋 Repo metadata proposal
-description: "<current>" → "<proposed>"
+description: "<current>" → "<compressed>" (derived from the README's opening line: "<raw>")
 homepage: unchanged, no local source
 topics: +<added>, -<removed>
 

package/docs/workflow/ai-workflow.md

@@ -291,9 +291,9 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:create-skill`       | For a new `SKILL.md`                                                                              |
 | `canon:create-snippet`     | For a reusable prompt                                                                             |
 | `canon:create-standard`    | For a new authoring convention                                                                    |
-| `canon:docs-draft`         | For a brand-new `docs/*.md` page, drafted against `standards/docs.md`                             |
-| `canon:context-draft`      | For a brand-new `.claude/context/<domain>.md` entry, drafted against `standards/context.md`       |
-| `canon:wireframe-draft`    | For a brand-new `.claude/wireframes/<surface>.md` file, drafted against `standards/wireframes.md` |
+| `canon:draft-docs`         | For a brand-new `docs/*.md` page, drafted against `standards/docs.md`                             |
+| `canon:draft-context`      | For a brand-new `.claude/context/<domain>.md` entry, drafted against `standards/context.md`       |
+| `canon:draft-wireframes`   | For a brand-new `.claude/wireframes/<surface>.md` file, drafted against `standards/wireframes.md` |
 | `canon:bash-script`        | For an interactive, human-facing shell tool                                                       |
 | `canon:bash-cli-script`    | For a non-interactive automation, CI, or pipeline script                                          |
 | `canon:ci-workflow`        | For a GitHub Actions workflow file                                                                |
@@ -302,14 +302,14 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Answer a question at any point
 
-| Skill                       | When to use                                                                    |
-| --------------------------- | ------------------------------------------------------------------------------ |
-| `canon:canon-cli`           | Before a sync or install, to learn what it overwrites, merges, or leaves alone |
-| `canon:index-lookup`        | To find where a topic is documented across the tracked `index.md` catalogs     |
-| `canon:youtube-transcripts` | When a video transcript is wanted in the repo as context                       |
-| `canon:claude-teach`        | To learn a subject across sessions, in a workspace that holds the progress     |
-| `canon:write-human`         | Before drafting or revising prose, for voice, rhythm, and density              |
-| `canon:restate-plainly`     | When an answer or a document has to be read again in plain words               |
+| Skill                       | When to use                                                                                                                                                            |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `canon:canon-cli`           | Before running an unfamiliar verb, a sync, or an install, to learn which command to run, which reference doc covers it, or what it overwrites, merges, or leaves alone |
+| `canon:index-lookup`        | To find where a topic is documented across the tracked `index.md` catalogs                                                                                             |
+| `canon:youtube-transcripts` | When a video transcript is wanted in the repo as context                                                                                                               |
+| `canon:claude-teach`        | To learn a subject across sessions, in a workspace that holds the progress                                                                                             |
+| `canon:write-human`         | Before drafting or revising prose, for voice, rhythm, and density                                                                                                      |
+| `canon:restate-plainly`     | When an answer or a document has to be read again in plain words                                                                                                       |
 
 Every row answers a question rather than marking a point in a project's life, so a phase above would send a reader to the wrong group.
 

package/package.json

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

package/src/claude/cases/authoring.ts

@@ -40,17 +40,17 @@ export const AUTHORING_CASES: readonly SkillCase[] = [
   {
     prompt:
       'Write a brand-new docs page for the capture command, nothing under docs/ covers it yet.',
-    expect: 'docs-draft',
+    expect: 'draft-docs',
   },
   {
     prompt:
       'Write a context entry for the payments domain, there is no .claude/context page for it yet.',
-    expect: 'context-draft',
+    expect: 'draft-context',
   },
   {
     prompt:
       'Draft a wireframe for the settings panel, nothing under .claude/wireframes covers that surface yet.',
-    expect: 'wireframe-draft',
+    expect: 'draft-wireframes',
   },
   {
     prompt: 'Say what that dense answer actually means in plain terms.',

package/src/commands/tooling.ts

@@ -1,7 +1,7 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { execScript } from '@/exec'
-import { PROJECT_ROOT } from '@/project-root'
+import { findCheckoutMismatch, PROJECT_ROOT } from '@/project-root'
 import {
   injectConfigs,
   injectGitignore,
@@ -268,6 +268,13 @@ async function runSync(
 ): Promise<number> {
   intro('canon tooling sync')
 
+  const mismatch = findCheckoutMismatch(process.cwd())
+  if (mismatch !== undefined) {
+    logWarn(
+      `Resolved via ${PROJECT_ROOT}, not the checkout at ${mismatch}. Run \`bun ${mismatch}/src/cli.ts tooling sync ...\` to sync against that checkout instead.`,
+    )
+  }
+
   if (opts.check === true && opts.write === true) {
     logWarn('Pass --check or --write, not both.')
     outro()

package/src/migrate/scratch-evidence.ts

@@ -98,14 +98,18 @@ function citationPattern(folder: string): RegExp {
   )
 }
 
-/** One promoted folder's citation pattern, paired with its replacement. */
-const REWRITES: readonly {
+interface Rewrite {
   readonly pattern: RegExp
   readonly folder: string
-}[] = PROMOTED_FOLDERS.map((folder) => ({
-  pattern: citationPattern(folder),
-  folder,
-}))
+}
+
+/** One rewrite per folder, paired with its citation pattern. */
+function buildRewrites(folders: readonly string[]): readonly Rewrite[] {
+  return folders.map((folder) => ({
+    pattern: citationPattern(folder),
+    folder,
+  }))
+}
 
 /**
  * Marks a line naming a promoted folder's old path on purpose, the same
@@ -125,40 +129,43 @@ function isKept(lines: readonly string[], index: number): boolean {
   return above >= 0 && (lines[above]?.includes(KEEP_MARKER) ?? false)
 }
 
-function rewriteLine(line: string): string {
-  return REWRITES.reduce(
+function rewriteLine(line: string, rewrites: readonly Rewrite[]): string {
+  return rewrites.reduce(
     (current, { pattern, folder }) =>
       current.replace(pattern, `.canon/review/evidence/${folder}`),
     line,
   )
 }
 
-/**
- * Rewrites every unmarked citation of a promoted folder into its destination
- * under `.canon/review/evidence/`, absolute regardless of how the source
- * citation was spelled. A file naming no promoted folder returns
- * byte-identical, and a marked line is returned unchanged.
- */
-export function rewriteScratchEvidence(text: string): string {
-  const lines = text.split('\n')
-  return lines
-    .map((line, index) => (isKept(lines, index) ? line : rewriteLine(line)))
-    .join('\n')
+interface RewriteOutcome {
+  readonly text: string
+  readonly count: number
 }
 
-/** How many unmarked citations `rewriteScratchEvidence` would change. */
-export function countScratchEvidenceCitations(text: string): number {
+/**
+ * Rewrites every unmarked citation of a folder `rewrites` covers into its
+ * destination under `.canon/review/evidence/`, absolute regardless of how the
+ * source citation was spelled, counting each as it goes. A file naming no
+ * such folder returns byte-identical with a count of zero, and a marked line
+ * is returned unchanged and uncounted.
+ */
+function applyRewrites(
+  text: string,
+  rewrites: readonly Rewrite[],
+): RewriteOutcome {
   const lines = text.split('\n')
   let count = 0
 
-  for (const [index, line] of lines.entries()) {
-    if (isKept(lines, index)) continue
-    for (const { pattern } of REWRITES) {
+  const rewritten = lines.map((line, index) => {
+    if (isKept(lines, index)) return line
+
+    for (const { pattern } of rewrites) {
       count += [...line.matchAll(pattern)].length
     }
-  }
+    return rewriteLine(line, rewrites)
+  })
 
-  return count
+  return { text: rewritten.join('\n'), count }
 }
 
 /** The files under every `BACKED_FOLDERS` entry, archives included. */
@@ -261,17 +268,17 @@ export function planScratchEvidence(
   sources: readonly ScratchEvidenceSource[],
 ): ScratchEvidencePlan {
   const { moves, collisions } = planFolderMoves(root)
+  const folders = PROMOTED_FOLDERS.filter(
+    (folder) => !collisions.includes(destinationPath(root, folder)),
+  )
+  const rewrites = buildRewrites(folders)
   const entries: CitationEntry[] = []
 
   for (const source of sources) {
-    const rewritten = countScratchEvidenceCitations(source.text)
-    if (rewritten === 0) continue
-
-    entries.push({
-      path: source.path,
-      text: rewriteScratchEvidence(source.text),
-      rewritten,
-    })
+    const { text, count } = applyRewrites(source.text, rewrites)
+    if (count === 0) continue
+
+    entries.push({ path: source.path, text, rewritten: count })
   }
 
   return {

package/src/project-root.ts

@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -17,3 +18,36 @@ export const PROJECT_ROOT = resolve(
   dirname(fileURLToPath(import.meta.url)),
   '..',
 )
+
+const readPackageName = (root: string): string | undefined => {
+  try {
+    const raw = readFileSync(resolve(root, 'package.json'), 'utf8')
+    return (JSON.parse(raw) as { name?: string }).name
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Walks upward from `startDir` for the nearest ancestor `package.json`
+ * sharing this package's own `name`, and reports its path when that ancestor
+ * is not `PROJECT_ROOT`. A bare `canon` on PATH resolves `PROJECT_ROOT` to the
+ * installed package rather than to a checkout the caller may be standing in,
+ * which is the case this reports: a caller's cwd sitting inside a second
+ * checkout the running binary never resolved against.
+ */
+export function findCheckoutMismatch(startDir: string): string | undefined {
+  const ownName = readPackageName(PROJECT_ROOT)
+  if (ownName === undefined) return undefined
+
+  let dir = resolve(startDir)
+  while (true) {
+    if (readPackageName(dir) === ownName) {
+      return dir === PROJECT_ROOT ? undefined : dir
+    }
+
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+}

package/src/shipped/references.ts

@@ -168,14 +168,17 @@ const DOCS_PATH = /(?<![\w./-])docs\/[^\s`)\]]*\.md\b/g
  * lookbehind rejects, so a citation already rewritten to the resolving form
  * does not fail this check a second time.
  *
- * Reported only where `isStandardsPathResolvable` confirms the match
- * resolves against this checkout, the same gate `DOCS_PATH` runs. A body
- * illustrating the shape a project's own `standards/<name>.md` takes writes
- * the identical placeholder token this pattern matches, such as
- * `standards/<slug>.md` in `create-standard/SKILL.md` or `standards/<name>.md`
- * in `migration-standards-drop/SKILL.md`, and neither resolves to a real
- * file. Four such placeholders surfaced across three files the first time
- * this pattern ran unresolved, measured 2026-09-06.
+ * Reported unless `isStandardsPathReportable` reads the match as a
+ * deliberate placeholder rather than a real citation. A body illustrating
+ * the shape a project's own `standards/<name>.md` takes writes a bracketed
+ * token this pattern also matches, such as `standards/<slug>.md` in
+ * `create-standard/SKILL.md` or `standards/<name>.md` in
+ * `migration-standards-drop/SKILL.md`, and neither names a real file. A bare,
+ * non-bracketed match now reports whether or not the file exists, unlike
+ * `DOCS_PATH`, which still gates on existence: a same-repository citation
+ * under this corpus names no target project's own tree the way a `docs/`
+ * path can, so shape alone separates a placeholder from a broken citation
+ * here with no false-positive class existence was catching.
  */
 const STANDARDS_PATH = /(?<![\w./-])standards\/[^\s`)\]]*\.md\b/g
 
@@ -221,20 +224,37 @@ export interface ShippedReference {
 }
 
 /**
- * Whether a `DOCS_PATH` match names a real file in this checkout.
+ * Whether a matched path is a deliberate placeholder rather than a real
+ * citation, true when the text carries both `<` and `>`. A real path never
+ * carries either character, so the two classes cannot collide.
+ */
+function isPlaceholderPath(path: string): boolean {
+  return path.includes('<') && path.includes('>')
+}
+
+/**
+ * Whether a `DOCS_PATH` match should be reported.
  *
  * `file` gates the `docs/` corpus out by the caller's own location rather
  * than by a pattern exemption: a citation from inside `docs/` is read
  * together with the rest of that corpus through the same `canon docs`
  * resolution, which is a weaker claim than one from a skill body with no
  * `docs/` sibling at all.
+ *
+ * The placeholder check runs ahead of `existsSync` rather than replacing it.
+ * Shape alone cannot separate a genuinely broken same-repository citation
+ * from a legitimate illustration of a target project's own tree, such as
+ * `docs/retry.md`, and no signal in the text draws that line, so existence
+ * still does the work of muting those. The placeholder check only catches
+ * the bracketed illustrations existence alone would report as broken.
  */
-function isDocsPathResolvable(
+function isDocsPathReportable(
   file: string,
   path: string,
   root: string,
 ): boolean {
   if (file.startsWith('docs/')) return false
+  if (isPlaceholderPath(path)) return false
   return existsSync(join(root, path))
 }
 
@@ -250,9 +270,19 @@ function isStandardsPathScope(file: string): boolean {
   return file.startsWith('claude/skills/') && !file.endsWith('/REQUIREMENT.md')
 }
 
-/** Whether a `STANDARDS_PATH` match names a real file in this checkout. */
-function isStandardsPathResolvable(path: string, root: string): boolean {
-  return existsSync(join(root, path))
+/**
+ * Whether a `STANDARDS_PATH` match should be reported: every match that is
+ * not a placeholder, whether or not the named file exists.
+ *
+ * Existence used to gate this the same way `isDocsPathReportable` gates its
+ * corpus, which conflated a deliberate placeholder with a genuinely broken,
+ * real-looking citation: both fail existence and both passed muted. A bare
+ * `standards/<name>.md` names no target-project tree the way a `docs/` path
+ * can, so shape alone separates the two classes here with no false-positive
+ * class existence was catching.
+ */
+function isStandardsPathReportable(path: string): boolean {
+  return !isPlaceholderPath(path)
 }
 
 /**
@@ -318,7 +348,7 @@ export function referencesIn(
     }
 
     for (const match of line.matchAll(DOCS_PATH)) {
-      if (!isDocsPathResolvable(file, match[0], root)) continue
+      if (!isDocsPathReportable(file, match[0], root)) continue
       references.push({
         file,
         line: index + 1,
@@ -329,7 +359,7 @@ export function referencesIn(
 
     if (isStandardsPathScope(file)) {
       for (const match of line.matchAll(STANDARDS_PATH)) {
-        if (!isStandardsPathResolvable(match[0], root)) continue
+        if (!isStandardsPathReportable(match[0])) continue
         references.push({
           file,
           line: index + 1,

package/tooling/astro/configs/eslint.config.js

@@ -26,7 +26,7 @@ export default defineConfig([
   ...tseslint.configs.recommended,
   ...astro.configs.recommended,
   {
-    files: ['**/*.{ts,tsx,js,jsx}'],
+    files: ['**/*.{ts,tsx,js,jsx,astro}'],
     plugins: {
       'simple-import-sort': simpleImportSort,
       'check-file': checkFile,

package/tooling/astro/reference.md

@@ -21,7 +21,7 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 - `vitest.config.ts`: uses `getViteConfig` from `astro/config` (not `mergeConfig`). jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage, `**/*.astro` in coverage excludes.
 - `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `4321` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`. `DIST_PREBUILT` set in the environment drops the `build` half, running `bun run preview` alone against a `dist/` a prior CI job already produced.
 - `tsconfig.json`: extends `astro/tsconfigs/strict`, adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom` in types, `@/` paths.
-- `eslint.config.js`: overrides the web layer. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). `src/pages/**` exempt from filename and folder naming conventions because Astro's file-based routing ties names to URL segments.
+- `eslint.config.js`: overrides the web layer. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). The shared block's `files` selector includes `.astro`, so `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's own PascalCase component convention deliberately, on the ground that a component's name in markup comes from the import binding rather than the filename. `.js` and `.jsx` stay out of the rule's own pattern, matching `web` and `nextjs`. `check-file/folder-naming-convention`'s `src/**/!(__tests__|pages)` pattern reaches no folder under a real ESLint run, `.astro`-only or otherwise. See `.claude/context/tooling.md` for the measurement.
 
 ## Typecheck