@erclx/aitk 0.22.1 → 0.24.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.24.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-roadmap/references/roadmap.md

@@ -10,6 +10,17 @@ Applies to `.claude/ROADMAP.md`. Sequences the scope from `.claude/REQUIREMENTS.
 
 The roadmap is one scannable table. That is what keeps it distinct from `.claude/tasks/`: the roadmap is an overview read at a glance, while tasks are worked one file at a time.
 
+## Scope
+
+Governs the sequencing document at `.claude/ROADMAP.md`: the version table, its columns, and its lifecycle.
+
+Does not govern:
+
+- What the scope is, which the roadmap sequences rather than defines: `requirements.md`
+- Task files, outcomes, and board state: `tasks.md`
+- Phase-label format and semver discipline: `versioning.md`
+- Rationale for a technical choice: `architecture.md`
+
 ## What goes in
 
 - One row per version, ordered top to bottom by sequence
@@ -20,9 +31,8 @@ The roadmap is one scannable table. That is what keeps it distinct from `.claude
 
 ## What does not go in
 
-- Task breakdown, checkboxes, or per-feature file lists. Those live in `.claude/tasks/` and `.claude/plans/`.
+- Task breakdown, checkboxes, or per-feature file lists
 - Implementation detail, API names, or component references
-- Rationale for tech choices. That belongs in `.claude/ARCHITECTURE.md`.
 - Sentence-long cells. Keep each cell terse so the table stays scannable.
 
 ## Format

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/create-standard/references/snippets.md

@@ -6,6 +6,15 @@ consumers: create-standard
 
 # Snippet reference
 
+## Scope
+
+Governs a snippet file: what one is for, how it is invoked, and the structure of its body.
+
+Does not govern:
+
+- Skill folders, which carry frontmatter, references, and scripts a snippet has none of: `skill.md`
+- Voice, punctuation, and formatting in snippet prose: `prose.md`
+
 ## What a snippet is
 
 A snippet is a short, focused prompt stored as a plain markdown file. Invoke one to insert a prepared instruction into any AI chat without retyping it. Each snippet covers one purpose. If a prompt needs headers or multiple goals, use a system prompt instead.

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

@@ -1,11 +1,22 @@
 ---
 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
 
+## Scope
+
+Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
+
+Does not govern:
+
+- Commit subject format, which shares the type vocabulary: `commit.md`
+- Pull request title and body: `pr.md`
+- Whether a phase label may appear in a branch name: `versioning.md`
+- Deriving an output filename from a branch name, which is a transform the skill running it owns
+
 ## Format
 
 - Structure: `<type>/<description>` or `<type>/<ticket>-<description>`

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

@@ -6,6 +6,16 @@ consumers: git-commit, git-stage
 
 # Commit message reference
 
+## Scope
+
+Governs a git commit message: subject structure, the type and scope vocabulary, and the body.
+
+Does not govern:
+
+- Branch naming, which shares the type vocabulary: `branch.md`
+- Pull request title and body, which share the subject form: `pr.md`
+- Whether a phase label or a semver tag may appear in a subject: `versioning.md`
+
 ## Format
 
 - Structure: `<type>(<scope>): <subject>`
@@ -26,7 +36,7 @@ consumers: git-commit, git-stage
 - `ci`: CI/CD pipeline changes (GitHub Actions)
 - `revert`: revert a previous commit
 
-## Scope
+## Scope vocabulary
 
 - Single lowercase word representing a system component
 - Prefer single word

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

@@ -6,6 +6,16 @@ consumers: git-issue
 
 # Issue reference
 
+## Scope
+
+Governs a tracker issue: its title, its labels, and the sections its body carries.
+
+Does not govern:
+
+- Pull request title and body: `pr.md`
+- Whether a phase label may appear in issue text: `versioning.md`
+- Voice, punctuation, and banned words in issue prose: `prose.md`
+
 ## Title
 
 - Format: `<type>: <subject>`

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

@@ -1,11 +1,22 @@
 ---
 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
 
+## Scope
+
+Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
+
+Does not govern:
+
+- Commit subject format, which shares the type vocabulary: `commit.md`
+- Pull request title and body: `pr.md`
+- Whether a phase label may appear in a branch name: `versioning.md`
+- Deriving an output filename from a branch name, which is a transform the skill running it owns
+
 ## Format
 
 - Structure: `<type>/<description>` or `<type>/<ticket>-<description>`

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

@@ -1,11 +1,22 @@
 ---
 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
 
+## Scope
+
+Governs a pull request title and body: their format and the sections the body carries.
+
+Does not govern:
+
+- Commit subject format, which shares the title form: `commit.md`
+- Branch naming: `branch.md`
+- Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
+- Voice, punctuation, and banned words in pull request prose: `prose.md`
+
 ## Title
 
 - Format: `<type>(<scope>): <subject>`

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

@@ -1,11 +1,22 @@
 ---
 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
 
+## Scope
+
+Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
+
+Does not govern:
+
+- Commit subject format, which shares the type vocabulary: `commit.md`
+- Pull request title and body: `pr.md`
+- Whether a phase label may appear in a branch name: `versioning.md`
+- Deriving an output filename from a branch name, which is a transform the skill running it owns
+
 ## Format
 
 - Structure: `<type>/<description>` or `<type>/<ticket>-<description>`

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

@@ -1,11 +1,22 @@
 ---
 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
 
+## Scope
+
+Governs a pull request title and body: their format and the sections the body carries.
+
+Does not govern:
+
+- Commit subject format, which shares the title form: `commit.md`
+- Branch naming: `branch.md`
+- Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
+- Voice, punctuation, and banned words in pull request prose: `prose.md`
+
 ## Title
 
 - Format: `<type>(<scope>): <subject>`

package/claude/skills/git-stage/references/commit.md

@@ -6,6 +6,16 @@ consumers: git-commit, git-stage
 
 # Commit message reference
 
+## Scope
+
+Governs a git commit message: subject structure, the type and scope vocabulary, and the body.
+
+Does not govern:
+
+- Branch naming, which shares the type vocabulary: `branch.md`
+- Pull request title and body, which share the subject form: `pr.md`
+- Whether a phase label or a semver tag may appear in a subject: `versioning.md`
+
 ## Format
 
 - Structure: `<type>(<scope>): <subject>`
@@ -26,7 +36,7 @@ consumers: git-commit, git-stage
 - `ci`: CI/CD pipeline changes (GitHub Actions)
 - `revert`: revert a previous commit
 
-## Scope
+## Scope vocabulary
 
 - Single lowercase word representing a system component
 - Prefer single word

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.24.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'),
     )