@erclx/canon 4.62.1 → 4.64.0

package/claude/skills/identity/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: identity
+description: Drafts a project's logo mark through draft-and-pick's render-and-pick loop, then composes the picked mark into an icon sequence and a 1200x630 social card. Use when asked to "make a logo", "design a logo mark", "create a favicon", "build the icon set", "generate a social card", "make an og:image", or "draft the logo and social card together". Do NOT use to mutate an existing logo file directly, which is a plain edit, or to record the mark's construction rules in DESIGN.md, which is out of scope.
+---
+
+# Identity
+
+One identity rendered twice: the same mark sized down to an icon sequence and composed with type into the social card sized up. Drafting both from one pick keeps the mark and its card composition from settling on shapes that do not match.
+
+## Guards
+
+- If `canon` is not on PATH, stop: `❌ canon CLI not found.`
+- Draft no candidate for a mark the operator has not asked to make. This skill fires on a direct request, never on the model's own read that a project could use one.
+
+## Step 1: read signal
+
+Read these in parallel, skipping any that do not exist:
+
+- `.claude/DESIGN.md`: the `## Personality`, `## Color`, and `## Typography` sections, the same three cells `claude-design-extract` Step 2 sources from
+- `.claude/REQUIREMENTS.md`: the `## Personality` paragraph, when `.claude/DESIGN.md` carries none
+- `CLAUDE.md`: the project's stated voice, when neither file above carries a personality signal
+
+No signal from any of the three is not a stop. Draft against a neutral default and tag the color and type choices `? verify` per `${CLAUDE_SKILL_DIR}/../../standards/design.md`'s uncertainty tag.
+
+## Step 2: detect the icon size sequence
+
+Check the project's HTML entry points (`index.html`, `public/index.html`, `src/index.html`) for a `<link rel="icon">` or `<link rel="apple-touch-icon">` tag carrying a `sizes` attribute, and any `manifest.json` or `site.webmanifest` for an `icons` array. Take the union of every size found.
+
+Fall back to the stated default when nothing is detected, since no `tooling/` stack scaffolds a `public/` folder, a favicon reference, or an `og:image` meta tag:
+
+- `16x16`, `32x32`, `48x48`
+- `180x180`
+- `192x192`, `512x512`
+
+This default set is raster-only. Step 6 already writes the vector source at `favicon.svg` regardless of which branch decided the sequence, so a project willing to reference an SVG favicon directly is covered either way.
+
+Announce which of the two decided the sequence.
+
+## Step 3: detect the write folder
+
+Check for `public/`, `static/`, or a stack-declared asset folder, taking the first that exists. Fall back to the project root when none is detected, mirroring `claude-design-extract`'s own source-versus-greenfield split. Announce the folder so the operator can move the files if the project's own convention differs.
+
+## Step 4: name the decision and the arms
+
+Follow `${CLAUDE_SKILL_DIR}/../draft-and-pick/SKILL.md` Step 1, with the decision fixed rather than derived: "the project's logo mark and its composition into the social card." Vary the mark's shape or style across arms, keeping the card's type and layout fixed, per that skill's one-property rule. Draft each arm already inside the full 1200x630 card frame, mark and type together, so the pick settles the shape and the composition in one choice. Arm 0 is the current mark when the folder from Step 3 already holds a logo file (`favicon.svg`, `favicon.ico`, `logo.svg`, or similar). Arms start at 1 otherwise.
+
+Structure every arm as a `.mark` element, the inline SVG alone, nested inside a `.card` element, the full composition, so Step 6 can address either without re-deriving them.
+
+## Step 5: draft, render, pick, and loop
+
+Follow `${CLAUDE_SKILL_DIR}/../draft-and-pick/SKILL.md` Steps 2 through 5 against the arms from Step 4: author the page, render and hand off, take the pick, and loop on it.
+
+## Step 6: finalize
+
+This step replaces `draft-and-pick`'s own Step 6, since the pick here produces several final files rather than one applied surface.
+
+1. Extract the picked arm's `.mark` markup as the final vector source. Write it to `<write-folder>/favicon.svg`.
+2. Under `<dest>/render/`, write one page per Step 2 size plus one for the card. Give every page's captured element the shared class `.render`, so one capture call renders the whole batch regardless of the size spread. `canon capture` opens every page at a fixed 2x device scale factor and screenshots the element at that scale, so declare each `.render` element at half its target dimension, `<w>/2` by `<h>/2`, to land the captured PNG on the literal target size rather than double it. Declare a machine-resolved font stack (`system-ui` behind a generic fallback) on each, since `canon capture` refuses a page naming no font at all.
+   - `icon-<w>x<h>.html`: the picked `.mark` markup, its `.render` wrapper sized `<w>/2` by `<h>/2`
+   - `og-image.html`: the picked `.card` markup, its `.render` wrapper sized 600x315 to capture at the native 1200x630
+3. Render the batch:
+
+   ```bash
+   canon capture <dest>/render --selector .render --out <write-folder>
+   ```
+
+4. Report each written file's path and the dimensions `canon capture` printed for it, confirming each equals its Step 2 target rather than half of it.
+5. Delete `<dest>`, per `draft-and-pick`'s own scratch-folder rule.
+
+## Response format
+
+```plaintext
+📝 Wrote <write-folder>/favicon.svg
+📝 Wrote <write-folder>/icon-16x16.png (16x16)
+📝 Wrote <write-folder>/og-image.png (1200x630)
+
+Write folder: <detected <path>|defaulted to project root>. Move the files if this project's own convention differs.
+```
+
+## What this delegates
+
+Cite these rather than restating them.
+
+- `draft-and-pick` owns Steps 1 through 5 of the render-and-pick loop, cited above
+- `claude-design-extract` owns building `.claude/DESIGN.md`. This skill only reads it.
+- `canon capture` owns the render mechanics, its font refusal, and its reported dimensions

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/claude/skills/test-first/REQUIREMENT.md

