@erclx/aitk 0.22.1 → 0.23.0

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

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

package/claude/skills/claude-standards-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claude-standards-audit
-description: Audits changed markdown files against applicable authoring standards (prose, skill, readme, branch, pr) and reports violations without fixing. Maps each file to its standards, greps for banned tokens, and groups findings by file. Use when asked to "audit prose", "audit standards", "check standards", "standards audit", or after editing markdown where standards compliance matters. Do NOT fix violations. Reporting only.
+description: Audits changed markdown files against applicable authoring standards (prose, skill, readme) and reports violations without fixing. Maps each file to its standards, greps for banned tokens, and groups findings by file. Use when asked to "audit prose", "audit standards", "check standards", "standards audit", or after editing markdown where standards compliance matters. Do NOT fix violations. Reporting only.
 ---
 
 # Claude standards audit
@@ -44,11 +44,11 @@ For each changed markdown file, pick the applicable standards:
 - Any markdown with prose: `.claude/standards/prose.md`
 - `SKILL.md` under `.claude/skills/` or `claude/skills/`: also `.claude/standards/skill.md`
 - `README.md` at any level: also `.claude/standards/readme.md`
-- Branch names proposed in the session: `${CLAUDE_SKILL_DIR}/references/branch.md`
-- PR titles or bodies drafted in the session: `${CLAUDE_SKILL_DIR}/references/pr.md`
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 
+Every mapping names a changed markdown file, which is the only thing Step 1 produces. Text that never lands in the tree, such as a branch name or a pull request body, is checked by the skill that publishes it rather than here.
+
 ## Step 3: read standards and audit
 
 Read each applicable standard once. For each changed file, audit against every rule:

package/claude/skills/git-branch/references/branch.md

@@ -1,7 +1,7 @@
 ---
 title: Branch reference
 description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr, claude-standards-audit
+consumers: git-branch, git-split, git-pr
 ---
 
 # Branch reference

package/claude/skills/git-pr/references/branch.md

@@ -1,7 +1,7 @@
 ---
 title: Branch reference
 description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr, claude-standards-audit
+consumers: git-branch, git-split, git-pr
 ---
 
 # Branch reference

package/claude/skills/git-pr/references/pr.md

@@ -1,7 +1,7 @@
 ---
 title: Pull request reference
 description: Pull request title and body conventions
-consumers: git-split, git-pr, claude-standards-audit
+consumers: git-split, git-pr
 ---
 
 # Pull request reference

package/claude/skills/git-split/references/branch.md

@@ -1,7 +1,7 @@
 ---
 title: Branch reference
 description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr, claude-standards-audit
+consumers: git-branch, git-split, git-pr
 ---
 
 # Branch reference

package/claude/skills/git-split/references/pr.md

@@ -1,7 +1,7 @@
 ---
 title: Pull request reference
 description: Pull request title and body conventions
-consumers: git-split, git-pr, claude-standards-audit
+consumers: git-split, git-pr
 ---
 
 # Pull request reference

package/docs/agents.md

@@ -70,7 +70,7 @@ Full help: `aitk <command> --help`.
 | `aitk sandbox reset`     | Reset sandbox to baseline                                                                      |
 | `aitk sandbox clean`     | Wipe the sandbox                                                                               |
 | `aitk sandbox check`     | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)          |
-| `aitk sandbox coverage`  | Report which scenarios declare expectations (`--json`, `--strict`)                             |
+| `aitk sandbox coverage`  | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`)                 |
 | `aitk indexes regen`     | Regenerate `index.md` files from sibling frontmatter                                           |
 | `aitk docs [topic]`      | Emit toolkit reference docs (`list`, or a topic by name)                                       |
 | `aitk design render`     | Render `.claude/DESIGN.md` tokens to HTML and CSS                                              |
@@ -228,13 +228,18 @@ Exit 0 means `pass` or `unchecked`. Exit 1 means `fail`, or a caller error: a ma
 aitk sandbox coverage --json
 ```
 
-| Flag       | Effect                                            |
-| ---------- | ------------------------------------------------- |
-| `--json`   | Emit the coverage record on stdout                |
-| `--strict` | Exit 1 while any scenario declares no expectation |
+| Flag       | Effect                                                      |
+| ---------- | ----------------------------------------------------------- |
+| `--json`   | Emit the coverage record on stdout                          |
+| `--strict` | Exit 1 while any scenario declares no expectation           |
+| `--skills` | Add a per-skill asserted, should-be-asserted, exempt census |
 
 The record carries every scenario with the arms that declare, plus `totalScenarios`, `armedScenarios`, and `armedArms`. Scenarios and arms count separately, since several arms can share one scenario and dividing one by the other overstates the rollout.
 
