@erclx/aitk 0.58.0 → 0.60.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.58.0",
+  "version": "0.60.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/claude/skills/claude-memory-capture/SKILL.md

@@ -9,6 +9,8 @@ Scan the current session for patterns worth persisting, send each to the surface
 
 A fact about a domain belongs in that domain's context entry, which the three-tier model already loads on demand. Writing it to memory instead puts it in a folder nothing opens. Routing is therefore the point of this skill and the memory file is the fallback.
 
+The filename and its type prefix, the frontmatter, the body shape each type carries, and the lifecycle are fixed by `.claude/standards/memory.md`, or `${CLAUDE_SKILL_DIR}/../../standards/memory.md` when the project does not have it. Read it before writing an entry and follow it rather than working the shape from memory.
+
 ## Guards
 
 - All `.claude/memory/` reads and writes resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
@@ -20,7 +22,8 @@ A fact about a domain belongs in that domain's context entry, which the three-ti
 
 Read in parallel from the project root, skipping any that do not exist:
 
-- `CLAUDE.md`: Memory section rules, including save thresholds and file format overrides
+- `.claude/standards/memory.md`: the filename, frontmatter, body shape, and lifecycle every entry follows
+- `CLAUDE.md`: the project's write location and any rule it states over the folder
 - `.claude/memory/index.md`: existing index, to avoid duplicates
 - `.claude/context/index.md`: the domain catalog Step 3 routes against
 - `.claude/standards/prose.md`: voice and banned words applied to memory file bodies
@@ -30,14 +33,9 @@ Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the pro
 
 ## Step 2: classify candidates
 
-Scan the session and group candidate patterns into four types:
-
-- **feedback**: explicit user corrections, stated preferences, or non-obvious confirmations
-- **project**: decisions, initiatives, deadlines, or motivations not derivable from git or code
-- **user**: role, expertise, responsibilities, or working preferences
-- **reference**: pointers to external systems (dashboards, trackers, channels)
+Scan the session and group candidate patterns as `feedback`, `project`, `user`, or `reference`. What each type holds and what makes one fire are the Types table in `.claude/standards/memory.md`. Read the table and classify against it rather than against a recollection of the four names.
 
-Apply the save threshold: a feedback memory only fires on explicit user correction, or on a pattern that repeated twice in the session. First-occurrence slips are noise. Project, user, and reference memories fire on first disclosure.
+Scan the whole session rather than its last exchange. A rule the user stated early and you followed since reads as settled and is exactly the one no file records.
 
 ## Step 3: route what a context entry owns
 
@@ -65,26 +63,14 @@ For each remaining candidate, grep `.claude/memory/` for an existing file on the
 
 ## Step 5: write the residue
 
-For each new memory, write to `.claude/memory/<type>-<slug>.md` with this frontmatter:
+Write each remaining candidate to `.claude/memory/<type>-<slug>.md`, following the template and the shape rules in `.claude/standards/memory.md`. Copy the shape from there rather than from this body, so one edit to the standard moves every entry.
 
-```markdown
----
-title: <one-line human title, as it should read in the index>
-description: <one-line description per .claude/standards/prose.md § Frontmatter descriptions>
-category: <Feedback|Project|User|Reference>
----
-
-<memory body>
-```
-
-`category` is the type in sentence case, which is what the index renderer groups on, while the filename keeps the lowercase `<type>-` prefix. A description opening with a backtick or a colon needs single quotes, or the frontmatter fails to parse and the index goes stale.
-
-Feedback and project bodies must be three lines: the rule or fact on one line, a `**Why:**` line naming the session signal, and a `**How to apply:**` line for when the rule fires next. Keep each line tight. No narrative.
-
-User and reference bodies are a single sentence each.
+Two of its rules are the ones a capture pass gets wrong under time pressure. State the rule rather than the incident that produced it, since the session ending is the only reader who has the narrative. Write the `title` as the rule itself, never as the filename stem.
 
 Do not edit the index. `.claude/memory/index.md` is generated from sibling frontmatter by a `PostToolUse` hook, the same way the task board's index is, so a hand-appended row is drift the next regeneration discards.
 
+Run `aitk records validate memory` when the writes are done and fix what it names. It reads the whole pen rather than this session's writes, so treat a finding on a carried entry as one to fix in place rather than as a reason to stop.
+
 ## Output
 
 Respond with one line per fact routed, written, or updated:

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