@@ -0,0 +1,34 @@
+---
+name: test-first
+description: Why the loop exists and where it stops short of a debugging session or a visual check
+---
+
+# Test first requirement
+
+## Gap
+
+Without this skill, a session implementing a planned change writes the test after the code, or writes both in one motion and never runs the test against the code as it stood before. Either way, nothing showed that the test would have caught the defect it exists to catch, so a test added after the fact protects nothing beyond what the author was already confident about.
+
+## Must
+
+- Write or extend the test before the implementation it covers, for any behavior whose shape is already known
+- Run the test before implementing and confirm it fails for the missing behavior, not for an unrelated mistake in the test itself
+- Implement the minimum the current test demands, and start a new test before extending past it
+- Re-run the test after implementing and confirm the pass is the one the test was written to prove
+
+## Must not
+
+- Write the implementation and the test together with the test never run red first
+- Treat a test that already passes before any code change as evidence for the new behavior
+- Restate the reproducing-test step `canon:systematic-debugging` already owns for a failure with no known cause
+- Decide whether a change looks right visually, which runs after implementation as a separate check
+
+## Guards
+
+- A test failing for a reason other than the missing behavior blocks moving to implementation. Fix the test first.
+
+## Out of scope
+
+- Finding the cause of an unexplained failure: `canon:systematic-debugging`
+- Confirming visual output after a change lands: `070-planning.md` states the order and `claude-ui-test` covers it
+- The mechanical audit of whether an implementation reached history ahead of its test: `canon gov test-order`, invoked from `claude-autoship`