+`--skills` answers what the scenario count cannot, which is whether anything can fail a given skill. It adds `skills`, `totalSkills`, `asserted`, `shouldBeAsserted`, `exempt`, `staleExemptions`, and `supersededExemptions` to the record, and keeps the scenario view rather than replacing it. The two denominators disagree on purpose: an armed scenario under `infra/` or `tooling/` exercises a CLI domain and pairs with no skill at all.
+
+A skill pairs to a scenario by filename, `<category>-<command>` first and bare `<command>` second, so `claude/setup-init.sh` reaches the `setup-init` skill. `should-be-asserted` is the default and is the work queue for writing arms. `exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
+
 `scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.claude/.tmp/sandbox-runs/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit. Stdout carries the same bytes it did before the record existed.
 
 ## Docs

package/package.json

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

package/src/commands/sandbox.ts

@@ -3,6 +3,11 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import { PROJECT_ROOT, execScript } from '@/exec'
+import {
+  assertedPercent,
+  collectCensus,
+  type CensusReport,
+} from '@/sandbox/census'
 import {
   collectCoverage,
   coveragePercent,
@@ -100,6 +105,7 @@ interface CheckOptions {
 interface CoverageOptions {
   readonly json?: boolean
   readonly strict?: boolean
+  readonly skills?: boolean
 }
 
 function getCategories(): string[] {
@@ -245,20 +251,105 @@ function reportCoverage(report: CoverageReport): void {
   else logInfo(summary)
 }
 
+/**
+ * Names the skills nothing can fail, which is the work queue the arm batches
+ * consume. Exempt entries print their reason, since an exemption with no reason
+ * beside it is indistinguishable from a skill nobody has got to yet.
+ */
+function reportCensus(report: CensusReport): void {
+  const shouldBe = report.skills.filter(
+    (s) => s.verdict === 'should-be-asserted',
+  )
+  const exempt = report.skills.filter((s) => s.verdict === 'exempt')
+
+  if (shouldBe.length > 0) {
+    logStep('No arm can fail these')
+    for (const entry of shouldBe)
+      logWarn(
+        `${entry.skill} (${entry.scenarios.length === 0 ? 'no scenario' : entry.scenarios.join(', ')})`,
+      )
+  }
+
+  if (exempt.length > 0) {
+    logStep('Exempt')
+    for (const entry of exempt) logInfo(`${entry.skill}: ${entry.reason}`)
+  }
+
+  // A wrong exemption is the one way this report can overstate itself, so both
+  // kinds print as errors even on a run that is otherwise clean. They separate
+  // because the reader checks a different thing: whether the skill left the
+  // tree, or whether an arm landed and the entry outlived its reason.
+  if (report.staleExemptions.length > 0) {
+    logStep('Exemptions naming no shipped skill')
+    for (const skill of report.staleExemptions) logError(skill)
+  }
+
+  if (report.supersededExemptions.length > 0) {
+    logStep('Exemptions an arm now asserts')
+    for (const skill of report.supersededExemptions)
+      logError(`${skill}, delete the entry`)
+  }
+
+  logStep('Skills')
+  const summary =
+    `${report.asserted}/${report.totalSkills} skills asserted ` +
+    `(${assertedPercent(report)}%), ${report.shouldBeAsserted} should be, ` +
+    `${report.exempt} exempt`
+  if (report.shouldBeAsserted > 0) logWarn(summary)
+  else logInfo(summary)
+}
+
 function runCoverage(options: CoverageOptions): void {
   if (reportAbsentScenarioTree()) return
 
   intro('aitk sandbox coverage')
 
   const report = collectCoverage(PROJECT_ROOT)
+
+  // A broken `exempt.toml` reads as a caller error, not as a crash. The parser
+  // throws rather than returning a smaller set, since a dropped exemption is
+  // invisible in the counts, and the conversion belongs here for the reason
+  // `resolveVerdict` catches its own parse: a typo in a declaration should read
+  // the way a pattern that does not compile does rather than as a stack trace.
+  let census: CensusReport | undefined
+  if (options.skills === true) {
+    try {
+      census = collectCensus(PROJECT_ROOT, report)
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      reportCoverage(report)
+      logStep('Skills')
+      logError(`Cannot read the exemptions: ${reason}`)
+      outro()
+      process.exitCode = 1
+
+      return
+    }
+  }
+
+  // The scenario view stays whichever way `--skills` is set. The two count
+  // different denominators, and replacing one with the other loses the scenario
+  // rollout the strict gate is written against.
   reportCoverage(report)
-  if (options.json === true) process.stdout.write(`${JSON.stringify(report)}\n`)
+  if (census !== undefined) reportCensus(census)
+
+  if (options.json === true)
+    process.stdout.write(
+      `${JSON.stringify(census === undefined ? report : { ...report, ...census })}\n`,
+    )
 
   outro()
-  process.exitCode =
+
+  // A wrong exemption exits non-zero without `--strict`. It is a wrong claim in
+  // committed data rather than a rollout still in progress, and the whole point
+  // of the verdict is that an exemption someone can no longer check is worse
+  // than no exemption at all.
+  const wrongExemption =
+    (census?.staleExemptions.length ?? 0) > 0 ||
+    (census?.supersededExemptions.length ?? 0) > 0
+  const rolloutIncomplete =
     options.strict === true && report.armedScenarios < report.totalScenarios
-      ? 1
-      : 0
+  process.exitCode = wrongExemption || rolloutIncomplete ? 1 : 0
 }
 
 function runCheck(
@@ -361,6 +452,7 @@ export function register(program: Command): void {
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Emit the report as JSON on stdout')
     .option('--strict', 'Exit non-zero while any scenario declares nothing')
+    .option('--skills', 'Add a per-skill asserted, should-be, or exempt census')
     .addHelpText(
       'after',
       [
@@ -368,8 +460,10 @@ export function register(program: Command): void {
         'Examples:',
         '  aitk sandbox coverage',
         '  aitk sandbox coverage --json',
+        '  aitk sandbox coverage --skills',
         '',
-        'Exit codes: 0, unless --strict and a scenario declares nothing.',
+        'Exit codes: 0, unless --strict and a scenario declares nothing, or',
+        '--skills and an exemption names no shipped skill or one an arm asserts.',
         'Where the scenario tree does not ship, exits 1 without a report.',
       ].join('\n'),
     )

package/src/sandbox/census.ts

@@ -0,0 +1,228 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { collectCoverage, type CoverageReport } from '@/sandbox/coverage'
+
+/**
+ * Holds the exemption declarations, beside the scenario categories rather than
+ * inside one. `listScenarios` in `coverage.ts` walks directories only, so a file
+ * at that level joins no category and never reads as a scenario.
+ */
+const EXEMPT_FILE = 'exempt.toml'
+
+export type SkillVerdict = 'asserted' | 'should-be-asserted' | 'exempt'
+
+export interface SkillCensusEntry {
+  readonly skill: string
+  readonly verdict: SkillVerdict
+  /**
+   * Every `<category>:<command>` pairing to this skill, empty when none does.
+   * Plural because the mapping is many-to-one: two scenarios can drive one
+   * skill, and naming only the first would credit its arms to the wrong file.
+   */
+  readonly scenarios: readonly string[]
+  /**
+   * Each armed arm as `<category>:<command>/<arm>`. Qualified rather than bare,
+   * because a skill two scenarios drive can hold two arms of the same name and
+   * a bare list renders them as one label twice. Deduplicating instead would
+   * read as one arm where two assert, which understates in the one direction
+   * this report exists to keep honest.
+   */
+  readonly armed: readonly string[]
+  /** Why no arm asserts this skill. Present only on `exempt`. */
+  readonly reason?: string
+}
+
+export interface CensusReport {
+  readonly skills: readonly SkillCensusEntry[]
+  readonly totalSkills: number
+  readonly asserted: number
+  readonly shouldBeAsserted: number
+  readonly exempt: number
+  /** Exemptions naming a skill the tree does not carry. */
+  readonly staleExemptions: readonly string[]
+  /**
+   * Exemptions on a skill an arm now asserts. The claim is wrong in the one
+   * direction a verdict decays, and the entry outranks nothing, so dropping it
+   * silently leaves committed data nobody is told to delete.
+   */
+  readonly supersededExemptions: readonly string[]
+}
+
+function directories(path: string): string[] {
+  if (!existsSync(path)) return []
+
+  return readdirSync(path, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+/**
+ * Every skill the plugin ships, which is the census denominator. Reads the
+ * authoring root rather than `.claude/skills/`, since the latter holds
+ * toolkit-internal skills that reach no target and would inflate the count.
+ */
+export function listSkills(root: string): string[] {
+  return directories(join(root, 'claude', 'skills'))
+}
+
+/**
+ * Maps a scenario to the skill it drives, trying two spellings in order.
+ *
+ * `<category>-<command>` is the rule `.claude/context/sandbox.md` states, and it
+ * alone pairs 29 of 55 skills. The bare `<command>` fallback is what reaches the
+ * rest: `claude/setup-init.sh` drives the `setup-init` skill, not a
+ * `claude-setup-init` that does not exist. Stating one spelling and shipping two
+ * is what let the audit report a paired skill as unpaired.
+ *
+ * Returns undefined for a scenario driving no skill at all, which is every
+ * `infra/` and `tooling/` scenario. Those exercise a CLI domain rather than a
+ * skill and belong to the scenario count, not to this one.
+ */
+export function skillForScenario(
+  category: string,
+  command: string,
+  skills: ReadonlySet<string>,
+): string | undefined {
+  const prefixed = `${category}-${command}`
+  if (skills.has(prefixed)) return prefixed
+  if (skills.has(command)) return command
+
+  return undefined
+}
+
+/**
+ * Reads the exemption declarations, keyed by skill with a `reason` each.
+ *
+ * The reason cannot live in the arm's `manual` array, which is where `#723` put
+ * prose a checker could not assert. `resolveVerdict` fails any declaration
+ * carrying zero mechanical assertions, so an `expect.toml` holding only an
+ * exempt reason goes red at the moment it is written. An exempt skill has no
+ * assertion to pair the prose with, which is what makes it exempt, so the two
+ * cases cannot share a home.
+ *
+ * Throws on a malformed file and on a table carrying no usable `reason`, rather
+ * than reporting a smaller set. Both losses are invisible downstream: the skill
+ * reclassifies to should-be-asserted and rejoins a work queue someone already
+ * ruled it out of, with nothing naming the entry that stopped counting. This is
+ * the stray-key rule `contentArray` applies in `expect.ts` for the same reason,
+ * where the declaration is well-formed and silently lost a key it appears to
+ * carry. `runCoverage` catches both and frames them.
+ */
+export function parseExemptions(source: string): Map<string, string> {
+  const parsed = Bun.TOML.parse(source) as Record<string, unknown>
+  const exemptions = new Map<string, string>()
+
+  for (const [skill, value] of Object.entries(parsed)) {
+    if (typeof value !== 'object' || value === null) {
+      throw new Error(
+        `exemption ${skill} is not a table. Write [${skill}] with a reason below it.`,
+      )
+    }
+
+    const reason = (value as Record<string, unknown>).reason
+    if (typeof reason !== 'string' || reason === '') {
+      throw new Error(
+        `exemption ${skill} declares no reason. An exemption without one cannot be checked or overturned.`,
+      )
+    }
+
+    exemptions.set(skill, reason)
+  }
+
+  return exemptions
+}
+
+function readExemptions(root: string): Map<string, string> {
+  const path = join(root, 'scripts', 'sandbox', EXEMPT_FILE)
+  if (!existsSync(path)) return new Map()
+
+  return parseExemptions(readFileSync(path, 'utf8'))
+}
+
+/**
+ * Gives every shipped skill an asserted, should-be-asserted, or exempt verdict
+ * against declared expectations rather than against a scenario existing.
+ *
+ * A paired scenario is not an asserted skill. A scenario with no `expect.toml`
+ * provisions a state and prints a human-readable `Expect:` line, so a run over
+ * it exits zero having proved nothing. Counting pairs would report coverage the
+ * suite does not have, which is the measure this report exists to replace.
+ *
+ * An armed arm outranks an exemption. A skill listed exempt that acquired an arm
+ * is asserted in fact, and reporting the stale claim instead would hide the one
+ * direction the verdict decays in.
+ */
+export function collectCensus(
+  root: string,
+  coverage: CoverageReport = collectCoverage(root),
+): CensusReport {
+  const skills = listSkills(root)
+  const known = new Set(skills)
+  const exemptions = readExemptions(root)
+
+  const pairings = new Map<string, { scenarios: string[]; armed: string[] }>()
+  for (const scenario of coverage.scenarios) {
+    const skill = skillForScenario(scenario.category, scenario.command, known)
+    if (skill === undefined) continue
+
+    // Accumulate rather than assign. Dropping a second scenario would report a
+    // skill unarmed while an arm under the other spelling asserts it.
+    const pair = `${scenario.category}:${scenario.command}`
+    const existing = pairings.get(skill) ?? { scenarios: [], armed: [] }
+    existing.scenarios.push(pair)
+    existing.armed.push(...scenario.armed.map((arm) => `${pair}/${arm}`))
+    pairings.set(skill, existing)
+  }
+
+  const entries = skills.map((skill): SkillCensusEntry => {
+    const pairing = pairings.get(skill)
+    const scenarios = pairing?.scenarios ?? []
+    const armed = pairing?.armed ?? []
+    const reason = exemptions.get(skill)
+
+    if (armed.length > 0) {
+      return { skill, verdict: 'asserted', scenarios, armed }
+    }
+
+    if (reason !== undefined) {
+      return { skill, verdict: 'exempt', scenarios, armed, reason }
+    }
+
+    return { skill, verdict: 'should-be-asserted', scenarios, armed }
+  })
+
+  // An exemption outranked by an arm is as wrong as one naming no skill, and it
+  // is the case the armed-wins rule creates rather than one the tree arrives
+  // with. Reading `entries` rather than recomputing keeps the two in step, so a
+  // change to the precedence cannot leave the report contradicting the verdict.
+  const assertedSkills = new Set(
+    entries.filter((e) => e.verdict === 'asserted').map((e) => e.skill),
+  )
+
+  return {
+    skills: entries,
+    totalSkills: entries.length,
+    asserted: assertedSkills.size,
+    shouldBeAsserted: entries.filter((e) => e.verdict === 'should-be-asserted')
+      .length,
+    exempt: entries.filter((e) => e.verdict === 'exempt').length,
+    staleExemptions: [...exemptions.keys()]
+      .filter((skill) => !known.has(skill))
+      .sort(),
+    supersededExemptions: [...exemptions.keys()]
+      .filter((skill) => assertedSkills.has(skill))
+      .sort(),
+  }
+}
+
+/**
+ * Whole percent, floored, over skills rather than scenarios. Floored for the
+ * reason `coveragePercent` is: the number exists to look worse than a wall of
+ * green does.
+ */
+export function assertedPercent(report: CensusReport): number {
+  if (report.totalSkills === 0) return 0
+
+  return Math.floor((report.asserted / report.totalSkills) * 100)
+}

package/standards/bundled/branch.md

@@ -1,7 +1,7 @@
 ---
 title: Branch reference
 description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr, claude-standards-audit
+consumers: git-branch, git-split, git-pr
 ---
 
 # Branch reference

package/standards/bundled/pr.md

@@ -1,7 +1,7 @@
 ---
 title: Pull request reference
 description: Pull request title and body conventions
-consumers: git-split, git-pr, claude-standards-audit
+consumers: git-split, git-pr
 ---
 
 # Pull request reference

package/claude/skills/claude-standards-audit/references/branch.md

@@ -1,49 +0,0 @@
----
-title: Branch reference
-description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr, claude-standards-audit
----
-
-# Branch reference
-
-## Format
-
-- Structure: `<type>/<description>` or `<type>/<ticket>-<description>`
-- Length: 50 characters maximum
-- Casing: kebab-case only, no underscores or camelCase
-- Description: 2 words maximum, 3 only when genuinely needed for specificity
-- Capture the core change, not the commit message verbatim
-- For branches with multiple commits, use the unifying concern as the description.
-- Do not duplicate type in description (e.g., `feat/feature-login`)
-
-## Types
-
-- `feat`: new feature or capability
-- `fix`: bug fix
-- `refactor`: structural changes (not a fix or feature)
-- `docs`: documentation only (README)
-- `chore`: maintenance tasks (deps, tooling, configs)
-- `perf`: performance improvements
-- `test`: add or modify tests
-- `style`: code formatting (whitespace, semicolons)
-- `build`: build system changes (webpack, npm scripts)
-- `ci`: CI/CD pipeline changes (GitHub Actions)
-- `revert`: revert a previous commit
-
-## Examples
-
-### Correct
-
-```plaintext
-feat/jwt-expiration                    # clear feature scope
-fix/AUTH-123-connection-pool           # includes ticket ID
-refactor/remove-deprecated-endpoints   # clear refactor intent
-```
-
-### Incorrect
-
-```plaintext
-feature/auth_stuff                                        # wrong type + underscore
-feat/feature-add-login                                    # duplicates type in description
-fix/DB-456-fix-the-database-connection-pool-memory-leak   # exceeds 50 chars + verbatim message
-```

package/claude/skills/claude-standards-audit/references/pr.md

@@ -1,124 +0,0 @@
----
-title: Pull request reference
-description: Pull request title and body conventions
-consumers: git-split, git-pr, claude-standards-audit
----
-
-# Pull request reference
-
-## Title
-
-- Format: `<type>(<scope>): <subject>`
-- Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
-- Length: 72 characters maximum
-
-## Content
-
-- Use imperative mood for all content (`add`, `fix`, `refactor`)
-- Do not start with "This PR," "This commit," "Included are," or "I have"
-- Do not use buzzwords (`seamless`, `robust`, `game-changer`, `enhanced`)
-- Do not describe historical behavior or unchanged code. Describe new behavior only.
-- Do not include future promises or speculative documentation
-- Do not explain obvious changes (formatting, renaming variables)
-- Do not duplicate commit messages verbatim
-
-## Sections
-
-- `## Summary`: 1-2 sentences following `<Action Verb> <Direct Object> to <Result>`, expand for clarity if needed
-- `## Key Changes`: name actual files, functions, or modules (e.g., `AuthService.verify()` not "auth handler"). Always use bullet points, never prose.
-- `## Technical Context` (optional): 1-2 lines of architectural reasoning explaining why, not what
-- Omit Technical Context for docs, config, or trivial changes
-- Use bullet points for multiple reasons, one sentence for a single reason
-- `## Testing` (optional): specify exact commands or test cases run
-- Omit Testing for docs, config, or trivial sync changes
-- Use checkboxes, never prose. See Testing discipline for which box gets ticked.
-- `## For the reviewer` (optional): what the reviewer should confirm, one bullet per request
-- Visuals: include only when they clarify architecture, UI, or complex logic flows
-
-## Testing discipline
-
-- Run the check before writing its line. A `- [ ]` reports a check that has not run rather than one that is planned.
-- Tick the box and state the observed result. `- [x] npm test passes, 42 tests` beats `- [ ] run npm test`.
-- Quote the count or output the run reported, never a figure carried from elsewhere.
-- Leave a box unchecked only when a human is required, and name which human and why on the same line.
-- Human-only covers visual or aesthetic judgment, anything needing credentials or a live third-party service, anything needing a second machine or a fresh OS, and judgment about whether a boundary or an abstraction reads correctly. The agent runs everything else.
-- Put a request for the reviewer under `## For the reviewer`. It is a request rather than unfinished testing, so it never appears as an unchecked Testing box.
-
-## Formatting
-
-- End every bullet point with a period
-
-## Examples
-
-### Template
-
-```markdown
-## Summary
-
-<Action Verb> <Direct Object> to <Result>.
-
-## Key Changes
-
-- <Verb> <specific component/file/function> (<reason if non-obvious>)
-- <Verb> <specific component/file/function>
-
-## Technical Context
-
-- <Architectural reasoning explaining why, not what>
-
-## Testing
-
-- [x] <Command run> <observed result>
-- [x] <Edge case verified> <what was observed>
-- [ ] <Human-only check> (<which human, why>)
-
-## For the reviewer
-
-- <What the reviewer should confirm>
-```
-
-### Correct
-
-```markdown
-## Summary
-
-Update auth middleware to enforce jwt expiration checks. # imperative + direct object + result
-
-## Key Changes
-
-- Add `verifyExpiration()` to `src/auth/validators.ts`. # specific function + file path
-- Refactor `AuthService.authenticate()` to handle 401 codes. # named component + clear change
-
-## Technical Context
-
-- Migration to stateless session management for horizontal scalability. # why, not what
-
-## Testing
-
-- [x] `npm run test:auth` passes, 42 tests. # command run + observed result
-- [x] Expired token rejected with a 401 against a local server. # edge case + what happened
-- [ ] Staging smoke test (release owner, needs staging credentials). # unchecked + which human + why
-
-## For the reviewer
-
-- Confirm the 401 and 403 split reads correctly for the public API. # a request, not a test result
-```
-
-### Incorrect
-
-```markdown
-## Summary
-
-This PR updates the authentication system to be more robust. # "This PR" opener + buzzword
-
-## Key Changes
-
-- Updated auth middleware files # vague, no specific component, no period
-- The old system used to check tokens differently # describes historical behavior
-
-## Testing
-
-- Tested manually # no specific command or case
-- [ ] `npm run test:auth` # unchecked box for a check the agent can run
-- [ ] Reviewer confirms the error split reads correctly # a reviewer request, belongs under `## For the reviewer`
-```