@@ -7,6 +7,8 @@ description: Reviews `.claude/memory/` and proposes per-entry actions (promote t
 
 This skill drives the full memory review lifecycle in five phases. Pick the phase from what the user said and whether a review receipt already exists at `<main-root>/.claude/review/memory-review-*.md`.
 
+What an entry looks like and why a retired one is moved rather than deleted are fixed by `.claude/standards/memory.md`, or `${CLAUDE_SKILL_DIR}/../../standards/memory.md` when the project does not have it. Read it before rewriting an entry, since a promotion rewrites the rule and a rewrite has to leave the entry conforming.
+
 | User intent                                                            | Phase     | Mutates                      |
 | ---------------------------------------------------------------------- | --------- | ---------------------------- |
 | "review memory", "promote memory", "sweep stale memories" (no receipt) | Propose   | review file only             |
@@ -68,7 +70,7 @@ For each in-scope entry (see Scope), pick one action:
 - **Hand off to governance**: the rule is coding-standards class (typescript, testing, naming, error-handling, performance, logging, concurrency, planning). Do not author the rule file inline. In the toolkit repo, point the user at `aitk-governance` and `.claude/standards/rule.md`, which own the source-of-truth rules under `governance/rules/`. In a target project, point the user at the `create-rule` skill, which scaffolds a project-local rule under `.claude/rules/`. Never edit the synced `.claude/rules/` copies of toolkit rules, because `aitk gov sync` overwrites them. Stop at handoff.
 - **Retire**: the rule is stale, already absorbed into a durable surface, too vague to phrase as a rule, or a one-time incident narrative. Apply moves the file to `.claude/.tmp/memory-archive/` rather than deleting it.
 
-Retire is an archive, not a deletion. `.claude/memory/` is gitignored with no history behind it, and a first pass over a folder this size is a bulk judgment with no undo. A plan and a task both archive rather than delete for the same reason, and this costs one `mv` against an unrecoverable wrong call. The archive is worth less than a plan's, since a promoted entry survives in its destination and a stale one is discarded on purpose, which is why it is cheap rather than free.
+Retire is an archive, not a deletion, which `.claude/standards/memory.md` states as the rule and this skill executes. The archive is worth less than a plan's, since a promoted entry survives in its destination and a stale one is discarded on purpose, which is why the move is cheap rather than free.
 
 When two or more memories collapse into one rule on the same target, propose them as a single merged edit under the matching promote category. The consolidate case is a variant of promote, not a separate action.
 

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 session record against the standard governing it, per kind (`--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,58 @@
+---
+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 four kinds are `plans`, `groundwork`, `intake`, and `memory`, each a gitignored folder under `.claude/`.
+
+```bash
+aitk records validate plans
+aitk records validate memory
+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`                                            |
+| `memory`     | A filename whose prefix names none of the four types, an entry missing `title`, `description`, or `category`, a `category` disagreeing with that prefix, a title repeating the filename, and a rule-bearing body missing a part       |
+
+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. The memory walk skips `index.md` for the same reason, since the catalog is generated from its siblings rather than authored as an entry.
+
+A memory `category` is compared against the sentence-case form of the filename prefix rather than checked field by field, so one finding covers a prefix outside the four types, a field disagreeing with the prefix, and a casing drift that would open a second group in the catalog. The body check runs on `feedback` and `project` entries alone, because a `user` or `reference` entry is a single sentence by design and has no rule to apply.
+
+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`, `.claude/standards/intake.md`, and `.claude/standards/memory.md`.

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`, `intake`, and `memory`, which are governed the same way and were unreachable for the same reason. Nothing fires it automatically, because all four 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/rules/claude/559-memory.md

@@ -0,0 +1,20 @@
+---
+description: Route .claude/memory/ edits to the memory standard for the filename, frontmatter, body shape, and lifecycle
+paths:
+  - '.claude/memory/**'
+---
+
+# Memory standards
+
+## Routing
+
+- Write no memory entry for a fact a per-domain context entry already owns. Memory keeps the residue, which in practice is feedback about how to work.
+
+## The pen
+
+- Never delete a memory entry. Retire one by moving it to an archive under its own name, since the folder is gitignored and a wrong call has no undo.
+- Never hand-edit `.claude/memory/index.md`. A hook regenerates it from sibling frontmatter.
+
+## Authority
+
+- Follow `.claude/standards/memory.md` for the filename and type prefix, the frontmatter, the body shape per type, links between entries, and the lifecycle. It is the single source.

package/package.json

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

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/records.ts

@@ -0,0 +1,161 @@
+import { $ } from 'bun'
+import type { Command } from 'commander'
+import {
+  type Finding,
+  isRecordKind,
+  RECORD_KINDS,
+  type ValidateOutcome,
+  validateRecords,
+} from '@/records/validate'
+import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
+
+/** Returned when a record carries a finding, which is the gating result. */
+const EXIT_FINDINGS = 2
+
+interface ValidateCommandOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
+/**
+ * The session-record folders are shared scratch at the main worktree root, and
+ * `git worktree list` puts that root first. Trusting the working directory would
+ * validate a linked worktree's empty folder and report it clean.
+ */
+async function mainWorktreeRoot(): Promise<string> {
+  const result = await $`git worktree list --porcelain`.quiet().nothrow()
+  if (result.exitCode !== 0) return process.cwd()
+
+  const line = result.stdout
+    .toString()
+    .split('\n')
+    .find((entry) => entry.startsWith('worktree '))
+
+  return line ? line.slice('worktree '.length).trim() : process.cwd()
+}
+
+export function register(program: Command): void {
+  const records = program
+    .command('records')
+    .description('Check the gitignored session records under .claude/')
+    .helpOption('-h, --help', 'Show this help message')
+
+  records
+    .command('validate')
+    .description('Report where a record and the standard governing it disagree')
+    .argument('<kind>', `Record folder: ${RECORD_KINDS.join(', ')}`)
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Checks:',
+        '  plans       filename, required sections, and the suggested-and-answer contract',
+        '  groundwork  README and current-state files, numbering, dating, and a half-closed track',
+        '  intake      overview file, numbering, dating, and the four bullets every item carries',
+        '  memory      filename and type prefix, frontmatter, and the body shape each type carries',
+        '',
+        'Exit codes:',
+        '  0  every check passed',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  at least one record carries a finding',
+        '',
+        'It reports and never writes. Each folder is per-machine scratch with no',
+        'history behind it, so a session fixes the record the report names.',
+        '',
+        'Examples:',
+        '  aitk records validate plans',
+        '  aitk records validate memory',
+        '  aitk records validate intake --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (kind: string, opts: ValidateCommandOptions) => {
+      process.exitCode = await runValidate(kind, opts)
+    })
+}
+
+async function runValidate(
+  kind: string,
+  opts: ValidateCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (!isRecordKind(kind)) {
+    return report(
+      {
+        ok: false,
+        reason: 'unknown-kind',
+        message: `Not a record kind: ${kind}. Expected one of: ${RECORD_KINDS.join(', ')}.`,
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+
+  return report(await validateRecords(root, kind), emitJson, root)
+}
+
+function report(
+  outcome: ValidateOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    // The framed branch below already reaches stderr through logError, so the
+    // bare write is what keeps the JSON mode from reporting the reason on
+    // stdout alone.
+    if (emitJson) {
+      process.stderr.write(`${outcome.message}\n`)
+      process.stdout.write(
+        `${JSON.stringify({
+          ok: false,
+          reason: outcome.reason,
+          message: outcome.message,
+        })}\n`,
+      )
+      return 1
+    }
+
+    intro('aitk records validate')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        kind: outcome.kind,
+        records: outcome.records,
+        findings: outcome.findings,
+      })}\n`,
+    )
+  } else {
+    intro('aitk records validate')
+    logStep(outcome.kind)
+    logInfo(`${outcome.records} record(s) read`)
+
+    logStep(outcome.findings.length === 0 ? 'Clean' : 'Findings')
+    if (outcome.findings.length === 0) {
+      logInfo('every record matches the shape its standard fixes')
+    } else {
+      for (const found of outcome.findings) logWarn(describe(found))
+    }
+    outro()
+  }
+
+  return outcome.findings.length > 0 ? EXIT_FINDINGS : 0
+}
+
+function describe(found: Finding): string {
+  const scope = found.record === found.subject ? '' : `${found.record}: `
+  return `${scope}${found.subject} ${found.message}`
+}