package/claude/skills/test-first/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: test-first
+description: Write the failing test for a behavior before writing the code that satisfies it, confirm it fails for the right reason, then implement the smallest change that turns it green. Auto-triggers before implementing a planned feature, adding a function or an endpoint, or extending existing behavior whose new shape is already decided. Do NOT use for a failure with no known cause, which is canon:systematic-debugging, or when the test for the behavior already exists and already passes.
+---
+
+# Test first
+
+## The loop
+
+1. Find or write the test for the behavior before touching the code it covers. Follow the pairing convention the project already uses, which is commonly a test sitting beside its subject under one name, so that `foo.ts` takes `foo.test.ts` beside it.
+2. Write the test against the behavior as it should exist once the change lands, naming the case for what it proves rather than for the function it calls.
+3. Run only that test and read the failure. Confirm it fails because the behavior is missing, not because of a typo, a missing import, or a signature the test itself got wrong. A test failing for the wrong reason still reads green the moment any code exists to satisfy that wrong reason, so treat any other failure as a defect in the test and fix the test before moving on.
+4. Implement the smallest change that turns the failure into a pass. Do not add behavior the test does not ask for. A second behavior wants its own test written first, not a shortcut folded into the change already open.
+5. Run the test again and confirm it passes for the reason it was written for, not by accident. Then run the surrounding suite so a change made to satisfy this test has not broken another.
+
+## Extending existing behavior
+
+- Changing what a function already does starts with changing what its test asserts. Run that changed test once before touching the implementation, and confirm it fails against the code as it stands today.
+- A test that already passes before any code changes proves nothing about the new behavior. Widen the assertion or add a case until the suite fails against the current implementation.
+
+## What this skill does not cover
+
+- A failure with no known cause. Route through `canon:systematic-debugging` first, whose own fix phase already writes the reproducing test as part of finding the cause. This skill starts once the shape of the fix or the feature is already decided.
+- Confirming a change looks right once it has landed, which is a separate concern from whether the test passed and runs after implementation rather than before it.

package/docs/agents/demo.md

@@ -23,6 +23,8 @@ So `canon demo compile` writes a second artifact rather than adding fields to a
 
 The plan is committed, not scratch. Its timing is a starting point tuned by watching a recording, and the draft cannot reproduce a tuned value, so a recompile over an existing plan refuses and names `--force`.
 
+`canon-record` is the routed way to run both verbs from a draft path: it compiles only when no plan exists yet, then runs, stopping to report any field still unresolved rather than guessing one.
+
 | Option          | Behavior                                                          |
 | --------------- | ----------------------------------------------------------------- |
 | `--out <dir>`   | Directory the plan and its output paths point at, default `demos` |

package/docs/agents/review-classification.md

@@ -64,13 +64,13 @@ An empty set refuses with `no-changes` rather than skipping. Both tests are univ
 
 ## Why it is a verb
 
-The decision was three sentences in `claude-autoship` Step 5, applied by a session reading a bulleted list of paths. It failed three times. A driven arm on 2026-08-30 staged `.claude/skills/deploy-check/SKILL.md`, which that list names, and the chain skipped review and opened a draft pull request anyway. The rule was correct and the session did not apply it, and the two fixes before that one were each a rewrite of the same prose.
+The decision was three sentences in `claude-autoship`'s review step, applied by a session reading a bulleted list of paths. It failed three times. A driven arm on 2026-08-30 staged `.claude/skills/deploy-check/SKILL.md`, which that list names, and the chain skipped review and opened a draft pull request anyway. The rule was correct and the session did not apply it, and the two fixes before that one were each a rewrite of the same prose.
 
 A rule a session can talk itself out of moves into a verb. That is the same argument the quiz-order draw in `canon teach lesson` was decided on: an instruction is a hope where a verb is a check.
 
 ## The written fallback
 
-The verb ships with the CLI and Step 5 ships with the plugin, so a target holding an older binary meets a missing subcommand. The skill body keeps the written list and applies it by hand there, naming which of the two decided the run.
+The verb ships with the CLI and Step 6 ships with the plugin, so a target holding an older binary meets a missing subcommand. The skill body keeps the written list and applies it by hand there, naming which of the two decided the run.
 
 The fallback is never a skip. Failing open is the exact defect the verb closes, so a body that skips on anything other than a `skip` record would ship every branch unreviewed the moment the subcommand went absent.
 

package/docs/workflow/ai-workflow.md

@@ -157,7 +157,7 @@ The list stays written in the skill body as the fallback for a target whose inst
 
 #### Memory in the chain
 
