@erclx/aitk 0.57.0 → 0.59.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.57.0",
+  "version": "0.59.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -41,6 +41,8 @@ If the two commands differ, the session is already in a linked worktree. Continu
 
 Read `.claude/plans/feature-<slug>.md` at the main worktree root. This file is the scope for this run.
 
+Its sections and its answer contract are fixed by `.claude/standards/plan.md`, or `${CLAUDE_SKILL_DIR}/../../standards/plan.md` when the project does not have it. A blank `- Answer:` accepts the `- Suggested:` line above it, so an unanswered question is a decision this run executes rather than a reason to stop.
+
 ## Step 2: implement
 
 Implement only what the plan describes. Do not expand scope. Do not refactor neighbors. Do not touch files outside the plan's "Files to touch" list without reason.

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

@@ -234,7 +234,7 @@ The base lint-staged config runs `aitk indexes regen` on every committed `*.md`,
 
 Sweep reviews this session consumed, and sweep plans across the whole board. Resolve all paths at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
 
-**Plans.** Scan every file in `.claude/tasks/`, not only the ones this session touched. For each task file whose outcomes are now all `[x]`, check for a `Plan:` line directly under the title and parse the target. The line carries a markdown link, so read the target out of the parentheses rather than taking the rest of the line. A task still carrying the older bare-path form parses the same way once the link is absent, so accept both. Resolve the target against `.claude/tasks/` before routing on it, which lands `../plans/x.md` and `.claude/plans/x.md` on the same file. The bullets below name resolved locations, so an unresolved target falls to the last one and no plan is ever archived. Never delete a plan. `CLAUDE.md` owns why a shipped plan is archived rather than removed.
+**Plans.** Scan every file in `.claude/tasks/`, not only the ones this session touched. For each task file whose outcomes are now all `[x]`, check for a `Plan:` line directly under the title and parse the target. The line carries a markdown link, so read the target out of the parentheses rather than taking the rest of the line. A task still carrying the older bare-path form parses the same way once the link is absent, so accept both. Resolve the target against `.claude/tasks/` before routing on it, which lands `../plans/x.md` and `.claude/plans/x.md` on the same file. The bullets below name resolved locations, so an unresolved target falls to the last one and no plan is ever archived. Never delete a plan. `.claude/standards/plan.md` owns the archive destination and why a shipped plan is moved rather than removed.
 
 Board-wide scope is the one place this sweep reaches past Step 3's rule against touching task files the session did not change. A board carrying a task that closed while an earlier run missed its archive is the defect this exists to clear, and skipping those tasks would preserve it. Reaching them is safe because the archive moves the plan and points the task at the new path, so a task from unrelated work ends up with a working pointer rather than a broken one.
 

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

@@ -35,33 +35,14 @@ Measure against the tree rather than recall. Grep for each construct the plan wi
 
 ## Step 3: build the plan
 
-Construct the plan with these sections:
+The section list, what each section holds, the suggested-and-answer contract, and the lifecycle are fixed by `.claude/standards/plan.md`, or `${CLAUDE_SKILL_DIR}/../../standards/plan.md` when the project does not have it. Read it before writing the file and follow it rather than working the shape from memory.
 
-- **Summary:** three to five one-line bullets covering the goal, the main deliverables, and the key trade-off or decision. Aimed at humans scanning the plan, not agents executing it. Full mode only.
-- **Constraints:** durable rules the work must respect (patterns to reuse, surfaces not to touch, platform limits). Optional. Include when an orchestrator or prior context supplies them, omit the section otherwise. A constraint naming a surface to leave alone carries the distinction under Constraints below.
-- **Files to touch:** each file with a one-line reason
-- **Risks:** conflicts, coupling, or tricky spots. When the plan establishes a resource with more than one consumer, list the consumers and mark each read or write, because a policy stated over that resource has to hold for the writers and not just the consumer that prompted it. If none, use `None identified.`
-- **Questions:** numbered list of things to resolve before starting. Each carries a `- Suggested:` line and an `- Answer:` slot (see Suggestions below). If none, use `None identified.`
+What this skill adds on top of the standard:
 
