@erclx/aitk 0.58.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.58.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/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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.58.0",
+  "version": "0.59.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,159 @@
+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',
+        '',
+        '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 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}`
+}

package/src/records/validate.ts

@@ -0,0 +1,599 @@
+import { existsSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { parseFrontmatter, readField } from '@/indexes/frontmatter'
+
+export const RECORD_KINDS = ['plans', 'groundwork', 'intake'] as const
+
+export type RecordKind = (typeof RECORD_KINDS)[number]
+
+const FOLDER_BY_KIND: Readonly<Record<RecordKind, string>> = {
+  plans: join('.claude', 'plans'),
+  groundwork: join('.claude', 'groundwork'),
+  intake: join('.claude', 'intake'),
+}
+
+/**
+ * `unknown-kind` is raised at the argument boundary rather than by the walk, and
+ * it sits here because both reach a caller through the same `reason` field. A
+ * union covering only what the walk returns would type a record the command can
+ * emit as impossible.
+ */
+export const VALIDATE_REFUSALS = ['no-folder', 'unknown-kind'] as const
+
+export type ValidateRefusal = (typeof VALIDATE_REFUSALS)[number]
+
+export const FINDING_KINDS = [
+  'name-malformed',
+  'title-missing',
+  'section-missing',
+  'entry-unreasoned',
+  'suggestion-missing',
+  'question-unanswerable',
+  'frontmatter-incomplete',
+  'date-malformed',
+  'index-missing',
+  'state-missing',
+  'closing-partial',
+  'item-incomplete',
+] as const
+
+export type FindingKind = (typeof FINDING_KINDS)[number]
+
+export interface Finding {
+  readonly kind: FindingKind
+  /** The record the finding sits in, relative to the validated folder. */
+  readonly record: string
+  readonly subject: string
+  readonly message: string
+}
+
+export interface ValidateReport {
+  readonly ok: true
+  readonly kind: RecordKind
+  readonly records: number
+  readonly findings: readonly Finding[]
+}
+
+export interface ValidateRefused {
+  readonly ok: false
+  readonly reason: ValidateRefusal
+  readonly message: string
+}
+
+export type ValidateOutcome = ValidateReport | ValidateRefused
+
+export function recordsDir(root: string, kind: RecordKind): string {
+  return join(root, FOLDER_BY_KIND[kind])
+}
+
+export function isRecordKind(value: string): value is RecordKind {
+  return (RECORD_KINDS as readonly string[]).includes(value)
+}
+
+const NONE_IDENTIFIED = 'None identified.'
+const NUMBERED_FILE = /^\d{2}-[a-z0-9]+(-[a-z0-9]+)*\.md$/
+
+function finding(
+  kind: FindingKind,
+  record: string,
+  subject: string,
+  message: string,
+): Finding {
+  return { kind, record, subject, message }
+}
+
+async function listMarkdown(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+    .map((entry) => entry.name)
+    .sort()
+}
+
+async function listFolders(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+const PLAN_NAME = /^feature-[a-z0-9]+(-[a-z0-9]+)*\.md$/
+const PLAN_TITLE = /^#[ \t]+Feature:[ \t]+\S/
+/**
+ * An entry names a file and says something about it. Both halves are tested as
+ * facts rather than as a syntax: a backticked span anywhere, and prose left over
+ * once the spans are removed.
+ *
+ * Requiring the path to lead and the reason to follow a colon was the first
+ * shape and it reported 80 of 178 archived plans. The corpus writes
+ * `- Label: prose naming a path` as often as `- path: reason`, and both name the
+ * file and say why, so the stricter rule measured a house style rather than a
+ * defect.
+ */
+function statesReason(entry: string): boolean {
+  if (!/`[^`]+`/.test(entry)) return false
+
+  const prose = entry.replace(/`[^`]*`/g, '').replace(/^-[ \t]*/, '')
+  return /[A-Za-z0-9]/.test(prose)
+}
+const QUESTION_ITEM = /^\d+[a-z]?\.[ \t]+\S/
+
+const PLAN_SECTIONS = [
+  'Summary',
+  'Constraints',
+  'Files to touch',
+  'Risks',
+  'Questions',
+] as const
+
+type PlanSection = (typeof PLAN_SECTIONS)[number]
+
+const PLAN_REQUIRED: readonly PlanSection[] = [
+  'Summary',
+  'Files to touch',
+  'Risks',
+  'Questions',
+]
+
+const FENCE = /^(`{3,}|~{3,})/
+
+/**
+ * Drops every fenced block, so a quoted template is not read as content. A plan
+ * showing the shape it writes puts real-looking bullets and headings inside a
+ * fence, and scanning them reports the example rather than the plan.
+ *
+ * A closing fence has to match the opening character and be at least as long,
+ * which is what keeps a ```` block holding a ``` example from closing early. An
+ * unterminated fence swallows the rest of the document, which under-reports a
+ * malformed file rather than reporting its remainder as content.
+ */
+export function linesOutsideFences(text: string): string[] {
+  const kept: string[] = []
+  let fence: string | undefined
+
+  for (const line of text.split('\n')) {
+    const match = FENCE.exec(line.trim())
+
+    if (fence) {
+      const closes =
+        match && match[1][0] === fence[0] && match[1].length >= fence.length
+      if (closes) fence = undefined
+      continue
+    }
+
+    if (match) {
+      fence = match[1]
+      continue
+    }
+
+    kept.push(line)
+  }
+
+  return kept
+}
+
+/**
+ * A line standing alone as a bold label or an H2, whatever it names. A plan is
+ * free to carry a section of its own, so the split has to see one to close the
+ * section above it.
+ */
+const MARKER_LINE = /^(?:##[ \t]+(.+?)|\*\*(.+?):\*\*)[ \t]*$/
+
+/**
+ * A section opens as a bold label or as an H2 and both count. The corpus writes
+ * `Summary` as a heading and the other four as bold labels, and roughly a fifth
+ * of it swaps one for the other. Reporting the variant would fail nearly every
+ * plan present on the rule a reader is least served by, which is what teaches
+ * them to skip the output.
+ */
+export function sectionMarker(line: string): PlanSection | undefined {
+  const match = MARKER_LINE.exec(line.trim())
+  if (!match) return undefined
+
+  const name = match[1] ?? match[2]
+  return PLAN_SECTIONS.find((entry) => entry === name)
+}
+
+/** The spelling a finding names, which is the one the standard's template ships. */
+export function preferredMarker(section: PlanSection): string {
+  return section === 'Summary' ? '## Summary' : `**${section}:**`
+}
+
+export function splitPlanSections(text: string): Map<string, string[]> {
+  const sections = new Map<string, string[]>()
+  let current: string | undefined
+
+  for (const line of linesOutsideFences(text)) {
+    // Any marker-shaped line closes the section above it, and only a recognized
+    // one opens a section. A plan carrying a label of its own would otherwise
+    // collect its bullets into whichever section came before.
+    if (MARKER_LINE.test(line.trim())) {
+      current = sectionMarker(line)
+      if (current) sections.set(current, [])
+      continue
+    }
+
+    if (current) sections.get(current)?.push(line)
+  }
+
+  return sections
+}
+
+interface Question {
+  readonly label: string
+  readonly body: readonly string[]
+}
+
+export function readQuestions(lines: readonly string[]): Question[] {
+  const questions: { label: string; body: string[] }[] = []
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (QUESTION_ITEM.test(trimmed)) {
+      questions.push({ label: trimmed, body: [] })
+      continue
+    }
+
+    questions.at(-1)?.body.push(trimmed)
+  }
+
+  return questions
+}
+
+function shorten(label: string): string {
+  return label.length > 60 ? `${label.slice(0, 57)}...` : label
+}
+
+function checkQuestionContract(name: string, lines: string[]): Finding[] {
+  if (lines.some((line) => line.trim() === NONE_IDENTIFIED)) return []
+
+  const findings: Finding[] = []
+
+  for (const question of readQuestions(lines)) {
+    const subject = shorten(question.label)
+
+    if (!question.body.some((line) => line.startsWith('- Suggested:'))) {
+      findings.push(
+        finding(
+          'suggestion-missing',
+          name,
+          subject,
+          'carries no Suggested line, so it arrives at execution as a stop.',
+        ),
+      )
+    }
+
+    if (!question.body.some((line) => line.startsWith('- Answer:'))) {
+      findings.push(
+        finding(
+          'question-unanswerable',
+          name,
+          subject,
+          'carries no Answer slot, so the blank-answer default has nowhere to sit.',
+        ),
+      )
+    }
+  }
+
+  return findings
+}
+
+export function checkPlan(name: string, text: string): Finding[] {
+  const findings: Finding[] = []
+
+  if (!PLAN_NAME.test(name)) {
+    findings.push(
+      finding(
+        'name-malformed',
+        name,
+        name,
+        'is not named feature-<slug>.md with a kebab-case slug.',
+      ),
+    )
+  }
+
+  const lines = linesOutsideFences(text)
+
+  if (!lines.some((line) => PLAN_TITLE.test(line))) {
+    findings.push(
+      finding('title-missing', name, name, 'opens with no # Feature: heading.'),
+    )
+  }
+
+  const sections = splitPlanSections(text)
+
+  for (const marker of PLAN_REQUIRED) {
+    if (!sections.has(marker)) {
+      findings.push(
+        finding(
+          'section-missing',
+          name,
+          preferredMarker(marker),
+          'is required and the plan carries no such section.',
+        ),
+      )
+    }
+  }
+
+  for (const line of sections.get('Files to touch') ?? []) {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith('- ') || trimmed === `- ${NONE_IDENTIFIED}`)
+      continue
+
+    if (!statesReason(trimmed)) {
+      findings.push(
+        finding(
+          'entry-unreasoned',
+          name,
+          shorten(trimmed),
+          'names no file, or names one and says nothing about it.',
+        ),
+      )
+    }
+  }
+
+  findings.push(...checkQuestionContract(name, sections.get('Questions') ?? []))
+
+  return findings
+}
+
+const DATE_FIELD = /^date:[ \t]*'?"?(\d{4}-\d{2}-\d{2})'?"?[ \t]*$/m
+
+/**
+ * Reads the opening date off the raw block rather than the parsed fields. A YAML
+ * parser resolves an unquoted `YYYY-MM-DD` to a date value on the core schema
+ * and to a string elsewhere, and a check keyed on the parsed type would report a
+ * conforming file on one runtime and not the other.
+ */
+function hasOpeningDate(raw: string): boolean {
+  return DATE_FIELD.test(raw)
+}
+
+async function checkFolderFrontmatter(
+  dir: string,
+  slug: string,
+  files: readonly string[],
+  indexFile: string,
+): Promise<Finding[]> {
+  const perFile = await Promise.all(
+    files.map(async (file) => {
+      const found: Finding[] = []
+      const frontmatter = parseFrontmatter(
+        await readFile(join(dir, file), 'utf8'),
+      )
+
+      const missing = ['title', 'description'].filter(
+        (field) => !readField(frontmatter, field),
+      )
+
+      if (missing.length > 0) {
+        found.push(
+          finding(
+            'frontmatter-incomplete',
+            slug,
+            file,
+            `carries no ${missing.join(' and no ')}.`,
+          ),
+        )
+      }
+
+      if (file === indexFile && !hasOpeningDate(frontmatter?.raw ?? '')) {
+        found.push(
+          finding(
+            'date-malformed',
+            slug,
+            file,
+            'carries no date field as YYYY-MM-DD, so the folder states no opening day.',
+          ),
+        )
+      }
+
+      if (file !== indexFile && !NUMBERED_FILE.test(file)) {
+        found.push(
+          finding(
+            'name-malformed',
+            slug,
+            file,
+            'is not numbered NN-<name>.md, so the folder has no read order.',
+          ),
+        )
+      }
+
+      return found
+    }),
+  )
+
+  return perFile.flat()
+}
+
+const GROUNDWORK_INDEX = 'README.md'
+const GROUNDWORK_STATE = '01-current-state.md'
+const GROUNDWORK_DECISION = '06-'
+const GROUNDWORK_HANDOFF = '07-'
+
+async function checkTrack(dir: string, slug: string): Promise<Finding[]> {
+  const files = await listMarkdown(dir)
+  const findings: Finding[] = []
+
+  if (!files.includes(GROUNDWORK_INDEX)) {
+    findings.push(
+      finding(
+        'index-missing',
+        slug,
+        GROUNDWORK_INDEX,
+        'is absent, so the track carries no file map and no reason it is running.',
+      ),
+    )
+  }
+
+  if (!files.includes(GROUNDWORK_STATE)) {
+    findings.push(
+      finding(
+        'state-missing',
+        slug,
+        GROUNDWORK_STATE,
+        'is absent, so the track states no measured current state.',
+      ),
+    )
+  }
+
+  // A track closes on the decision and the handoff together. One without the
+  // other reads as closed to anyone scanning filenames and strands the half a
+  // returning session actually opens.
+  const decided = files.some((file) => file.startsWith(GROUNDWORK_DECISION))
+  const handed = files.some((file) => file.startsWith(GROUNDWORK_HANDOFF))
+
+  if (decided !== handed) {
+    findings.push(
+      finding(
+        'closing-partial',
+        slug,
+        decided ? GROUNDWORK_HANDOFF : GROUNDWORK_DECISION,
+        `is absent while ${decided ? '06' : '07'} is present, so the track is neither live nor closed.`,
+      ),
+    )
+  }
+
+  findings.push(
+    ...(await checkFolderFrontmatter(dir, slug, files, GROUNDWORK_INDEX)),
+  )
+
+  return findings
+}
+
+const INTAKE_INDEX = '00-overview.md'
+const INTAKE_HANDOFF = '99-next-session.md'
+
+const ITEM_HEADING = /^###[ \t]+\S/
+const ITEM_REQUIRED = ['Problem', 'Fix', 'Worth it', 'You'] as const
+
+function bulletLabel(line: string): string | undefined {
+  const match = /^-[ \t]+\*\*([^:*]+):\*\*/.exec(line.trim())
+  return match ? match[1].trim() : undefined
+}
+
+export function checkItems(
+  slug: string,
+  file: string,
+  text: string,
+): Finding[] {
+  const findings: Finding[] = []
+  const items: { heading: string; labels: string[] }[] = []
+
+  for (const line of linesOutsideFences(text)) {
+    if (ITEM_HEADING.test(line)) {
+      items.push({ heading: line.trim().replace(/^###[ \t]+/, ''), labels: [] })
+      continue
+    }
+
+    const label = bulletLabel(line)
+    if (label) items.at(-1)?.labels.push(label)
+  }
+
+  for (const item of items) {
+    const missing = ITEM_REQUIRED.filter(
+      (label) => !item.labels.includes(label),
+    )
+
+    if (missing.length > 0) {
+      findings.push(
+        finding(
+          'item-incomplete',
+          slug,
+          `${file}: ${shorten(item.heading)}`,
+          `states no ${missing.join(', no ')}.`,
+        ),
+      )
+    }
+
+    if (item.labels.includes('Open') && !item.labels.includes('Suggested')) {
+      findings.push(
+        finding(
+          'suggestion-missing',
+          slug,
+          `${file}: ${shorten(item.heading)}`,
+          'asks an open question and suggests nothing, so a bare answer decides it.',
+        ),
+      )
+    }
+  }
+
+  return findings
+}
+
+async function checkDump(dir: string, slug: string): Promise<Finding[]> {
+  const files = await listMarkdown(dir)
+  const findings: Finding[] = []
+
+  if (!files.includes(INTAKE_INDEX)) {
+    findings.push(
+      finding(
+        'index-missing',
+        slug,
+        INTAKE_INDEX,
+        'is absent, so the dump carries no cluster table and no verdict counts.',
+      ),
+    )
+  }
+
+  findings.push(
+    ...(await checkFolderFrontmatter(dir, slug, files, INTAKE_INDEX)),
+  )
+
+  // The two reserved files hold no items. Running the item check over the
+  // handoff would report every heading it carries as a malformed item.
+  const clusters = files.filter(
+    (file) => file !== INTAKE_INDEX && file !== INTAKE_HANDOFF,
+  )
+
+  const perCluster = await Promise.all(
+    clusters.map(async (file) =>
+      checkItems(slug, file, await readFile(join(dir, file), 'utf8')),
+    ),
+  )
+
+  return [...findings, ...perCluster.flat()]
+}
+
+function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
+  return { ok: false, reason, message }
+}
+
+/**
+ * Reports what every record in one gitignored folder claims against the shape
+ * its standard fixes. It writes nothing: the folder is per-machine scratch with
+ * no history behind it, so a repair that guessed wrong could not be undone.
+ */
+export async function validateRecords(
+  root: string,
+  kind: RecordKind,
+): Promise<ValidateOutcome> {
+  const dir = recordsDir(root, kind)
+
+  if (!existsSync(dir)) {
+    return refuse('no-folder', `No ${kind} folder at ${dir}.`)
+  }
+
+  if (kind === 'plans') {
+    const files = await listMarkdown(dir)
+    const perFile = await Promise.all(
+      files.map(async (file) =>
+        checkPlan(file, await readFile(join(dir, file), 'utf8')),
+      ),
+    )
+
+    return { ok: true, kind, records: files.length, findings: perFile.flat() }
+  }
+
+  const folders = await listFolders(dir)
+  const check = kind === 'groundwork' ? checkTrack : checkDump
+  const perFolder = await Promise.all(
+    folders.map((slug) => check(join(dir, slug), slug)),
+  )
+
+  return { ok: true, kind, records: folders.length, findings: perFolder.flat() }
+}

package/standards/groundwork.md

@@ -16,6 +16,7 @@ Governs a groundwork track under `.claude/groundwork/<slug>/`: folder layout, re
 Does not govern:
 
 - A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
+- The feature plan a closed track feeds, and the contract its answer slots keep: `plan.md`
 - The task file a closing track writes, and the origin line pointing back at the folder: `tasks.md`
 - Voice and word choice: `prose.md`
 - Headings, punctuation, and file references: `markdown.md`

package/standards/index.md

@@ -14,6 +14,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Groundwork reference](groundwork.md): Folder layout, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
 - [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, punctuation, emphasis, and file references
+- [Plan reference](plan.md): Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
 - [Prose reference](prose.md): Voice, language, and frontmatter wording for reference markdown
 - [Publish reference](publish.md): Scan run against finished text leaving through a channel no automated check covers
 - [Readme reference](readme.md): Readme voice, structure, and content conventions

package/standards/intake.md

@@ -16,6 +16,7 @@ Governs an intake folder under `.claude/intake/<slug>/`: folder layout, the rese
 Does not govern:
 
 - One question measured in depth before anyone can plan against it: `groundwork.md`
+- The feature plan a promoted item feeds, and the inverted answer contract it keeps: `plan.md`
 - The task file promoting an item onto the board, and the origin line pointing back at the folder: `tasks.md`
 - Voice and word choice: `prose.md`
 - Headings, punctuation, and file references: `markdown.md`

package/standards/plan.md

@@ -0,0 +1,145 @@
+---
+title: Plan reference
+description: Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
+---
+
+# Plan reference
+
+Applies to a feature plan at `.claude/plans/feature-<slug>.md`. One file holds one concern, written before implementation starts and read by whatever executes it, so it has to carry the scope without the conversation that produced it.
+
+The folder is gitignored and unbacked. Nothing recovers a deleted plan, which is why the archive step below is a move rather than a cleanup.
+
+## Scope
+
+Governs a feature plan under `.claude/plans/feature-<slug>.md`: the filename, the required sections, what each holds, the suggested-and-answer contract, and the lifecycle from the live folder to the archive.
+
+Does not govern:
+
+- One question measured in depth before anyone can plan against it: `groundwork.md`
+- A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
+- The task file a plan is linked from, and the origin line pointing back at it: `tasks.md`
+- The transform from a branch name to a slug: `slug.md`
+- Voice and word choice: `prose.md`
+- Headings, punctuation, and file references: `markdown.md`
+- When a plan is written at all, and whether a short one goes to a file or to the conversation, which belong to the surface driving it
+
+## What a working plan looks like
+
+A plan works when a session holding none of the conversation that produced it can execute from the file alone:
+
+- What is being built, and which files does it change?
+- Which decisions are already settled, and which are still open?
+- For each open decision, what happens when nobody answers it?
+- What is likely to go wrong, and where does the work collide with something already in flight?
+
+A plan failing these is non-conforming even when it satisfies every shape rule below.
+
+## Filename and slug
+
+- Name the file `feature-<slug>.md`, with `<slug>` two to four kebab-case words naming the concern.
+- Write one concern per file. A request spanning two independent concerns takes two plans rather than one bundling both, since a bundled plan cannot be executed by two sessions or abandoned by half.
+- Derive the slug from the concern rather than from a branch, because the plan is written before the branch exists.
+- Give the branch that executes the plan the same slug. A later surface finds the plan from the branch name and finds nothing when the two spellings differ.
+
+A plan carries no frontmatter. Its filename is the whole of its identity, so a folder of plans is read by name rather than by a generated catalog.
+
+## Sections
+
+The document opens with `# Feature: <short title>` and one paragraph stating what is being built and why now. The sections below follow in this order.
+
+| Section               | Holds                                                                     | Required      |
+| --------------------- | ------------------------------------------------------------------------- | ------------- |
+| `## Summary`          | three to five one-line bullets: the goal, the deliverables, the trade-off | Always        |
+| `**Constraints:**`    | durable rules the work must respect                                       | When supplied |
+| `**Files to touch:**` | each file with a one-line reason                                          | Always        |
+| `**Risks:**`          | conflicts, coupling, and the tricky spots                                 | Always        |
+| `**Questions:**`      | numbered open decisions, each with a suggestion and an answer slot        | Always        |
+
+- Write each marker as the table gives it. `Summary` opens the prose a reader scans, so it takes an H2, and the four that follow are labels over lists rather than sections of prose.
+- A section written in the other spelling is still that section. `## Risks` and `**Risks:**` name one thing, and a plan carrying either has stated its risks, so neither reads as an omission. Write the table's form in a new plan and leave an existing plan's spelling alone.
+- Write `None identified.` under a required section with nothing to report rather than dropping the marker. A dropped section and an unconsidered one read identically.
+- Aim `## Summary` at a person scanning the plan, not at the session executing it. The other sections carry what execution needs.
+- Give every `**Files to touch:**` entry a backticked path and something said about it. A bare path states scope and not intent, and the reason is what an executing session checks its edit against. Lead with the path or lead with a label carrying the path, whichever reads better for the entry.
+- State every count and every claim about the tree as measured during the pass that wrote the plan. A figure carried in from a summary or an earlier session is the most common way a plan ships the wrong scope.
+- Prefer a short plan over a padded one. A section filled to look thorough costs the reader the same attention as one that matters.
+
+### Constraints
+
+A constraint naming a surface to leave alone forbids two different acts, and it says which. A constraint carrying only the surface leaves the executing session to guess.
+
+- Forbid conforming that surface to whatever shape the change introduces. This is what 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 repairing 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 ships one correct call beside one broken reference.
+
+### Risks
+
+- Name the collision rather than the category. A risk a reader cannot act on is padding.
+- Where the work establishes a resource with more than one consumer, list the consumers and mark each one read or write. A policy stated over that resource has to hold for the writers and not only for the consumer that prompted it.
+
+## The suggested-and-answer contract
+
+Every question carries a `- Suggested:` line and an empty `- Answer:` slot below it.
+
+```markdown
+1. <question>
+   - Suggested: <pick>, <reason or tradeoff>
+   - Answer:
+```
+
+- A blank `- Answer:` means accept the suggestion at execution time. That default is what makes the plan decision-ready in one pass, with no separate round to collect answers.
+- Never ship a question without a suggestion. A bare question defers the judgment the plan exists to supply, and it arrives at the executing session as a stop.
+- State the pick in one line with its reason or its main tradeoff. List an alternative only where it changes the pick.
+- Write `- Suggested: needs your call, <why>` where the answer turns on preference rather than on a technical default. Fabricating a default there hides an open question behind an accepted answer.
+- Never fill an `- Answer:` slot on behalf of the person who owns it. Recording the pick as the suggestion is what the suggestion line is for.
+- Answer in place when a question is settled in conversation, so the file and the decision do not disagree.
+
+This contract inverts the one an intake folder keeps, where an empty slot means unread and acceptance is typed out. A plan is written and read in one sitting with every question already surfaced, so silence is a usable default here and is not one there. Both files state the inversion, since a contract read on only one side of a boundary is the one that gets applied to the wrong document.
+
+## Lifecycle
+
+- Write the plan before implementation starts, and treat it as the scope of the run that executes it.
+- Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
+- Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current.
+- Move the plan to `.claude/plans-archive/` when the work it describes ships. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it.
+- Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.
+
+## Anti-patterns
+
+- **The plan written before the measuring.** A subject that has to be measured before anyone can plan against it belongs in a measurement track, and every plan that skipped that step had to be superseded.
+- **The bundled plan.** Two concerns under one slug cannot be split later without rewriting both halves.
+- **The question with no suggestion.** It reads as thoroughness and lands as a blocked run.
+- **The answer filled in by the author.** A slot holding the writer's own pick destroys the only signal that anyone else agreed.
+- **The count carried in.** A figure quoted from an earlier session survives the change that invalidated it, and the scope built on it is quietly wrong.
+- **The plan deleted on ship.** The considered-and-dropped reasoning goes with it, and the next session re-proposes what this one rejected.
+
+## Template
+
+```markdown
+# Feature: <short title>
+
+<One paragraph on what is being built and why now.>
+
+## 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:**
+
+- <durable rule the work must respect>
+
+**Files to touch:**
+
+- `<path/to/file>`: <reason>
+
+**Risks:**
+
+- <conflict, coupling, or tricky spot>
+
+**Questions:**
+
+1. <question>
+   - Suggested: <pick>, <reason or tradeoff>
+   - Answer:
+```

package/standards/tasks.md

@@ -15,6 +15,7 @@ Governs the task board under `.claude/tasks/`: folder layout, filenames, frontma
 
 Does not govern:
 
+- The plan file a task cites, its sections, and its answer contract: `plan.md`
 - Phase-label format and which surfaces a label may appear on: `versioning.md`
 - Sequencing across versions and why the order is what it is: `roadmap.md`
 - Architectural reasoning that outlives a task: `architecture.md`