-`git-ship` runs its verify gate and then opens on `claude-memory-capture`, which sends what the session learned to the surface that owns it. `autoship` reaches the same step by invoking that skill at its Step 7 rather than restating the order. A fact about a domain carrying an entry in `.claude/context/index.md` is routed to that entry, and `claude-docs` folds it in on the next step, so it ships in the same pull request. Anything no entry owns stays a file in `.canon/memory/`.
+`git-ship` runs its verify gate and then opens on `claude-memory-capture`, which sends what the session learned to the surface that owns it. `autoship` reaches the same step by invoking that skill at its Step 8 rather than restating the order. A fact about a domain carrying an entry in `.claude/context/index.md` is routed to that entry, and `claude-docs` folds it in on the next step, so it ships in the same pull request. Anything no entry owns stays a file in `.canon/memory/`.
 
 Capture leads rather than trails because a routed fact edits a tracked file, which has to reach the branch before the commit steps run.
 
@@ -219,13 +219,14 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Build the feature
 
-| Skill                        | When to use                                                         |
-| ---------------------------- | ------------------------------------------------------------------- |
-| `canon:claude-worktree`      | At the plan-to-execute boundary, to get an isolated tree and branch |
-| `canon:claude-autoship`      | After plan approval, to chain implement, verify, review, draft PR   |
-| `canon:project-commands`     | When the project's own command needs running                        |
-| `canon:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first      |
-| `canon:claude-ui-test`       | After a UI change, to generate e2e tests and a visual checklist     |
+| Skill                        | When to use                                                               |
+| ---------------------------- | ------------------------------------------------------------------------- |
+| `canon:claude-worktree`      | At the plan-to-execute boundary, to get an isolated tree and branch       |
+| `canon:claude-autoship`      | After plan approval, to chain implement, verify, review, draft PR         |
+| `canon:project-commands`     | When the project's own command needs running                              |
+| `canon:test-first`           | Before implementing a planned change, to write and run its test red first |
+| `canon:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first            |
+| `canon:claude-ui-test`       | After a UI change, to generate e2e tests and a visual checklist           |
 
 ### Check the work before it leaves the branch
 
@@ -291,25 +292,28 @@ 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:draft-readme`       | For a project's `README.md`, drafted against `standards/readme.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                                                                |
 | `canon:canon-slides-draft` | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                             |
 | `canon:canon-screencast`   | For a recording script with beats and defaults already seeded                                     |
+| `canon:canon-record`       | For compiling and running a screencast draft into a recording and a still                         |
+| `canon:identity`           | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop       |
 
 ### 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/docs/workflow/visual-design-workflow.md

@@ -40,6 +40,7 @@ A cell no source anchors ends in `? verify`, and the preview shows that marker b
 - `canon:claude-ux-audit` for UX gap detection on existing surfaces
 - `canon:claude-ux-measure` for what a running surface costs to paint, read against published thresholds
 - `canon:draft-and-pick` for a call settled by looking, drafting several candidates onto one page and taking your pick
