@erclx/aitk 0.11.0 → 0.13.0

package/README.md

@@ -1,5 +1,9 @@
 # aitk
 
+[![npm version](https://img.shields.io/npm/v/@erclx/aitk)](https://www.npmjs.com/package/@erclx/aitk)
+[![CI status](https://img.shields.io/github/actions/workflow/status/erclx/aitk/verify.yml?branch=main)](https://github.com/erclx/aitk/actions/workflows/verify.yml)
+[![License MIT](https://img.shields.io/npm/l/@erclx/aitk)](LICENSE)
+
 One source for your repos' AI conventions. Install once, sync everywhere.
 
 ![Adding the aitk marketplace and installing the plugin in Claude Code](assets/install.png)
@@ -39,7 +43,7 @@ Two limits worth knowing before you install. Claude Code is the only agent runti
 
 Each domain has a canonical source in this repo and a thin install or sync CLI on your side. The links run to internal narrative, written for someone maintaining the toolkit rather than installing it, so skip them on a first pass.
 
-- [Claude Code plugin](.claude/context/claude-plugin.md): skills for planning, review, docs sync, and the git ship chain
+- [Claude Code plugin](.claude/context/claude-plugin/index.md): skills for planning, review, docs sync, and the git ship chain
 - [Governance rules](.claude/context/governance.md): Cursor rules and stacks, installable per project
 - [Standards](.claude/context/standards.md): shared authoring conventions, synced to projects
 - [Snippets](.claude/context/snippets.md): reusable prompts for Claude and Gemini chat

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

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

package/claude/skills/bash-script/SKILL.md

@@ -35,7 +35,7 @@ Load `${CLAUDE_SKILL_DIR}/references/patterns.md` for the timeline lifecycle, lo
 - Name functions verb-first: `validate_input`, `deploy_service`, `install_dependencies`.
 - Do not use global variables except exports from `ask()`.
 - Do not define unused color variables.
-- Do not include comments except the shebang line.
+- Comment only a fact the reader cannot recover from the code, and follow the code-comment rule in `.claude/rules/` when the project installs it.
 - Use sentence case for section headers and log messages. Proper nouns and product names retain their casing.
 - Quote variables inside parameter expansions: `"${file#"$dir"/}"` not `"${file#$dir/}"`.
 - Quote variables in test brackets: `[ "$i" -eq "$cur" ]` not `[ $i -eq $cur ]`.

package/claude/skills/claude-diagram/SKILL.md

@@ -55,6 +55,7 @@ One file per kind at `.claude/diagrams/<kind>.md`. Write only the files Step 2 s
 title: <what the entry answers, sentence case>
 description: <the question it settles and the signal that drives it>
 category: <the kind, matching the standard>
+verified: 'TODO: never verified'
 ---
 
 # <Same as title>
@@ -71,8 +72,12 @@ category: <the kind, matching the standard>
 <one to three explanation paragraphs>
 ````
 
+Write `verified` as the literal `TODO: never verified` here, quoted so the colon parses. Step 6 replaces it once a render has been read back, so a SHA written beside the diagram would assert a check that has not run yet. The placeholder is what keeps a render-less project conforming, since Step 5 sends a failed render past Step 6 and nothing stamps the entry. Carry an existing entry's current value across untouched when this pass is rewriting one, and let Step 6 replace that instead.
+
 When sources came from a code scan rather than planning prose, lead the explanation with `Source: code.` and add `Fidelity is lower than prose-driven diagrams. Verify against the project's intent.`
 
+The code paths the explanation cites are what the `claude-docs` sweep watches for staleness, so cite paths that exist and spell them exactly.
+
 Quote node labels containing spaces or special characters with double quotes (`A["Web shell"]`). Avoid parentheses inside labels, they break some renderers. Use `<br/>` for line breaks inside labels.
 
 Run the banned-character scan in `.claude/standards/prose.md` against the whole file, including inside mermaid `subgraph` labels and node text, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it. A colon also works as a replacement inside a label. The pedagogical voice the diagram standard asks for is a yield on voice alone and buys no exemption from these bans.
@@ -123,6 +128,20 @@ Fix the source and re-render. Stop after two correction passes on an entry.
 
 When a defect survives, keep the entry and name the defect in the chat output. A diagram whose author states the flaw is recoverable. A wrong diagram reported as verified is not.
 
+### Stamp the marker
+
+Stamp every entry that passed. Set `verified` to the short SHA of `HEAD` and today's ISO date, and delete any `stale` key the `claude-docs` sweep left on it:
+
+```bash
+git rev-parse --short HEAD
+```
+
+The result is one line, `<sha> <date>`, as in `73e9a3f8 2026-08-02`.
+
+Stamp nothing else. An entry Step 2 left alone was never re-checked, an entry whose defect survived is known wrong, and an entry whose render was skipped was never seen. All three keep the marker they already carry, and Step 7 names the last two. The field means a render was read back and judged correct, so stamping any of these spends the only signal a reader has on a diagram nobody confirmed.
+
+A migration pass stamps on the same rule. Conversion writes entries, Step 5 renders them, and this step reads them back, so the marker records the commit the split was checked against rather than the commit the flat file was written at.
+
 ## Step 7: chat output
 
 ```plaintext

package/claude/skills/claude-docs/SKILL.md

@@ -9,11 +9,11 @@ description: Updates `.claude/` planning docs to reflect decisions made during t
 
 - If no `.claude/` directory exists, stop: `❌ No .claude/ directory found. Run aitk claude init to set up the workflow.`
 
-The bail on a session that changed nothing lives at the end of Step 2, because it needs the diff to decide.
+The skip for a session that changed nothing lives at the end of Step 2, because it needs the diff to decide. It drops the doc rewrite alone. The diff-driven sweeps in Steps 4 and 5 still run.
 
 ## Diff baseline
 
-Steps 2, 4, and 7 share one diff on the usable path. An unusable baseline splits them, per the rule below. Resolve the base ref once and reuse it:
+Steps 2, 4, 5, and 7 share one diff on the usable path. An unusable baseline splits them, per the rule below. Resolve the base ref once and reuse it:
 
 ```bash
 git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
@@ -32,9 +32,9 @@ An unusable baseline costs only the committed half. `git diff <base> HEAD` is em
 
 **Step 2 recovers the committed half.** Read `git log -p -1`, widening to `git log -p -<n>` when the session spans several commits, and read the candidate task files against the working tree. That yields names and content both, which is what lets Step 2 decide on behavior rather than on filenames. A fresh `git init` on `main` with no remote is the ordinary shape of a scaffolded project, so this path carries the evidence rather than covering an edge case.
 
-**Steps 4 and 7 keep the scoped set.** Run them on the working tree and untracked files alone, and skip only when that set comes out empty, each reporting the warning its own step names.
+**Steps 4, 5, and 7 keep the scoped set.** Run them on the working tree and untracked files alone, and skip only when that set comes out empty, each reporting the warning its own step names.
 
-Never substitute the whole tree for a missing baseline, and do not reuse Step 2's commit read in these two for consistency. On a fresh `git init` project the last commit is the scaffold commit, so `git log -p -1` is the whole tree by another route. Step 2 tolerates that because it only reads, and it matches conservatively against outcomes already on the board. These two write, so the same set stubs a wireframe for every uncovered surface in the repository and rewrites every context entry that tree touches.
+Never substitute the whole tree for a missing baseline, and do not reuse Step 2's commit read in these three for consistency. On a fresh `git init` project the last commit is the scaffold commit, so `git log -p -1` is the whole tree by another route. Step 2 tolerates that because it only reads, and it matches conservatively against outcomes already on the board. These three write, so the same set stubs a wireframe for every uncovered surface in the repository, stubs a diagram for every source signal the scaffold introduced, and rewrites every context entry that tree touches.
 
 Widening what a step reads is safe. Widening what a step writes is not.
 
@@ -70,7 +70,17 @@ Keep the match conservative:
 - Match on the behavior an outcome describes, not on filenames or commit subjects. The path match above only narrowed which task files to open.
 - Leave an outcome `[ ]` when the diff is ambiguous. An unmarked shipped outcome costs one manual edit, while a wrongly marked one hides work that never happened.
 
-Stop here when the session shows no divergence **and** the diff matches no queued outcome: `✅ No doc updates needed. Session matched the original plan.` Both conditions have to hold. Shipping a queued task exactly as planned is the ordinary case and it reads as no divergence, so a session-only bail would stop the skill before it reaches the marking step.
+Skip Step 3 when the session shows no divergence **and** the diff matches no queued outcome, reporting `✅ No doc updates needed. Session matched the original plan.` Both conditions have to hold. Shipping a queued task exactly as planned is the ordinary case and it reads as no divergence, so a session-only skip would drop the marking step with it.
+
+Then run Steps 4 through 8. Step 3 is the only one this skips, because it is the only one driven by the session rather than by the diff or the board. A project with an empty task board making a mechanical change satisfies both conditions above, and stopping here would put an uncovered surface and an uncovered diagram kind out of reach in every such project.
+
+Three of the steps that follow write, so each earns the reach separately:
+
+- Steps 4 and 5 stub against the diff. These are why the skip is not a stop. A session that changed no docs is exactly when an uncovered surface or diagram kind goes unnoticed.
+- Step 7 rewrites context entries against the diff. The Diff baseline section above already groups it with Steps 4 and 5 as a scoped-set step, so a quiet session is no different from any other for it.
+- Step 8 reads the board rather than the session. Its board-wide scan exists to clear a plan an earlier run stranded, and a run that stops at Step 2 can never reach one.
+
+This changes which steps the skill reaches. It does not widen what any of them reads. Steps 4, 5, and 7 still take the same scoped set the Diff baseline section defines, and that section's rule is about the input a write is handed rather than about which writes run.
 
 ## Step 3: update
 
@@ -127,13 +137,59 @@ Output one line per finding:
 
 If the sweep finds nothing, skip silently.
 
-## Step 5: flag diagram staleness
+## Step 5: diagram staleness sweep
+
+Skip this step silently when `.claude/diagrams/` does not exist at `pwd` or holds no entry. An entry is any `*.md` other than `index.md`, so a folder carrying the catalog alone is an empty set. A project that has never run `claude-diagram` is not told on every ship that it has holes. When the baseline is unusable, scope the sweep to the working tree and untracked files, and skip it only when that set is empty, reporting `⚠ No diff to scope against. Skipped the diagram sweep.`
+
+This step writes frontmatter and never content. Mermaid bodies and explanation paragraphs are off limits to it. A change that removes a module does not carry the new correct shape of the picture, so rewriting a diagram from it produces a confident wrong diagram, which is worse than the stale one it replaced. The author redraws by running `claude-diagram`.
+
+Follow `.claude/standards/diagrams.md` for the marker fields this step writes, or `${CLAUDE_SKILL_DIR}/../../standards/diagrams.md` when the project does not have it.
+
+Both findings key on something literally entering or leaving the tree. Anything looser fires on ordinary feature work and rebuilds the ignored warning this sweep replaced.
+
+**Contradicted entries.** For each entry, collect the backticked code paths its explanation cites. When a cited path is in the diff as a delete or a rename and no longer exists in the tree, append a `stale` key to that entry's frontmatter naming the path:
+
+```yaml
+stale: 'src/gov/install.ts no longer exists'
+```
+
+Append that key alone. Never edit `verified`, `title`, `description`, or `category`, and never touch the body. When the entry already carries `stale`, extend the existing line rather than adding a second key.
+
+**Uncovered kinds.** The standard fixes one source signal per kind. Stub a kind when the diff adds its signal file and no entry covers that kind. The trigger is the signal appearing, never a file under it changing, so a branch editing a component folder that `components.md` already covers produces nothing here.
 
-If `.claude/DIAGRAMS.md` exists at `pwd` and this session edited any source `claude-diagram` reads (planning docs, deploy or infrastructure config, top-level component folders), surface a one-line warning:
+| Signal added by the diff                                                                                           | Kind stubbed when absent |
+| ------------------------------------------------------------------------------------------------------------------ | ------------------------ |
+| `.claude/REQUIREMENTS.md`                                                                                          | `system-context.md`      |
+| `.claude/ARCHITECTURE.md`                                                                                          | `components.md`          |
+| A deploy or infrastructure config (`Dockerfile`, `.github/workflows/*`, `vercel.json`, `fly.toml`, `compose.yaml`) | `deployment.md`          |
 
-`⚠ DIAGRAMS.md may be stale. Run /claude-diagram`
+Leave `request-flow.md` and `data-pipeline.md` out. Neither has a source signal a diff can point at, so a rule covering them would guess at when they went stale.
 
-Do not regenerate inline. The author decides when to re-run the diagram skill. Skip the step silently when `.claude/DIAGRAMS.md` does not exist.
+Write the stub at `.claude/diagrams/<kind>.md`:
+
+```markdown
+---
+title: <Kind as title case>
+description: 'TODO: name the question this entry settles.'
+category: <the category the standard fixes for this kind>
+verified: 'TODO: never verified'
+---
+
+# <Kind as title case>
+
+TODO: draw this. `<signal path>` entered the tree with no entry covering this kind.
+
+Run `/claude-diagram <kind>` to replace the stub.
+```
+
+No mermaid fence. An empty stub is visible debt that reaches review through the branch diff, while a generated diagram nobody rendered is invisible debt that reads as verified. A fence here invites the next session to fill it in without a render.
+
+Output one line per finding:
+
+- `⚠ Diagram stale: .claude/diagrams/<kind>.md cites <path>, which left the tree`
+- `📝 Stubbed: .claude/diagrams/<kind>.md`
+
+If the sweep finds nothing, skip silently. An ordinary change that adds no signal and deletes no cited path produces no output at all.
 
 ## Step 6: flag CLAUDE.md drift
 
@@ -202,3 +258,5 @@ Output one line per file updated:
 If no files were updated and nothing was swept, output:
 
 `✅ No changes needed.`
+
+Suppress that line when Step 2 already reported no doc updates. It closes the run on its own, and emitting both leaves a quiet session reporting success twice for one outcome.

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

@@ -85,6 +85,8 @@ Flag only issues that will definitely cause incorrect behavior or break a docume
 - Linter territory
 - Issues that depend on unverified state
 
+A comment that makes a false claim about the code is a correctness finding, not a style one. Flag it past the exclusions above and let the severity ladder rank it.
+
 If uncertain, do not flag. False positives erode trust.
 
 ### Severity

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

@@ -33,7 +33,7 @@ Load `${CLAUDE_SKILL_DIR}/references/template.md` for the base skeleton. Copy it
 - Decompose by responsibility. Each function does one thing, `main()` orchestrates.
 - Name functions verb-first: `parse_args`, `fetch_data`, `validate_input`.
 - Quote variables in expansions and test brackets.
-- Do not include comments except the shebang line.
+- Comment only a fact the reader cannot recover from the code, and follow the code-comment rule in `.claude/rules/` when the project installs it.
 - Use 2-space indentation.
 
 ## Validation

package/claude/skills/create-standard/SKILL.md

@@ -7,7 +7,7 @@ description: Creates a new standard file in `standards/` (toolkit repo) or `.cla
 
 Read these files in parallel:
 
-- `${CLAUDE_SKILL_DIR}/references/standard.md`: the meta-standard for a standard's shape, frontmatter, and structure
+- `.claude/standards/standard.md` from the project root: the meta-standard for a standard's shape, frontmatter, and structure
 - `.claude/standards/prose.md` from the project root: prose conventions for all generated text
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.

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

@@ -35,4 +35,4 @@ What each `aitk` sync or install command does to existing files in a target proj
 
 ## Source of truth
 
-- Full semantics live in the toolkit's `.claude/context/tooling.md`, `standards.md`, and `claude-plugin.md`. This skill is the target-session summary. When they disagree, the context docs win.
+- Full semantics live in the toolkit's `.claude/context/tooling.md`, `standards.md`, and `claude-plugin/`. This skill is the target-session summary. When they disagree, the context docs win.

package/docs/agents.md

@@ -204,14 +204,16 @@ aitk sandbox check claude:docs drift --json
 
 | Flag                | Effect                                                     |
 | ------------------- | ---------------------------------------------------------- |
-| `--envelope <file>` | Read `is_error`, `num_turns`, and denials from a run       |
+| `--envelope <file>` | Read `is_error`, `num_turns`, denials, and the reply text  |
 | `--writes <file>`   | Newline-delimited paths the session wrote, for write scope |
 | `--json`            | Emit the verdict record on stdout                          |
 | `--strict`          | Exit 1 on `unchecked` instead of 0                         |
 
 The verdict `state` is `pass`, `fail`, or `unchecked`. An arm with no `expect.toml` is `unchecked` and exits 0, so the harness stays usable while expectations roll out. A declaration that exists but asserts nothing is a failure, since an expectation file that asserts nothing passes every run.
 
-Omitting `--writes` or `--envelope` does not silently drop the assertion kinds that need them. Write scope and the turn ceiling report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. A verdict never reports `pass` with zero assertions.
+Omitting `--writes` or `--envelope` does not silently drop the assertion kinds that need them. Write scope, the turn ceiling, and the reply assertion report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. A verdict never reports `pass` with zero assertions.
+
+An envelope that parses but carries no `result` field skips the reply assertion the same way an absent file does. An envelope carrying an empty `result` fails it, since a run that returned no text is a finding rather than a gap in the input.
 
 Exit 0 means `pass` or `unchecked`. Exit 1 means `fail`, or a caller error: a malformed target, or a sandbox that was never provisioned. A missing sandbox reports as an error rather than a failed verdict, because failing every path assertion would read as a skill that did nothing. `--strict` moves `unchecked` to exit 1 for a caller that has finished arming its scenarios.
 
@@ -239,6 +241,8 @@ The record carries every scenario with the arms that declare, plus `totalScenari
 - `aitk docs list [--json]` lists the downstream catalog: the consumer-facing `docs/` surface plus per-domain narrative from `.claude/context/` when that root is present. Toolkit-internal context entries (`ci`, `development`, `extensions`, `sandbox`) are dropped. From a registry install the context section is absent rather than empty.
 - `aitk docs <topic>` prints one doc to stdout, resolved by exact name from `docs/` first, then `.claude/context/`. Any doc the install carries is reachable by name, including the toolkit-internal topics the list omits.
 
+A domain too large for one file splits into `<domain>/` with a generated `index.md`, and both verbs name it by the folder. `aitk docs <domain>` prints that index, which is the catalog routing to the sub-area files, and the listing describes it from the index's `subtitle` where a sibling file supplies `description`. A sibling file wins over a folder of the same name. A folder carrying no `index.md` is absent from both, since a catalog is what makes the sub-areas reachable.
+
 Data prints to stdout and the frame to stderr, so `aitk docs <topic> > out.md` captures clean markdown. With no topic and no verb, `aitk docs` runs `list`. An unknown topic names the available topics on stderr and exits 1.
 
 Only a `---` block opening on the first line counts as frontmatter, so a document body carrying horizontal rules emits whole.
@@ -321,6 +325,8 @@ Two exclusions are structural rather than tuning. Heredoc bodies are dropped fro
 
 The degradation sweep reads its vocabulary from whichever rule publishes a `## Degradation vocabulary` heading, preferring `.claude/rules/` over `governance/rules/`, so one definition serves the toolkit and every target. Discovery anchors on the heading rather than a filename, because a renumbered rule would otherwise empty the vocabulary while the sweep still reported clean. With no such rule the sweep reports **skipped** rather than zero hits, since finding nothing and looking for nothing mean opposite things.
 
+`090-code-comments` is the rule that publishes the list, and it ships on the `base` stack. A project that installs or syncs governance for the first time after that rule landed gets a sweep that previously reported skipped, so hits appear where the command used to stay quiet. Edit the backticked terms in the installed copy to change what that project sweeps for. The sweep matches comment text, so a comment naming a term as an example is a hit, and a hit is a prompt to read the line rather than a verdict on it.
+
 ## Runtime catalogs
 
 Use these to discover what's available instead of hardcoding names.

package/docs/ai-workflow.md

@@ -20,12 +20,13 @@ Project docs live in `.claude/` at the project root.
 ├── ARCHITECTURE.md  ← technical design decisions
 ├── DESIGN.md        ← visual intent and token decisions (UI projects)
 ├── WIREFRAMES.md    ← ASCII wireframes: layout, UI copy, and interaction rules (UI projects)
+├── diagrams/        ← one Mermaid entry per diagram kind with a generated index.md
 ├── tasks/           ← one file per task with a generated index.md, gitignored local scratch
 ├── context/         ← per-domain narrative loaded on demand via index.md
 └── rules/           ← path-scoped governance rules, written by aitk gov install
 ```
 
-Three tiers of context load with different cost: always-loaded (root `CLAUDE.md`, `.claude/REQUIREMENTS.md`, `.claude/ARCHITECTURE.md`), path-scoped lazy (`.claude/rules/<scope>.md` with `paths:` glob), and on-demand lookup (`.claude/context/<domain>.md` discovered via `.claude/context/index.md`). See [the context model](../.claude/context/context-model.md) for the full picture.
+Three tiers of context load with different cost: always-loaded (root `CLAUDE.md`, `.claude/REQUIREMENTS.md`, `.claude/ARCHITECTURE.md`), path-scoped lazy (`.claude/rules/<scope>.md` with `paths:` glob), and on-demand lookup (`.claude/context/<domain>.md`, or `.claude/context/<domain>/` once a domain outgrows one file, discovered via `.claude/context/index.md`). See [the context model](../.claude/context/context-model.md) for the full picture.
 
 Run `aitk init` to seed the `.claude/` directory, a root `CLAUDE.md` file, and `.claude/rules/` in one pass. `aitk init` chains claude init and governance install. Claude Code auto-loads every file in `.claude/rules/` at session start, applying always-on rules unconditionally and path-scoped rules to files matching their `paths:` glob.
 

package/docs/operating-model.md

@@ -103,4 +103,4 @@ port-collision detail.
 
 - [Claude Code and git worktrees](../wiki/claude-worktrees.md) for the isolation and fan-out mechanics
 - [Claude Code subagents](../wiki/claude-subagents.md) for in-session parallelism without worktrees
-- `.claude/context/claude-plugin.md` for how the skills in the loop are categorized
+- `.claude/context/claude-plugin/skills.md` for how the skills in the loop are categorized

package/docs/target-projects.md

@@ -57,7 +57,7 @@ Scaffold installs tooling and seeds. It does not fill the planning docs or the d
 
 1. Fill `.claude/REQUIREMENTS.md` and `.claude/ARCHITECTURE.md`. The seed provides the files, the scope and decisions are yours to write.
 2. For a UI project, invoke `aitk:claude-design-propose` to draft `.claude/DESIGN.md` from the requirements and a `## Personality` section. Skip for non-UI projects.
-3. Optionally invoke `aitk:claude-diagram` to draft entries under `.claude/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds. A machine without a renderer still gets the diagrams and is told which check was skipped.
+3. Optionally invoke `aitk:claude-diagram` to draft entries under `.claude/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds. A machine without a renderer still gets the diagrams and is told which check was skipped. Each entry records the commit and date it was last verified against, and `aitk:claude-docs` maintains that record on every ship: it annotates an entry whose cited code path left the tree and stubs a kind whose source signal arrived uncovered. The sweep writes frontmatter only, so a diagram's picture and prose change when you redraw them and at no other time.
 4. Start the feature loop. See [AI workflow](ai-workflow.md) for the per-feature sequence.
 
 ### Stack decision
@@ -179,5 +179,5 @@ Sync also refuses a target whose working tree is dirty, so commit or stash befor
 
 - [agents](agents.md): CLI flags, exit codes, and JSON output shapes
 - [AI workflow](ai-workflow.md): feature-development loop inside a toolkit-managed project
-- [tooling](../.claude/context/tooling.md), [governance](../.claude/context/governance.md), [claude plugin](../.claude/context/claude-plugin.md), [indexes](../.claude/context/indexes.md), [snippets](../.claude/context/snippets.md), [standards](../.claude/context/standards.md): per-domain mechanics
+- [tooling](../.claude/context/tooling.md), [governance](../.claude/context/governance.md), [claude plugin](../.claude/context/claude-plugin/index.md), [indexes](../.claude/context/indexes.md), [snippets](../.claude/context/snippets.md), [standards](../.claude/context/standards.md): per-domain mechanics
 - [sandbox](../.claude/context/sandbox.md): scenario catalog for verifying domain flows

package/docs/visual-design-workflow.md

@@ -130,7 +130,7 @@ Zero or one yes: tier 0. Two or three: tier 1. Four: tier 2. Resist over-tiering
 
 - [Stitch](../wiki/stitch.md): Gemini-powered design product with the MCP server that anchors tier 1
 - [Claude Design](../wiki/claude-design.md): first-party hosted design product and handoff bundle
-- `.claude/context/claude-plugin.md`: how to decide between workflow and domain-knowledge skills
+- `.claude/context/claude-plugin/skills.md`: how to decide between workflow and domain-knowledge skills
 - [Visual wireframes](../wiki/visual-wireframes.md): Excalidraw research and setup for the tier 1 wireframe companion
 - [Community skills and plugins](../wiki/community-skills.md): catalog of frontend design skills and integrations
 - [Community MCP servers](../wiki/community-mcp-servers.md): catalog of MCPs referenced across all tiers

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

@@ -8,4 +8,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/readme.md` for structure, required and optional sections, heading hierarchy, and what to link out rather than inline. It is the single source.
+- Follow `.claude/standards/readme.md` for voice, structure, required and optional sections, heading hierarchy, badge classes, per-project-type content, and what to link out rather than inline. It is the single source.

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

@@ -0,0 +1,13 @@
+---
+description: Enforce shape, scope, and success criterion for authoring convention files
+paths:
+  - '.claude/standards/**/*.md'
+  - 'standards/**/*.md'
+---
+
+# Standard authoring standards
+
+## Authority
+
+- Follow `.claude/standards/standard.md` for a standard's frontmatter, shape, scope, and success criterion. It is the single source.
+- Read it before writing or editing a standard. Do not work the shape from memory.

package/governance/rules/core/090-code-comments.md

@@ -0,0 +1,39 @@
+---
+description: Decide when a code comment should exist and what it may claim
+paths:
+  - '**/*.ts'
+  - '**/*.tsx'
+  - '**/*.js'
+  - '**/*.jsx'
+  - '**/*.sh'
+  - '**/*.py'
+---
+
+# Code comment standards
+
+## When a comment should exist
+
+- Write a comment only when it records a fact the reader cannot recover from the code: an external contract, a rejected alternative, or the reason a surprising line is correct.
+- Do not restate in prose what the line beside it already says.
+- Do not comment a self-contained function whose signature and body already carry its behavior.
+- Let comment density follow how much of a file's behavior is decided outside that file. Treat density as an outcome, never as a target.
+- Do not add or delete a comment to move a file toward a density figure.
+
+## What a comment may claim
+
+- State only what is true of the code as written.
+- Describe a function's contract and its constraints, never its steps line by line.
+- Update or delete an invalidated comment in the same change that invalidates it.
+- Do not name a person, a ticket, or a date in place of the fact itself.
+
+## What never goes in a comment
+
+- Delete commented-out code. Do not park it beside the live path.
+- Do not record the edit that produced the code. Version control holds the change history.
+- Do not defer work into a comment. Deferred work belongs in the tracker.
+
+## Degradation vocabulary
+
+Do not write a comment carrying any of these terms.
+
+- `FIXED`, `BUGFIX`, `HACK`, `XXX`, `NOTE:`, `TODO`, `FIXME`, `don't remove`, `previously`, `used to`, `workaround`

package/governance/stacks/base.toml

@@ -1,2 +1,2 @@
 extends = ""
-rules = ["000-constitution", "010-testing", "020-concurrency", "030-error-handling", "040-performance", "050-logging", "060-naming", "070-planning", "080-config-comments", "500-prose", "510-context", "520-wireframes", "530-requirements", "540-architecture", "550-design", "555-tasks", "560-diagrams", "570-skill", "580-readme", "590-rule-authoring"]
+rules = ["000-constitution", "010-testing", "020-concurrency", "030-error-handling", "040-performance", "050-logging", "060-naming", "070-planning", "080-config-comments", "090-code-comments", "500-prose", "510-context", "520-wireframes", "530-requirements", "540-architecture", "550-design", "555-tasks", "560-diagrams", "570-skill", "580-readme", "590-rule-authoring", "591-standard-authoring"]

package/package.json

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

package/scripts/docs/list.sh

@@ -38,8 +38,33 @@ is_internal_topic() {
   esac
 }
 
+# Emits `name<TAB>description<TAB>target` per context entry, sorted so a domain
+# split into a folder lands in its alphabetical place rather than after every
+# file. Matches listTopics in src/docs/read.ts, which sorts both together.
+collect_context() {
+  local file name description
+  {
+    while IFS= read -r file; do
+      name=$(basename "$file" .md)
+      [ "$name" = "index" ] && continue
+      is_internal_topic "$name" && continue
+      description=$(read_frontmatter_field "$file" "description")
+      printf '%s\t%s\t%s\n' "$name" "$description" ".claude/context/$name.md"
+    done < <(find "$CONTEXT_DIR" -maxdepth 1 -type f -name "*.md")
+
+    # A split domain is named by its folder and described by its generated
+    # index, which carries subtitle where a sibling file carries description
+    while IFS= read -r file; do
+      name=$(basename "$(dirname "$file")")
+      is_internal_topic "$name" && continue
+      description=$(read_frontmatter_field "$file" "subtitle")
+      printf '%s\t%s\t%s\n' "$name" "$description" ".claude/context/$name/index.md"
+    done < <(find "$CONTEXT_DIR" -mindepth 2 -maxdepth 2 -type f -name "index.md")
+  } | sort
+}
+
 list_text() {
-  local file name description category
+  local file name description category target
   log_step "Docs"
   while IFS= read -r file; do
     name=$(basename "$file" .md)
@@ -53,13 +78,9 @@ list_text() {
   # Absent in a registry install, which ships docs/ without .claude/
   if [ -d "$CONTEXT_DIR" ]; then
     log_step "Domain context"
-    while IFS= read -r file; do
-      name=$(basename "$file" .md)
-      [ "$name" = "index" ] && continue
-      is_internal_topic "$name" && continue
-      description=$(read_frontmatter_field "$file" "description")
+    while IFS=$'\t' read -r name description target; do
       log_info "$name : $description"
-    done < <(find "$CONTEXT_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+    done < <(collect_context)
   fi
 }
 
@@ -76,7 +97,7 @@ emit_json_entry() {
 }
 
 list_json() {
-  local file name description category
+  local file name description category target
   JSON_FIRST=1
   printf '['
   while IFS= read -r file; do
@@ -89,13 +110,9 @@ list_json() {
   done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md" | sort)
 
   if [ -d "$CONTEXT_DIR" ]; then
-    while IFS= read -r file; do
-      name=$(basename "$file" .md)
-      [ "$name" = "index" ] && continue
-      is_internal_topic "$name" && continue
-      description=$(read_frontmatter_field "$file" "description")
-      emit_json_entry "$name" "$description" "" ".claude/context/$(basename "$file")"
-    done < <(find "$CONTEXT_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+    while IFS=$'\t' read -r name description target; do
+      emit_json_entry "$name" "$description" "" "$target"
+    done < <(collect_context)
   fi
   printf ']'
 }

package/scripts/lib/frontmatter.sh

@@ -4,7 +4,7 @@
 #
 # Kept in bash because the list commands call it once per field per file
 # inside a loop, where shelling into the CLI would cost a process per read.
-# The index engine that used to live here is TypeScript, in src/indexes/.
+# Index logic is TypeScript, in src/indexes/, and does not belong here.
 read_frontmatter_field() {
   local file="$1"
   local key="$2"

package/src/commands/sandbox.ts

@@ -86,6 +86,11 @@ async function interactivePicker(): Promise<string> {
  * file was given, so the turn ceiling reports as skipped rather than passing on a
  * fabricated zero. A file that exists but does not parse falls back to clean,
  * since decision 8 lets the envelope fail a run but never pass one.
+ *
+ * `result` carries the reply text and is left undefined on both fallbacks, which
+ * routes a reply assertion to skipped. Fabricating an empty string there would
+ * fail every reply assertion on a run that supplied no envelope, turning a gap in
+ * the input into a red arm.
  */
 function readEnvelope(path: string | undefined): RunEnvelope | undefined {
   if (path === undefined) return undefined
@@ -102,6 +107,7 @@ function readEnvelope(path: string | undefined): RunEnvelope | undefined {
       isError: parsed.is_error === true,
       turns: typeof parsed.num_turns === 'number' ? parsed.num_turns : 0,
       denials: Array.isArray(denials) ? denials.length : 0,
+      reply: typeof parsed.result === 'string' ? parsed.result : undefined,
     }
   } catch {
     return CLEAN_ENVELOPE

package/src/docs/read.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs'
-import { basename, join } from 'node:path'
+import { basename, dirname, join } from 'node:path'
 import { stripFrontmatter } from '@/frontmatter'
 
 const INDEX_TOPIC = 'index'
@@ -16,14 +16,25 @@ export interface ResolvedTopic {
   readonly rel: string
 }
 
+/**
+ * A domain too large for one file splits into `<domain>/` with a generated
+ * `index.md`, so a topic names either a sibling file or such a folder. Both
+ * spellings resolve to the same name a caller types.
+ */
 export function resolveTopic(
   root: string,
   topic: string,
 ): ResolvedTopic | undefined {
   for (const dir of ROOTS) {
-    const rel = join(dir, `${topic}.md`)
-    const path = join(root, rel)
-    if (existsSync(path)) return { path, rel }
+    const candidates = [
+      join(dir, `${topic}.md`),
+      join(dir, topic, `${INDEX_TOPIC}.md`),
+    ]
+
+    for (const rel of candidates) {
+      const path = join(root, rel)
+      if (existsSync(path)) return { path, rel }
+    }
   }
 
   return undefined
@@ -41,14 +52,21 @@ export function listTopics(root: string): string[] {
     const cwd = join(root, dir)
     if (!existsSync(cwd)) continue
 
-    const names = [
+    const files = [
       ...new Bun.Glob('*.md').scanSync({ cwd, onlyFiles: true, dot: true }),
     ]
       .map((name) => basename(name, '.md'))
       .filter((name) => name !== INDEX_TOPIC)
-      .sort()
 
-    topics.push(...names)
+    const folders = [
+      ...new Bun.Glob(`*/${INDEX_TOPIC}.md`).scanSync({
+        cwd,
+        onlyFiles: true,
+        dot: true,
+      }),
+    ].map((name) => dirname(name))
+
+    topics.push(...[...files, ...folders].sort())
   }
 
   return topics

package/src/indexes/render.ts

@@ -161,21 +161,41 @@ function renderIndex(
       }
     })
   } else {
-    for (const entry of entries) {
-      out += formatEntry(entry)
-    }
+    /**
+     * Flat mode sorts sub-catalogs among the files rather than after them. A
+     * folder and a file are both one domain to a reader scanning the catalog,
+     * so a trailing folder reads as absent from the alphabetical run it belongs
+     * in. Grouped mode keeps its own heading below, where a category is the
+     * organizing key and alphabetical position carries no meaning.
+     */
+    const lines = [
+      ...entries.map((entry) => ({
+        key: entry.name,
+        text: formatEntry(entry),
+      })),
+      ...subCatalogs.map((catalog) => ({
+        key: catalog.name,
+        text: formatSubCatalog(catalog),
+      })),
+    ].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+
+    for (const line of lines) out += line.text
   }
 
-  if (subCatalogs.length > 0) {
-    if (hasCategories) out += '\n## Sub-catalogs\n\n'
+  if (hasCategories && subCatalogs.length > 0) {
+    out += '\n## Sub-catalogs\n\n'
     for (const catalog of subCatalogs) {
-      out += `- [${catalog.title}](${catalog.name}/${INDEX_FILE}): ${catalog.subtitle}\n`
+      out += formatSubCatalog(catalog)
     }
   }
 
   return out
 }
 
+function formatSubCatalog(catalog: SubCatalog): string {
+  return `- [${catalog.title}](${catalog.name}/${INDEX_FILE}): ${catalog.subtitle}\n`
+}
+
 function formatEntry(entry: IndexEntry): string {
   return `- [${entry.title}](${entry.name}): ${entry.description}\n`
 }

package/src/sandbox/expect.ts

@@ -19,6 +19,7 @@ export interface Expectation {
   readonly absent: readonly string[]
   readonly content: readonly ContentAssertion[]
   readonly writeScope: readonly string[]
+  readonly reply: readonly string[]
   readonly manual: readonly string[]
   readonly maxTurns?: number
 }
@@ -28,10 +29,17 @@ export interface AssertionResult {
   readonly message: string
 }
 
+/**
+ * `reply` is optional because an absent reply and an empty one mean different
+ * things. A run whose envelope was never supplied has nothing to assert against
+ * and skips. A run that genuinely returned no text carries the empty string and
+ * fails every reply assertion, which is the finding.
+ */
 export interface RunEnvelope {
   readonly isError: boolean
   readonly turns: number
   readonly denials: number
+  readonly reply?: string
 }
 
 export interface Verdict {
@@ -155,6 +163,7 @@ export function parseExpectation(source: string): Expectation {
     absent: stringArray(parsed.absent),
     content: contentArray(parsed.content),
     writeScope: stringArray(parsed.write_scope),
+    reply: stringArray(parsed.reply),
     manual: stringArray(parsed.manual),
     maxTurns:
       typeof parsed.max_turns === 'number' ? parsed.max_turns : undefined,
@@ -171,7 +180,8 @@ export function countMechanicalAssertions(expectation: Expectation): number {
     expectation.paths.length +
     expectation.absent.length +
     expectation.content.length +
-    expectation.writeScope.length
+    expectation.writeScope.length +
+    expectation.reply.length
   )
 }
 
@@ -259,6 +269,42 @@ function checkWriteScope(
   }
 }
 
+/**
+ * Plain substrings, matched case-sensitively, against the text the run replied
+ * with. A substring rather than a regex because the pattern a reply assertion
+ * wants is a load-bearing token, a path or a command, and a regex invites the
+ * anchored sentence that goes red on any rewording.
+ *
+ * Declare only positives. A negative substring passes on every reply that
+ * phrases the thing differently, which is the vacuous pass
+ * `countMechanicalAssertions` excludes `manual` to prevent. An entry asserting
+ * what a run must not have said stays in `manual` with its reason.
+ */
+function checkReply(
+  expectation: Expectation,
+  envelope: RunEnvelope | undefined,
+): KindOutcome {
+  if (expectation.reply.length === 0) return { results: [], skipped: [] }
+
+  if (envelope?.reply === undefined) {
+    return {
+      results: [],
+      skipped: ['reply: no reply text supplied, pass --envelope'],
+    }
+  }
+
+  const reply = envelope.reply
+
+  return {
+    results: expectation.reply.map((fragment) =>
+      reply.includes(fragment)
+        ? { ok: true, message: `reply says: ${fragment}` }
+        : { ok: false, message: `reply never says: ${fragment}` },
+    ),
+    skipped: [],
+  }
+}
+
 /**
  * The envelope never determines a pass. It can only fail a run the expectations
  * would otherwise have passed. Under `bypassPermissions` the denial count is
@@ -306,16 +352,18 @@ export function checkExpectation(
   input: CheckInput,
 ): Verdict {
   const scope = checkWriteScope(expectation, input.writes)
+  const reply = checkReply(expectation, input.envelope)
   const envelope = checkEnvelope(expectation, input.envelope)
 
   const results = [
     ...checkPaths(expectation, input.sandboxDir),
     ...checkAbsent(expectation, input.sandboxDir),
     ...checkContent(expectation, input.sandboxDir),
+    ...reply.results,
     ...scope.results,
     ...envelope.results,
   ]
-  const skipped = [...scope.skipped, ...envelope.skipped]
+  const skipped = [...scope.skipped, ...reply.skipped, ...envelope.skipped]
 
   const failed = results.filter((result) => !result.ok).length
 

package/standards/architecture.md

@@ -17,7 +17,7 @@ Applies to `.claude/ARCHITECTURE.md`. Describes the system shape and the decisio
 
 - Per-domain structure and narrative. That belongs in `.claude/context/<domain>.md`, one file per domain.
 - Setup commands and install instructions. Those live in the README.
-- How individual functions work line by line. Those go in code comments.
+- How individual functions work line by line. The code carries its own behavior.
 - Full type definitions. They live in code. Reference the shape conceptually if needed.
 
 ## Sections

package/standards/context.md

@@ -90,6 +90,8 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Past roughly 150 lines, check two things before adding more: whether the entry still covers a single domain, and whether it has filled with content `ls` or `--help` reproduces. Fix whichever is true rather than trimming to hit a number.
 - Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
 - Split into a folder (`.claude/context/<domain>/<sub-area>.md`) when a domain has three or more sub-areas that do not fit cleanly in one file. That split is the natural ceiling.
+- Keep a split domain's `index.md` generated. The catalog body is rewritten on every regen, so the domain's own overview and layout belong in a sibling file rather than in it, and the `subtitle` is what names the file to start with.
+- Author a catalog that grows a row per shipped thing as a bullet list, never a markdown table. A table pads its columns to a shared width, so one row outgrowing its column reflows every row and turns a one-line edit into a whole-file rewrite that conflicts with any sibling branch. This is what forced the split above.
 
 ## Examples
 

package/standards/diagrams.md

@@ -24,8 +24,14 @@ An entry that fails these is non-conforming regardless of whether it satisfies e
 - `title` (required): sentence case, names what the entry answers (`System context`, `Request flow`), not what it draws.
 - `description` (required): one line on which question the entry settles and which source signal drives it.
 - `category` (required): the diagram kind, one of the five in Entry kinds. It is the grouping field `aitk indexes regen` renders headings from.
+- `verified` (required): the short commit SHA an entry was last checked against and the ISO date of that check, separated by a space (`73e9a3f8 2026-08-02`). A stub nobody has drawn yet carries the literal `TODO: never verified` instead, which is the one other accepted value.
+- `stale` (optional): one line naming what changed under the entry since that check. Absent on an entry nothing has flagged.
 
-All three feed `.claude/diagrams/index.md` when regenerated. The catalog sorts categories alphabetically rather than in narrative order, so an entry cannot rely on its position to introduce another. Each entry names its own starting point, and the catalog's subtitle routes a first-time reader to the system context entry.
+The first three feed `.claude/diagrams/index.md` when regenerated. The catalog sorts categories alphabetically rather than in narrative order, so an entry cannot rely on its position to introduce another. Each entry names its own starting point, and the catalog's subtitle routes a first-time reader to the system context entry.
+
+The marker fields reach the catalog through neither route. `aitk indexes regen` reads `title`, `description`, and `category` and ignores every other key, so a marker changes no generated file. A reader picks it up by opening the entry, which is where it sits above the diagram and where anyone deciding whether to trust the picture is already standing.
+
+Two writers share the marker and neither touches the other's field. A pass that renders an entry and reads the picture back sets `verified` and clears `stale`. The `claude-docs` sweep appends `stale` and never edits `verified`. Keeping them separate is what lets a reader tell a diagram nobody has checked since the code moved from one that was checked and found correct.
 
 ## Entry kinds
 
@@ -72,7 +78,7 @@ A second entry for one kind takes a suffixed name (`request-flow-admin.md`) and
 
 - One to three short paragraphs below each diagram. Plain English and pedagogical.
 - Lead with what the diagram shows. Follow with why this shape was chosen and what alternative was rejected, when the choice was non-obvious.
-- Reference one or two specific code paths the reader can open. Do not enumerate every file.
+- Reference one or two specific code paths the reader can open. Do not enumerate every file. Backticked paths here are also the set the `claude-docs` sweep watches, so a path cited in this section is one a later session gets told about when it leaves the tree.
 - Do not duplicate prose across entries. An entry that restates its neighbor has taken the neighbor's job.
 - The audience is mixed, so vocabulary runs as a gradient across the set. `System context` assumes no knowledge of the repository. `Deployment` may assume the reader has read the others.
 
@@ -101,5 +107,7 @@ Reference the context entry by path when a reader needs the mechanism. The diagr
 - When the system changes, update the entries whose source signal changed and leave the rest alone. Rewriting the folder wholesale reproduces the defect the per-kind split exists to end.
 - A diagram showing a defunct host or library is worse than no diagram. Audit the affected entry in the same PR.
 - `System context` has no named source signal beyond `.claude/REQUIREMENTS.md`, so nothing tells a session it went stale. Re-read it when the boundary or the set of external dependencies moves.
+- The `claude-docs` sweep watches two things and writes frontmatter only. It appends `stale` when a path an entry cites leaves the tree, and it stubs a kind when a diff adds the source signal that kind is drawn from. Diagram bodies and explanation paragraphs are off limits to it, because a change that removes a module does not carry the new correct shape of the picture.
+- That watch samples thinly. It sees the one or two paths an entry happened to cite and nothing else, so a change elsewhere leaves the entry looking current. `verified` is what covers the gap, and an entry whose date sits far behind the branch is due a read whether or not anything flagged it.
 - Mermaid blocks are inside fenced code, so the prose-standards hook ignores them. The explanation paragraphs around them are still prose. Follow `standards/prose.md`.
 - The punctuation bans still apply to node and subgraph labels, and nothing checks them there. An em dash in a label passes every gate the repository has, so read the labels before shipping the entry.

package/standards/index.md

@@ -16,6 +16,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Requirements reference](requirements.md): Shape and content rules for .claude/REQUIREMENTS.md
 - [Governance rule reference](rule.md): Rule frontmatter, body shape, and voice for .claude/rules files
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
+- [Standard reference](standard.md): Shape and content rules for authoring a standard
 - [Tasks reference](tasks.md): Folder layout, filename convention, and content rules for .claude/tasks/
 - [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, commits, and tags
 - [Wireframe reference](wireframes.md): Shape and content rules for .claude/wireframes/<surface>.md files

package/standards/readme.md

@@ -36,6 +36,23 @@ Scoped to the README at a repository root. A nested README documenting a folder,
 - Do not include detailed contribution guidelines. Reference `CONTRIBUTING.md`.
 - Do not include extensive troubleshooting guides. Use a wiki or separate documentation.
 
+### Badges
+
+A badge earns its place by carrying a fact the reader cannot get from the page they are already on. Three classes pass that test.
+
+- Package version, which reports what the registry actually published rather than what the working tree claims
+- Build or CI status, which reports whether the checks are currently passing
+- License, which passes because a README rendered on a registry page has no host sidebar stating it
+
+Stars, forks, download counts, language chips, and "made with" badges fail. The first three restate what a repository host already renders above the README, and the rest decorate.
+
+- Cap the block at four. A fifth costs more scanning than any badge repays.
+- Give each badge alt text naming what it reports rather than the service that renders it. Write `npm version`, not `shields.io`.
+- Link each badge to the page a doubting reader would check next, which is the registry listing for a version badge and the run history for a status badge. A red badge with no route to the failing run reports a problem and withholds the only thing the reader wants.
+- Pin a status badge to the branch whose health it claims to report, and confirm the workflow actually runs on that branch. A workflow triggered by pull requests alone never runs on the default branch, so an unpinned badge reports whichever branch ran last and a pinned one reports nothing at all. Fix the trigger, or drop the badge under the rule below.
+- Verify a badge by the value it renders, not by its status code. A badge service answers 200 for a query it cannot satisfy, so a blank badge and a working one look identical to a status check.
+- Zero badges is a correct answer. A private project with no registry presence and no CI has nothing that passes the test, and an empty block beats a padded one.
+
 ## Content
 
 - Open public-facing READMEs with universal problems any reader recognizes, not repo-specific artifact names. Save artifact names for feature or "What is inside" sections.
@@ -44,6 +61,10 @@ Scoped to the README at a repository root. A nested README documenting a folder,
 - For libraries/tools: include API quickstart
 - For applications/products: include usage instructions and configuration options
 - For CLI tools: include command examples with flags
+- For agent-facing repositories: name the file an agent loads first and the command that lists what the project exposes
+- For marketplace-distributed plugins: give the install command for every channel the project publishes to
+
+A project is often several of these at once. Cover every type that applies rather than picking the closest one. A repository that ships a CLI, distributes a plugin, and holds agent conventions owes its reader all three.
 
 ## Examples
 

package/{claude/skills/create-standard/references → standards}/standard.md

@@ -1,33 +1,52 @@
 ---
 title: Standard reference
 description: Shape and content rules for authoring a standard
-consumers: create-standard
 ---
 
 # Standard reference
 
+Applies to each authored standard in the folder. Skip for `index.md`, which is generated rather than authored.
+
 ## Overview
 
-A standard is a target-facing authoring convention for one document type. It installs into a project under `.claude/standards/` and is consumed by skills and developers alike. One standard governs one doc type. Split unrelated conventions into separate files.
+A standard is a target-facing authoring convention for one document type. It installs into a project under `.claude/standards/` and is consumed by skills and developers alike. This file governs itself, so every rule below applies to it.
+
+## What a working standard looks like
+
+A standard answers these questions. Each can be answered wrong, which is what makes them a test rather than a preamble.
+
+- Which single document type does this govern, and where does that document live?
+- Can an author who has seen no example produce a conforming document from this file alone?
+- Does every rule state a shape the document must have, rather than a fact about the repository that happens to store it?
+- What does a conforming document achieve, stated so a reviewer can call one non-conforming without appealing to taste?
+
+A standard failing these questions is non-conforming even when it satisfies every shape rule below.
+
+## Scope
+
+- Govern one document type per standard. Split unrelated conventions into separate files.
+- Name no path, filename, or folder outside the document type the standard governs. A standard reaches projects whose layout is their own, so a path borrowed from the authoring repository is wrong in a target and nothing reports it.
+- State the rule, never the mechanism enforcing it. Hooks, scripts, checks, and skill catalogs are facts about one repository. Name the condition the document must meet and let the enforcing surface name its own case.
+- Invent inline examples rather than citing a real file elsewhere in the project. A cited file moves or is deleted and the standard goes stale in silence.
 
 ## Frontmatter
 
-- Start the file with a frontmatter block carrying `title` and `description`.
-- `title`: names the doc type in sentence case, suffixed `reference` (`Commit reference`, `Branch reference`).
+- Start the file with a frontmatter block carrying at least `title` and `description`. A consuming surface may require more.
+- `title`: names the doc type in sentence case, suffixed `reference` (`Commit reference`, `Branch reference`)
 - `description`: one line naming what the standard covers. It becomes the index link label on install.
 
 ## Structure
 
-- Use sentence case for every heading.
+- Use sentence case for every heading
 - Flat `##` rule groups for a single-topic standard. Group `##` headers by concern for a multi-topic one.
 - When one `##` section covers more than one sub-concern, split its bullets into `###` subgroups, one subgroup per sub-concern. A flat bullet list under an `##` covers a single sub-concern. Roughly seven bullets is a signal to split, not a hard cap.
-- Order groups from the most-used rule down to the edge case.
+- Order groups from the most-used rule down to the edge case
 
 ## Rules
 
-- Write rules as imperative bullets: one rule per bullet, one concern per group.
-- State the forbidden shape rather than enumerating allowed options, so a rule survives new categories.
-- Cut any rule that resists a crisp one-line phrasing.
+- Write rules as imperative bullets: one rule per bullet, one concern per group
+- State the forbidden shape rather than enumerating allowed options, so a rule survives new categories
+- Cut any rule that resists a crisp one-line phrasing
 - Do not pad with filler prose. Every line earns its place as a usable reference entry.
 
 ## Success criterion
@@ -47,6 +66,6 @@ A standard is a target-facing authoring convention for one document type. It ins
 ## Examples
 
 - Include examples only where a rule is non-obvious. A self-evident rule needs none.
-- When shown, label them `### Correct` and `### Incorrect` with an inline `# reason` on each entry.
+- When shown, label them `### Correct` and `### Incorrect` with an inline `# reason` on each entry
 - Keep to two or three entries. Show the pattern, not a catalog.
 - Keep each entry a short one-liner or command. Do not write multi-line correct and incorrect function blocks.

package/standards/bundled/standard.md

@@ -1,52 +0,0 @@
----
-title: Standard reference
-description: Shape and content rules for authoring a standard
-consumers: create-standard
----
-
-# Standard reference
-
-## Overview
-
-A standard is a target-facing authoring convention for one document type. It installs into a project under `.claude/standards/` and is consumed by skills and developers alike. One standard governs one doc type. Split unrelated conventions into separate files.
-
-## Frontmatter
-
-- Start the file with a frontmatter block carrying `title` and `description`.
-- `title`: names the doc type in sentence case, suffixed `reference` (`Commit reference`, `Branch reference`).
-- `description`: one line naming what the standard covers. It becomes the index link label on install.
-
-## Structure
-
-- Use sentence case for every heading.
-- Flat `##` rule groups for a single-topic standard. Group `##` headers by concern for a multi-topic one.
-- When one `##` section covers more than one sub-concern, split its bullets into `###` subgroups, one subgroup per sub-concern. A flat bullet list under an `##` covers a single sub-concern. Roughly seven bullets is a signal to split, not a hard cap.
-- Order groups from the most-used rule down to the edge case.
-
-## Rules
-
-- Write rules as imperative bullets: one rule per bullet, one concern per group.
-- State the forbidden shape rather than enumerating allowed options, so a rule survives new categories.
-- Cut any rule that resists a crisp one-line phrasing.
-- Do not pad with filler prose. Every line earns its place as a usable reference entry.
-
-## Success criterion
-
-- State what a conforming artifact achieves, not only what shape it takes. A standard that specifies structure exhaustively and success nowhere cannot be argued against, only edited on taste.
-- Write the criterion as a small set of questions the artifact must answer, or a task a reader must be able to complete from it. Keep it checkable by a person in one sitting.
-- Place it near the top, above the shape rules it governs. The shape rules are the means and the criterion is the test.
-- Say that an artifact failing the criterion is non-conforming even when it satisfies every shape rule. Without that line the criterion reads as advice.
-- Add a criterion to an existing standard when that standard is next exercised, not in a sweep. A criterion written without a failure to point at is the taste-based edit this section exists to prevent, so a standard with no criterion yet is a known gap rather than a violation.
-
-## Changing a standard
-
-- Change a standard on a failure, not on a finding. A finding is that the docs say X or a paper suggests Y. A failure is a conforming artifact that satisfied every shape rule and still missed the success criterion.
-- Park findings wherever the project tracks pending work, or in the standard's own backlog section when it tracks none. They are hypotheses to test, not instructions to apply.
-- Cite the failing artifact in the change that fixes it, so the next reader can tell which rules were paid for by evidence.
-
-## Examples
-
-- Include examples only where a rule is non-obvious. A self-evident rule needs none.
-- When shown, label them `### Correct` and `### Incorrect` with an inline `# reason` on each entry.
-- Keep to two or three entries. Show the pattern, not a catalog.
-- Keep each entry a short one-liner or command. Do not write multi-line correct and incorrect function blocks.