-Prefer `None identified.` over low-signal fillers. A small feature should produce a short plan, not a padded one. Small mode skips the summary since the plan is already short enough to scan in full.
-
-### Constraints
-
-A constraint naming a surface to leave alone forbids two different acts. Name which one, since a constraint carrying only the surface leaves the executing session to guess.
-
-- Forbid conforming the surface to whatever shape the change introduces. This is the act a scope constraint means, and it keeps the branch from growing a second concern.
-- Never forbid retargeting a pointer the change breaks. A rename, a split, or a deletion that leaves a citation behind ships a dangling reference, so fixing it is required work rather than scope creep.
-- Decide both acts for every surface the constraint names. Carving the distinction out for one file and leaving its siblings under the bare wording is how a plan ships one correct call beside one broken reference.
-
-### Suggestions
-
-Attach a `- Suggested:` line to every question, then an empty `- Answer:` slot below it. A blank answer means accept the suggestion at execution time. This makes the plan decision-ready in one pass, with no separate decision-help round.
-
-- Apply senior judgment: pick the best option and state it in one line with its reason or main tradeoff. No padding, no alternatives unless they change the pick.
+- Apply senior judgment to every `- Suggested:` line. Pick the best option and state it in one line with its reason or main tradeoff. No padding, no alternatives unless they change the pick.
 - Suggest a real default when best practice, the codebase, or prior context points to one.
-- When the answer hinges on the user's preference or their intent is unclear, write `- Suggested: needs your call, <why>` rather than fabricating a technical default.
-
-When three or more questions remain, keep chat output to the file pointer plus a short summary. Inline chat is fine when two or fewer remain.
+- Prefer `None identified.` over low-signal fillers. A small feature should produce a short plan, not a padded one.
+- When three or more questions remain, keep chat output to the file pointer plus a short summary. Inline chat is fine when two or fewer remain.
 
 ## Step 4: output
 
@@ -74,7 +55,7 @@ A consumer list is a `Risks` entry, which already forces Full. Establishing a re
 
 ### Small mode
 
-Output the plan to chat. Do not write a plan file.
+Output the plan to chat. Do not write a plan file. The markers match the standard's, so a plan that later grows into a file keeps the shape it was drafted in.
 
 ```markdown
 **Files to touch:**
@@ -98,37 +79,9 @@ Omit empty sections. Do not print `None identified.` in chat.
 
 Derive a 2-to-4-word kebab-case slug from the feature description. Write the full plan to `.claude/plans/feature-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist.
 
-File format:
-
-```markdown
-# Feature: <short title>
-
-<feature description>
-
-## Summary
-
-- <one-line bullet covering the goal>
-- <one-line bullet covering the main deliverables>
-- <one-line bullet covering the key decision or trade-off>
-
-**Constraints:**
+The file follows the template in `.claude/standards/plan.md`. Copy the shape from there rather than from this body, so one edit to the standard moves every plan.
 
-- <durable rule the work must respect>
-
-**Files to touch:**
-
-- `path/to/file`: reason
-
-**Risks:**
-
-- <risk>
-
-**Questions:**
-
-1. <question>
-   - Suggested: <pick>, <reason or tradeoff>
-   - Answer:
-```
+Run `aitk records validate plans` after writing the file when the CLI is on PATH. It reports a section, a filename, or an answer slot that does not hold, and it writes nothing.
 
 Then output in chat:
 

package/docs/agents/commands.md

@@ -28,6 +28,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                          |
 | `aitk tasks archive`       | Move a shipped task off the board, clear its ordering row, and regenerate the index            |
 | `aitk tasks validate`      | Report board rows whose plan, task file, group, or file set does not hold (`--json`)           |
+| `aitk records validate`    | Report a plan, groundwork track, or intake dump against the standard governing it (`--json`)   |
 | `aitk comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git         |
 | `aitk context audit`       | Report required sections, length, depth, bullet weight, cited paths, provenance, and drift     |
 | `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                 |

package/docs/agents/index.md