+- `canon:identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop
 - Anthropic's `frontend-design` plugin optional for light visual steering
 
 ### When to pick

package/governance/rules/core/070-planning.md

@@ -13,6 +13,7 @@ description: Enforce planning standards before implementation
 - Propose the simplest solution that satisfies the requirement before implementing complex patterns.
 - Write or update tests as part of every implementation plan.
 - Write the test for a behavior before the code that implements it. Confirm visual output after implementing it, not before.
+- Load the `canon:test-first` skill before writing the implementation for a behavior whose test does not exist yet, and report it rather than proceeding silently when the skill does not resolve.
 - Run `canon gov test-order` before shipping a branch. Fix what it names as reaching history ahead of its test.
 - Load the `canon:systematic-debugging` skill before proposing a fix for a failing test, a surfaced bug, or behavior nobody has explained yet, and report it rather than proceeding silently when the skill does not resolve.
 - Do not modify code without a confirmed plan.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.62.1",
+  "version": "4.64.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -62,9 +62,11 @@
     "@tailwindcss/vite": "^4.2.4",
     "@testing-library/jest-dom": "^6.9.1",
     "@types/bun": "^1.2.10",
+    "@types/micromatch": "^4.0.10",
     "astro": "^6.1.9",
     "cspell": "^8.17.1",
     "husky": "^9.1.7",
+    "micromatch": "^4.0.8",
     "prettier": "^3.8.1",
     "prettier-plugin-astro": "^0.14.1",
     "prettier-plugin-tailwindcss": "^0.7.2",

package/scripts/core/regen-agent-fixture.sh

@@ -202,7 +202,7 @@ const summary = {
 }
 
 const fixture = {
-  // Read by web/src/components/AgentView.astro. Every field below is either a
+  // Read by web/src/components/agent-view.astro. Every field below is either a
   // live read or a hand transcription, and this header is what says which.
   generatedBy: "scripts/core/regen-agent-fixture.sh",
   readAt: READ_AT,

package/src/claude/cases/authoring.ts

@@ -40,17 +40,21 @@ 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: 'This project has no README.md at all, write one from scratch.',
+    expect: 'draft-readme',
   },
   {
     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/claude/cases/claude-workflow.ts

@@ -79,6 +79,11 @@ export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
     prompt: 'Post a formal review with findings on that open pull request.',
     expect: 'claude-pr-review',
   },
+  {
+    prompt:
+      'The screencast draft is finished. Turn it into an actual video now.',
+    expect: 'canon-record',
+  },
   {
     prompt:
       'Look over everything that changed on this branch for bugs and edge cases.',

package/src/claude/cases/misc.ts

@@ -12,6 +12,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'Show me a few different treatments for this callout so I can pick one by looking.',
     expect: 'draft-and-pick',
   },
+  {
+    prompt:
+      'This project has no logo yet. Draft one and give me a social card to go with it.',
+    expect: 'identity',
+  },
   {
     prompt: 'Fire up the dev server the way this project documents it.',
     expect: 'project-commands',
@@ -29,6 +34,11 @@ export const MISC_CASES: readonly SkillCase[] = [
     prompt: "This test just started failing and I don't know why yet.",
     expect: 'systematic-debugging',
   },
+  {
+    prompt:
+      "I'm about to write the retry helper we settled on and nothing covers it yet, so get the failing case in first.",
+    expect: 'test-first',
+  },
   {
     prompt: 'Does our github about text still match what the readme says?',
     expect: 'repo-metadata',

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/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/standards/readme.md

@@ -46,6 +46,8 @@ Scoped to the README at a repository root. A nested README documenting a folder,
 - Do not include license text. Reference the `LICENSE` file.
 - Do not include detailed contribution guidelines. Reference `CONTRIBUTING.md`.
 - Do not include extensive troubleshooting guides. Use a wiki or separate documentation.
+- A README that points to the project's own context entries instead of restating them satisfies the required list by routing rather than carrying. A repository documented in `docs/` or `.claude/context/` names the entry point and the listing command, then stops. The reader is one hop away, the same way `## Badges` treats zero as complete.
+- A README missing an H1, or whose headings restate the tool that scaffolded it rather than the project, is unedited generator output rather than a page anyone wrote. Draft over it. Nothing here asks a session to preserve a section a scaffold wrote and nobody replaced.
 
 ### Badges
 

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

@@ -50,10 +50,16 @@ export default defineConfig([
       ],
       'check-file/folder-naming-convention': [
         'error',
-        { 'src/**/!(__tests__|pages)': 'KEBAB_CASE' },
+        { 'src/**/!(__tests__)/': 'KEBAB_CASE' },
       ],
     },
   },
+  {
+    files: ['src/pages/**/*.{ts,tsx,astro}'],
+    rules: {
+      'check-file/folder-naming-convention': 'off',
+    },
+  },
   {
     files: ['**/*.{jsx,tsx}'],
     plugins: {

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). 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.
+- `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` reaches every `src/**` folder except `__tests__` and the whole `pages/` subtree, which carries its own off-block for the bracket-named dynamic routes and nested slug folders Astro's file-based routing produces. See `.claude/context/tooling.md` for the measurement.
 
 ## Typecheck