@@ -18,6 +18,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
+- [Records](records.md): Validating the gitignored session records under .claude/, the per-kind checks, the refusal reasons, and why the root defaults to the main worktree
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
 - [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, and the requirement gate that is the only failing one

package/docs/agents/records.md

@@ -0,0 +1,54 @@
+---
+title: Records
+description: Validating the gitignored session records under .claude/, the per-kind checks, the refusal reasons, and why the root defaults to the main worktree
+---
+
+# Records
+
+## Validate
+
+`aitk records validate <kind>` reports where a session record and the standard governing it disagree. The three kinds are `plans`, `groundwork`, and `intake`, each a gitignored folder under `.claude/`.
+
+```bash
+aitk records validate plans
+aitk records validate intake --json
+```
+
+| Option          | Behavior                                      |
+| --------------- | --------------------------------------------- |
+| `--json`        | Add a machine-readable record on stdout       |
+| `--root <path>` | Project root, defaulting to the main worktree |
+
+It reads and never writes. Each folder is per-machine scratch with no history behind it, so a repair that guessed wrong could not be undone, and the report names the record for a session to fix.
+
+Nothing fires it automatically. The folders are gitignored, so the standards-audit hook exits early on them and any check reading changed files from git never lists one. The verb runs at the moment a session claims the record is finished, which is the same placement `aitk tasks validate` takes over the board.
+
+### What each kind checks
+
+| Kind         | What it reports                                                                                                                                                                                                                       |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plans`      | A filename that is not `feature-<slug>.md`, a missing `# Feature:` heading, a missing required section, a files-to-touch entry naming no file or saying nothing about one, and a question carrying no suggestion or no answer slot    |
+| `groundwork` | A track with no `README.md` or no `01-current-state.md`, a file missing `title` or `description`, a `README.md` with no `date` as `YYYY-MM-DD`, an unnumbered file, and a track holding a decision without its handoff or the reverse |
+| `intake`     | A dump with no `00-overview.md`, the same frontmatter and numbering checks, an item missing any of `Problem`, `Fix`, `Worth it`, or `You`, and an item carrying `Open` with no `Suggested`                                            |
+
+The half-closed track is the groundwork check a reader cannot run by eye. A folder holding `06` without `07` reads as closed to anyone scanning filenames while the file a returning session actually opens is absent.
+
+The item check skips `00-overview.md` and `99-next-session.md`, since neither holds items and running it over the handoff would report every heading it carries.
+
+A plan section opens as a bold label or as an H2 and the check counts both, naming the standard's spelling when it reports one missing. The corpus splits roughly four to one between the two forms, so failing the variant would report nearly every plan on a rule that costs a reader nothing.
+
+A section runs to the next marker-shaped line whatever it names, so a plan carrying a label of its own closes the section above it rather than collecting into it. Fenced blocks are dropped before any of this, since a plan showing the shape it writes puts real-looking bullets and headings inside a fence.
+
+### Exit codes and refusals
+
+Exit codes: `0` every check passed, `1` refused, `2` at least one record carries a finding. A `reason` field carries which gate fired: `no-folder` when the kind's directory does not exist, and `unknown-kind` when the argument names no published kind.
+
+The folders are shared scratch at the main worktree root, so `--root` defaults to the first entry of `git worktree list` rather than the working directory. A linked worktree validates the same records every other session reads.
+
+Skills branch on the findings rather than on the exit code:
+
+```bash
+aitk records validate plans --json | jq -r '.findings[] | "\(.kind): \(.subject)"'
+```
+
+For the shapes each check enforces, see `.claude/standards/plan.md`, `.claude/standards/groundwork.md`, and `.claude/standards/intake.md`.

package/docs/agents/scripting.md

@@ -11,15 +11,15 @@ What a skill or script reads to discover names at runtime, and how each domain i
 
 Use these to discover what's available instead of hardcoding names.
 
-| Command                          | Returns                                       |
-| -------------------------------- | --------------------------------------------- |
-| `aitk tooling list --json`       | Stacks, extends chain, dep and script counts  |
-| `aitk snippets list --json`      | Presets and categories with their slugs       |
-| `aitk standards list --json`     | Standards docs and the paths each governs     |
-| `aitk gov list --json`           | Governance stacks and rule sets               |
-| `aitk claude seeds list --json`  | Seed doc sources with content                 |
-| `aitk claude skills list --json` | Plugin skills, descriptions, requirement flag |
-| `aitk docs list --json`          | Consumer docs plus per-domain context         |
+| Command                          | Returns                                              |
+| -------------------------------- | ---------------------------------------------------- |
+| `aitk tooling list --json`       | Stacks, extends chain, dep and script counts         |
+| `aitk snippets list --json`      | Presets and categories with their slugs              |
+| `aitk standards list --json`     | Standards docs and the paths each governs            |
+| `aitk gov list --json`           | Governance stacks, rule sets, and unreferenced rules |
+| `aitk claude seeds list --json`  | Seed doc sources with content                        |
+| `aitk claude skills list --json` | Plugin skills, descriptions, requirement flag        |
+| `aitk docs list --json`          | Consumer docs plus per-domain context                |
 
 ### Catalog fields
 
@@ -40,6 +40,18 @@ listing and the install cannot disagree. It now reports
 `.claude/context/index.md`, which `init` has always installed and the listing
 never named, and it emits the project-level `CLAUDE.md` last rather than first.
 
+`aitk gov list` reports each stack's rules already expanded. A stack entry names
+either a rule or a whole rule folder under `governance/rules/`, and the folder
+form reaches this listing as the rules it stands for rather than as the folder
+name. A consumer deduping `--add` extras against a stack therefore reads the same
+set the install writes, whichever form the stack file uses.
+
+It also carries `unreferenced`, the rules no stack reaches, on every invocation
+rather than behind a flag. These install only through `--add`, so the key answers
+what a stack leaves out without a caller resolving every stack itself. The key is
+present alongside `stacks` and `rules` and survives `--stacks` or `--rules`
+narrowing the other two.
+
 ### The skills catalog
 
 `aitk claude skills list` reads `claude/skills/*/SKILL.md` and reports the folder

package/docs/ai-workflow.md

@@ -79,6 +79,10 @@ Before a handoff, the orchestrator checks the plan against the tree rather than
 
 `.claude/plans/`, `.claude/review/`, and `.claude/memory/` all resolve at the main worktree root, so artifacts created in any session are visible from any sibling worktree. See [Claude Code and git worktrees](../wiki/claude/claude-worktrees.md) for the full rule and the domain-level fan-out guidance.
 
+The plan's shape is fixed by `.claude/standards/plan.md`: the section list, the filename, the lifecycle, and the contract its questions keep. Every question carries a `- Suggested:` line and an empty `- Answer:` slot, and a blank answer accepts the suggestion at execution time. That default is what makes a plan decision-ready in one pass, and it is the opposite of the contract an intake folder keeps, where an empty slot means nobody reached the item.
+
+`aitk records validate plans` reports where a plan and that standard disagree: a filename that is not `feature-<slug>.md`, a missing required section, a files-to-touch entry naming no file, and a question carrying a suggestion with no answer slot. The same verb takes `groundwork` and `intake`, which are governed the same way and were unreachable for the same reason. Nothing fires it automatically, because all three folders are gitignored and every check the repository runs reads changed files from git. It reports and never writes, since the folders are per-machine scratch with no history to recover a wrong repair from.
+
 A plan that ships is archived, never deleted. `aitk:claude-docs` moves it to `.claude/plans-archive/` and retargets the task file's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. Both folders are gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
 
 The sweep reads the whole board rather than the tasks the session touched. It is the one place the skill reaches past its own rule against editing a task file the session did not change, because a task that closed while an earlier run missed its archive is exactly what the sweep exists to clear. Reaching it is safe: the archive moves the plan and retargets the pointer in the same pass, so an untouched task ends up with a working link rather than a broken one.

package/governance/rules/claude/558-plan.md

@@ -0,0 +1,22 @@
+---
+description: Route .claude/plans/ edits to the plan standard for sections, the answer contract, and the archive move
+paths:
+  - '.claude/plans/**'
+  - '.claude/plans-archive/**'
+---
+
+# Plan standards
+
+## The answer contract
+
+- Never fill an `- Answer:` slot on behalf of the person who owns it. A blank slot accepts the suggestion at execution time.
+- Never ship a question without a `- Suggested:` line. Write `- Suggested: needs your call, <why>` where the answer turns on preference.
+
+## Archiving
+
+- Move a shipped plan to `.claude/plans-archive/`. Never delete one.
+- Amend a plan in place when a decision changes. Do not append a second passage narrating the change.
+
+## Authority
+
+- Follow `.claude/standards/plan.md` for the filename and slug, the required sections, the suggested-and-answer contract, and the lifecycle. It is the single source.

package/governance/stacks/base.toml

@@ -1,2 +1,4 @@
 extends = ""
-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", "501-markdown", "510-context", "520-wireframes", "530-requirements", "540-architecture", "550-design", "555-tasks", "556-groundwork", "557-intake", "560-diagrams", "570-skill", "580-readme", "590-rule-authoring", "591-standard-authoring"]
+# Both folders whole. Every rule authored under them ships to a base consumer,
+# so adding one is a single edit rather than a file and a name here.
+rules = ["core", "claude"]

package/package.json

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

package/scripts/core/verify.sh

@@ -18,6 +18,12 @@ CHANGED_FILES=""
 # unarmed and why.
 SANDBOX_UNDECLARED_CEILING=47
 
+# Rules no stack reaches, space separated and sorted the way `aitk gov list`
+# emits them. Both are opt-in libraries a project may not want, so they are
+# recorded here rather than in a config file: the list is what a reader compares
+# a new arrival against, and a config file would absorb the arrival silently.
+GOV_EXPECTED_UNREFERENCED="260-shadcn 320-tanstack-query"
+
 check_dependencies() {
   command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
 }
@@ -208,6 +214,55 @@ main() {
   run_check "bash $PROJECT_ROOT/scripts/core/check-plugin-boundary.sh" "Plugin ships toolkit-internal content."
   log_info "Plugin boundary clean"
 
+  # A stack entry naming a rule folder takes every rule in it, which is what
+  # stops a new rule from needing a second edit to reach a target. The failure
+  # it leaves open is a rule authored into a folder no stack names, which
+  # installs for nobody and reports nothing on its own.
+  #
+  # This reports and never fails. Both standing findings are opt-in libraries
+  # this repository ships on purpose, so gating would fail every push over the
+  # deliberate case and teach a reader to route around the stage. Revisit when a
+  # third appears and the pattern is either a library set or an accident.
+  log_step "Unreferenced rules"
+  local gov_json gov_status=0 unreferenced
+  gov_json=$(cd "$PROJECT_ROOT" && bun src/cli.ts gov list --json 2>/dev/null) || gov_status=$?
+  if [ "$gov_status" -ne 0 ] || [ -z "$gov_json" ]; then
+    log_warn "Skipped, the governance catalog did not report"
+  else
+    # `bun --eval` rather than a grep, because the key holds an array of names
+    # and the numeric matches the stages above use reach a scalar alone.
+    #
+    # The `ok:` sentinel carries success rather than the exit code, because
+    # `bun --eval` reading piped stdin exits 0 even when the script throws.
+    # Measured on Bun 1.3.14: the same throw exits 1 with no pipe attached. A
+    # payload that parses as text but not as JSON would therefore print nothing
+    # and exit clean, and empty already means every rule is reached, so reading
+    # the exit code would report a broken catalog as a clean sweep. A missing
+    # or non-array key takes the same branch, since a stage that cannot measure
+    # should say so rather than claim the sweep found nothing.
+    local reported
+    reported=$(printf '%s' "$gov_json" | bun --eval '
+      try {
+        const data = JSON.parse(require("node:fs").readFileSync(0, "utf8"))
+        if (!Array.isArray(data.unreferenced)) throw new Error("no field")
+        console.log("ok:" + data.unreferenced.join(" "))
+      } catch {
+        console.log("unreadable:")
+      }
+    ')
+    unreferenced="${reported#ok:}"
+    if [ "${reported%%:*}" != "ok" ]; then
+      log_warn "Skipped, the governance catalog carried no readable unreferenced list"
+    elif [ -z "$unreferenced" ]; then
+      log_info "Every rule is reached by a stack"
+    elif [ "$unreferenced" = "$GOV_EXPECTED_UNREFERENCED" ]; then
+      log_info "Reached by no stack: $unreferenced (opt-in, install with --add)"
+    else
+      log_warn "Reached by no stack: $unreferenced"
+      log_warn "Expected: $GOV_EXPECTED_UNREFERENCED. Name the new rule in a stack, or update GOV_EXPECTED_UNREFERENCED in this script and say why it ships opt-in."
+    fi
+  fi
+
   # Only the citation half of the audit gates. Length, depth, table, and index
   # findings are judgment thresholds, and failing a push on one would make the
   # stage something to route around. `bun src/cli.ts` rather than `aitk`, since a

package/src/cli.ts

@@ -22,6 +22,7 @@ import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
 import { register as comments } from '@/commands/comments'
 import { register as context } from '@/commands/context'
+import { register as records } from '@/commands/records'
 import { PROJECT_ROOT } from '@/exec'
 
 const GREY = '\x1b[0;90m'
@@ -53,6 +54,7 @@ function showHelp(): void {
     `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
     `${GREY}│${NC}    comments [cmd]     ${GREY}# Measure comment density and trend (scan)${NC}`,
     `${GREY}│${NC}    context [cmd]      ${GREY}# Report context folder health (audit)${NC}`,
+    `${GREY}│${NC}    records [cmd]      ${GREY}# Check session records under .claude/ (validate)${NC}`,
     `${GREY}│${NC}`,
     `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
     `${GREY}│${NC}    aitk sandbox             ${GREY}# Interactive scenario picker${NC}`,
@@ -85,6 +87,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk tasks archive --pull-request 673 --json`,
     `${GREY}│${NC}    aitk comments scan src --json`,
     `${GREY}│${NC}    aitk context audit --json`,
+    `${GREY}│${NC}    aitk records validate plans`,
     `${GREY}└${NC}`,
   ]
   console.log(lines.join('\n'))
@@ -138,5 +141,6 @@ transcripts(program)
 tasks(program)
 comments(program)
 context(program)
+records(program)
 
 program.parse()

package/src/commands/gov.ts

@@ -2,11 +2,11 @@ import { existsSync } from 'node:fs'
 import { mkdir, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, resolve } from 'node:path'
 import type { Command } from 'commander'
-import { registerPassThroughVerbs } from '@/commands/pass-through'
 import { PROJECT_ROOT } from '@/exec'
 import { createGovAdapter } from '@/gov/adapter'
 import { regenConsumedRules } from '@/gov/consumed'
 import { hasStandards, installRules, lookupRules } from '@/gov/install'
+import { buildGovCatalog, describeRule, describeStack } from '@/gov/list'
 import { buildRulesPayload, listRuleFiles } from '@/gov/payload'
 import {
   govStackExists,
@@ -34,8 +34,6 @@ const NC = '\x1b[0m'
 const PAYLOAD_REL = join('.claude', '.tmp', 'gov', 'rules.md')
 const RULES_REL = join('.claude', 'rules')
 
-const PASS_THROUGH_VERBS = ['list'] as const
-
 interface InstallOptions {
   readonly add?: string
 }
@@ -44,6 +42,12 @@ interface RegenOptions {
   readonly root?: string
 }
 
+interface ListOptions {
+  readonly stacks?: boolean
+  readonly rules?: boolean
+  readonly json?: boolean
+}
+
 export function register(program: Command): void {
   const gov = program
     .command('gov')
@@ -119,7 +123,78 @@ export function register(program: Command): void {
       process.exitCode = await runRegen(opts)
     })
 
-  registerPassThroughVerbs(gov, 'gov', PASS_THROUGH_VERBS)
+  gov
+    .command('list')
+    .description('Emit the catalog of stacks and rules')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--stacks', 'Only list stacks')
+    .option('--rules', 'Only list rules')
+    .option('--json', 'Emit machine-readable JSON')
+    .action((opts: ListOptions) => {
+      process.exitCode = runList(opts)
+    })
+}
+
+/**
+ * Both selectors absent means both sections, which is the bash default. Naming
+ * both is the same as naming neither rather than an error, since the two flags
+ * read as filters and a caller passing both is asking for everything.
+ */
+function selectedSections(opts: ListOptions): {
+  stacks: boolean
+  rules: boolean
+} {
+  const stacks = opts.stacks === true
+  const rules = opts.rules === true
+  if (stacks === rules) return { stacks: true, rules: true }
+  return { stacks, rules }
+}
+
+/**
+ * `JSON.stringify` replaces a `printf` that interpolated a description into a
+ * JSON string literal through a hand-rolled escaper, so a rule carrying a
+ * character that escaper missed emitted output a consuming skill could not
+ * parse.
+ *
+ * `unreferenced` rides the same payload rather than taking a flag of its own.
+ * The verify stage and a skill asking what a stack leaves out read one call,
+ * and the key is additive, so a consumer reading `stacks` or `rules` is
+ * untouched by it.
+ */
+function runList(opts: ListOptions): number {
+  const catalog = buildGovCatalog(PROJECT_ROOT)
+  const sections = selectedSections(opts)
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ...(sections.stacks ? { stacks: catalog.stacks } : {}),
+        ...(sections.rules ? { rules: catalog.rules } : {}),
+        unreferenced: catalog.unreferenced,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk gov list')
+
+  if (sections.stacks) {
+    logStep('Stacks')
+    for (const entry of catalog.stacks) logInfo(describeStack(entry))
+  }
+
+  if (sections.rules) {
+    logStep('Rules')
+    for (const entry of catalog.rules) logInfo(describeRule(entry))
+  }
+
+  if (catalog.unreferenced.length > 0) {
+    logStep('Reached by no stack')
+    for (const rule of catalog.unreferenced) logInfo(rule)
+  }
+
+  outro()
+  return 0
 }
 
 /**