@erclx/aitk 0.28.0 → 0.30.0

package/README.md

@@ -6,7 +6,9 @@
 
 One source for your repos' AI conventions. Install once, sync everywhere.
 
-![Adding the aitk marketplace and installing the plugin in Claude Code](assets/install.png)
+![The aitk catalog, listing skills, governance rules, and standards with the count each ships and a sample of their names](assets/hero.png)
+
+If you work across more than one repository and your AI setup has started to drift between them, this is for you. The counts above are read from the catalogs when the image is built, so they're what the repo actually ships today.
 
 ## Install
 
@@ -17,6 +19,8 @@ claude plugin marketplace add https://github.com/erclx/aitk
 claude plugin install aitk@aitk
 ```
 
+![Adding the aitk marketplace and installing the plugin in Claude Code](assets/install.png)
+
 The skills land as `/aitk:<name>`. If your session was already open, run `/reload-plugins` to pick them up. Updates arrive on release, so a push to this repo won't reach your installed copy.
 
 Several skills call the `aitk` CLI to read catalogs and run installs, and the plugin doesn't put it on your path. Install it from the registry.

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

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

package/docs/agents.md

@@ -80,7 +80,7 @@ Full help: `aitk <command> --help`.
 | `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 comments scan`     | Measure comment density by language and comment kind, with a trend recomputed from git         |
-| `aitk context audit`     | Report entry length, depth, cited-path resolution, and index drift in the context folders      |
+| `aitk context audit`     | Report entry length, depth, cited-path resolution, provenance, and index drift                 |
 | `aitk capture [source]`  | Render HTML capture sources to PNG, toolkit-only and absent from an installed package          |
 
 ### Domain commands
@@ -93,7 +93,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `snippets`  | `list`, `install`, `sync`, `create`                                    |
 | `standards` | `list`, `install`, `sync`                                              |
 | `gov`       | `list`, `install`, `sync`, `build`                                     |
-| `claude`    | `init`, `sync`, `seeds list`, `setup [dest]`                           |
+| `claude`    | `init`, `sync`, `seeds list`, `skills list`, `setup [dest]`            |
 | `wiki`      | `init`                                                                 |
 | `design`    | `render`                                                               |
 | `slides`    | `render`, `list`                                                       |
@@ -327,6 +327,8 @@ aitk capture assets/install.html
 aitk capture assets --out .claude/review/captures
 ```
 
+`assets/` now holds two sources, so a bare `aitk capture` rebuilds both. `install.html` is hand-authored and its text came from a real run. `hero.html` is generated by `scripts/core/regen-hero.sh` from the CLI catalogs and must not be edited by hand, since `bun run check` regenerates it and fails on the difference. Only the HTML is asserted for drift. The PNG is a chromium render whose bytes move with the browser version, so rebuild it with `aitk capture assets/hero.html` when the check reports the HTML changed.
+
 | Option             | Behavior                                          |
 | ------------------ | ------------------------------------------------- |
 | `--out <dir>`      | Write every PNG here instead of beside its source |
@@ -385,7 +387,7 @@ aitk context audit --folder context,diagrams
 
 Scope defaults to `context`, `diagrams`, and `wireframes`, and a folder the project does not carry is skipped rather than reported. A domain that outgrew one file and split into `<domain>/` is audited as its own folder, so a split entry measures at the same grain as a flat one.
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for an unresolved citation. Only the citation check sets a failing code. Length, depth, table, and index findings print and return `0`, because each is a judgment threshold and failing a push on one would make the check something to route around.
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for an unresolved citation. Only the citation check sets a failing code. Length, depth, table, provenance, and index findings print and return `0`, because each is a judgment and failing a push on one would make the check something to route around.
 
 ### What each check reports
 
@@ -393,6 +395,8 @@ Length and depth quote their checkpoints from `.claude/standards/context.md`: ro
 
 The table check reports a catalog that grows a row per shipped thing, not a table count. A fixed comparison table never reflows, so its size costs nothing. A table qualifies at six or more body rows whose first column mostly carries a path, command, or link, which is what separates a catalog from a comparison without reading the prose.
 
+The provenance check reports the markers narrating how a domain reached its shape rather than describing what it is: a date, a change number, or a release label. The standard admits a rejected alternative and the reasoning that killed it while refusing the provenance attached to it, so a marker names a line to read rather than a line to delete. Findings group by entry and sort left to right within a line, since what a reader acts on is which file to open. Fenced blocks are excluded, which keeps a pinned version in an install command from reading as a claim the entry makes. Frontmatter is excluded with them, since every check reads the body alone, and that is what keeps a diagram entry's dated `verified` stamp a record of its last check rather than a marker to settle.
+
 Index drift compares an index against its siblings in both directions. An entry the index does not link is invisible to a session choosing what to open, and a linked name resolving to nothing sends one to a path that opens nothing.
 
 ### The citation gate
@@ -407,14 +411,15 @@ What remains is a sentence naming a hypothetical entry to show the shape of a na
 
 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 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 and rule sets              |
+| `aitk claude seeds list --json`  | Seed doc sources with content                |
+| `aitk claude skills list --json` | Plugin skills with their descriptions        |
+| `aitk docs list --json`          | Consumer docs plus per-domain context        |
 
 Every catalog serializes through `JSON.stringify`, so a name carrying a quote
 emits valid JSON. `aitk tooling list` and `aitk snippets list` previously built
@@ -433,6 +438,14 @@ 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 claude skills list` reads `claude/skills/*/SKILL.md` and reports the folder
+name with the frontmatter description, sorted by name. Internal skills under
+`.claude/skills/` are excluded, since they never install into a target and a
+count spanning both overstates what ships. A skill whose frontmatter is missing
+or unparseable returns an empty description rather than failing the listing, so
+one malformed file cannot hide the rest of the catalog. `--names` emits skill
+names one per line.
+
 ## Non-interactive examples
 
 ```bash

package/package.json

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

package/scripts/core/regen-hero.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# Fills assets/hero.html.tmpl from the CLI catalogs and writes assets/hero.html.
+#
+# Only the HTML regenerates here. The PNG beside it is a chromium render whose
+# bytes move with the browser version, so asserting it in verify.sh would fail
+# on a machine whose chromium differs rather than on a stale count. Rebuild the
+# image with `aitk capture assets/hero.html` after this script reports a change.
+# The frame carries no version. `package.json` is bumped on main by the release
+# tooling, so embedding it drifts every open branch on the next release and the
+# stage then fails for work that touched nothing.
+#
+# Clone-only. `src/capture` is excluded from the published tarball, and this
+# script reads the repository's own catalogs, so a registry install has neither.
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+TEMPLATE="$PROJECT_ROOT/assets/hero.html.tmpl"
+OUTPUT="$PROJECT_ROOT/assets/hero.html"
+LISTED=10
+
+# `bun src/cli.ts` rather than `aitk`, since a globally linked binary resolves to
+# the main checkout no matter which worktree is running.
+catalog() {
+  (cd "$PROJECT_ROOT" && AITK_NON_INTERACTIVE=1 bun src/cli.ts "$@" --json 2>/dev/null)
+}
+
+if [ ! -f "$TEMPLATE" ]; then
+  echo "regen-hero: missing template at $TEMPLATE" >&2
+  exit 1
+fi
+
+SKILLS_JSON="$(catalog claude skills list)"
+GOV_JSON="$(catalog gov list)"
+STANDARDS_JSON="$(catalog standards list)"
+SNIPPETS_JSON="$(catalog snippets list)"
+TOOLING_JSON="$(catalog tooling list)"
+
+for payload in "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$TOOLING_JSON"; do
+  if [ -z "$payload" ]; then
+    echo "regen-hero: a catalog returned nothing, refusing to write a zeroed hero" >&2
+    exit 1
+  fi
+done
+
+export SKILLS_JSON GOV_JSON STANDARDS_JSON SNIPPETS_JSON TOOLING_JSON
+export TEMPLATE OUTPUT LISTED PROJECT_ROOT
+
+bun --eval '
+const {
+  SKILLS_JSON, GOV_JSON, STANDARDS_JSON, SNIPPETS_JSON, TOOLING_JSON,
+  TEMPLATE, OUTPUT, LISTED, PROJECT_ROOT,
+} = process.env
+
+const listed = Number(LISTED)
+const skills = JSON.parse(SKILLS_JSON).skills.map((entry) => entry.name)
+const gov = JSON.parse(GOV_JSON)
+// Rule names carry a numeric prefix that orders the load, not the identity a
+// reader knows them by, so the frame shows the slug alone.
+const rules = gov.rules.map((entry) => entry.name.replace(/^\d+-/, ""))
+const standards = JSON.parse(STANDARDS_JSON).standards.map((entry) => entry.name)
+const snippets = new Set(
+  JSON.parse(SNIPPETS_JSON).categories.flatMap((category) => category.entries),
+)
+const toolingStacks = JSON.parse(TOOLING_JSON).stacks
+
+const escape = (value) =>
+  value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+
+// Even spacing across the sorted catalog rather than its first N. The skill
+// names are prefixed by domain, so an alphabetical head returns eight
+// `claude-*` entries and reads as a narrower catalog than the one that ships.
+const sample = (names) => {
+  if (names.length <= listed) return names
+  const step = names.length / listed
+  return Array.from({ length: listed }, (_, i) => names[Math.floor(i * step)])
+}
+
+const entries = (names) =>
+  sample(names)
+    .map((name) => `            <div class="entry">${escape(name)}</div>`)
+    .join("\n")
+
+const remaining = (names) => String(Math.max(0, names.length - listed))
+
+// An empty array is well-formed JSON, so the shell guard on an empty payload
+// does not catch a catalog whose tree went missing. A zeroed count would ship a
+// frame claiming the domain has nothing in it.
+for (const [label, list] of [
+  ["skills", skills], ["rules", rules], ["standards", standards],
+  ["snippets", [...snippets]], ["tooling stacks", toolingStacks], ["gov stacks", gov.stacks],
+]) {
+  if (list.length === 0) {
+    console.error(`regen-hero: the ${label} catalog is empty, refusing to write a zeroed hero`)
+    process.exit(1)
+  }
+}
+
+const values = {
+  SKILL_COUNT: String(skills.length),
+  RULE_COUNT: String(rules.length),
+  STANDARD_COUNT: String(standards.length),
+  SNIPPET_COUNT: String(snippets.size),
+  GOV_STACK_COUNT: String(gov.stacks.length),
+  TOOLING_STACK_COUNT: String(toolingStacks.length),
+  SKILL_ENTRIES: entries(skills),
+  RULE_ENTRIES: entries(rules),
+  STANDARD_ENTRIES: entries(standards),
+  SKILL_MORE: remaining(skills),
+  RULE_MORE: remaining(rules),
+  STANDARD_MORE: remaining(standards),
+}
+
+let html = await Bun.file(TEMPLATE).text()
+for (const [key, value] of Object.entries(values)) {
+  html = html.replaceAll(`{{${key}}}`, value)
+}
+
+const unresolved = html.match(/{{[A-Z_]+}}/g)
+if (unresolved) {
+  console.error(`regen-hero: unresolved placeholders ${[...new Set(unresolved)].join(", ")}`)
+  process.exit(1)
+}
+
+await Bun.write(OUTPUT, html)
+'

package/scripts/core/verify.sh

@@ -99,6 +99,23 @@ collect_plugin_manifests() {
   } | sort -u
 }
 
+# The drift assert covers the HTML because the PNG is a chromium render whose
+# bytes move with the browser. That leaves the artifact a visitor actually sees
+# asserted nowhere, so a branch that regenerates the HTML and never runs the
+# capture passes every stage while shipping an image with the old counts.
+#
+# The two files move together or the image is stale, so their last-touching
+# commit is the same commit. Comparing the branch's file list instead would pass
+# any branch that touched both anywhere, including one that regenerated the HTML
+# alone in a later commit. Both absent resolves to two empty strings and passes,
+# which is correct for a tree that carries neither.
+assert_hero_pair() {
+  local html_commit png_commit
+  html_commit=$(git -C "$PROJECT_ROOT" log -1 --format=%H -- assets/hero.html)
+  png_commit=$(git -C "$PROJECT_ROOT" log -1 --format=%H -- assets/hero.png)
+  [ "$html_commit" = "$png_commit" ]
+}
+
 assert_no_drift() {
   local paths=$1
   local err_msg=$2
@@ -135,6 +152,15 @@ main() {
   assert_no_drift ".claude/standards .claude/snippets .claude/internal .claude/rules" "Consumed copies drifted. Run bun run check and commit .claude/standards, .claude/snippets, .claude/internal, and .claude/rules."
   log_info "Consumed copies clean"
 
+  # Only the HTML is asserted. The PNG beside it is a chromium render whose bytes
+  # move with the browser version, so a drift check over it would fail on a
+  # machine whose chromium differs rather than on a stale count.
+  log_step "Hero"
+  run_check "bash $PROJECT_ROOT/scripts/core/regen-hero.sh" "Hero regen failed"
+  assert_no_drift "assets/hero.html" "Hero counts drifted. Run bun run check, then aitk capture assets/hero.html, and commit assets/hero.html with assets/hero.png."
+  run_check "assert_hero_pair" "Hero HTML and image last moved in different commits, so the image may be stale. Run aitk capture assets/hero.html and commit both files together."
+  log_info "Hero clean"
+
   log_step "Skill references"
   run_check "bash $PROJECT_ROOT/scripts/core/regen-skill-references.sh" "Skill-reference regen failed"
   assert_no_drift "claude/skills/*/references" "Skill references drifted. Run bun run check and commit the updated reference files."

package/src/claude/skills-list.ts

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---/
+
+export interface SkillListing {
+  readonly name: string
+  readonly description: string
+}
+
+/**
+ * Enumerates the plugin skill catalog, which is the corpus under `claude/`
+ * rather than the internal skills under `.claude/`. Only the former installs
+ * into a target, so a count taken across both overstates what ships.
+ *
+ * The folder name wins over the frontmatter `name` when they disagree, because
+ * Claude Code invokes a skill by its directory.
+ */
+export function listSkills(root: string): SkillListing[] {
+  const skillsRoot = join(root, 'claude', 'skills')
+  if (!existsSync(skillsRoot)) return []
+
+  const paths = [
+    ...new Bun.Glob('*/SKILL.md').scanSync({
+      cwd: skillsRoot,
+      onlyFiles: true,
+    }),
+  ].sort()
+
+  return paths.map((path) => ({
+    name: dirname(path),
+    description: readDescription(join(skillsRoot, path)),
+  }))
+}
+
+/**
+ * Returns an empty description rather than throwing on a skill whose
+ * frontmatter is missing or unparseable, so one malformed file does not hide
+ * the rest of the catalog from a caller counting it.
+ */
+function readDescription(path: string): string {
+  const match = FRONTMATTER.exec(readFileSync(path, 'utf8'))
+  if (!match) return ''
+
+  try {
+    const parsed = Bun.YAML.parse(match[1])
+    if (typeof parsed !== 'object' || parsed === null) return ''
+    const { description } = parsed as Record<string, unknown>
+    return typeof description === 'string' ? description : ''
+  } catch {
+    return ''
+  }
+}

package/src/commands/claude.ts

@@ -12,6 +12,7 @@ import {
   type Seed,
 } from '@/claude/seeds'
 import { listSeeds, readSeedContents } from '@/claude/seeds-list'
+import { listSkills } from '@/claude/skills-list'
 import {
   planSettings,
   readSettings,
@@ -43,6 +44,11 @@ interface SeedsListOptions {
   readonly names?: boolean
 }
 
+interface SkillsListOptions {
+  readonly json?: boolean
+  readonly names?: boolean
+}
+
 const SEEDED_FILES: readonly string[] = [
   'ARCHITECTURE.md',
   'REQUIREMENTS.md',
@@ -130,6 +136,42 @@ export function register(program: Command): void {
     .action(async (opts: SeedsListOptions) => {
       process.exitCode = await runSeedsList(opts)
     })
+
+  const skills = claude
+    .command('skills')
+    .description('Plugin skill catalog (list)')
+    .argument('[subcommand]', "Only 'list' is supported")
+    .helpOption('-h, --help', 'Show this help message')
+    .action((subcommand: string | undefined) => {
+      intro('aitk claude')
+      logError(
+        subcommand === undefined
+          ? "Missing subcommand. Use 'list'."
+          : `Unknown subcommand: ${subcommand}. Use 'list'.`,
+      )
+      outro()
+      process.exitCode = 1
+    })
+
+  skills
+    .command('list')
+    .description('List the plugin skills shipped under claude/skills/')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit JSON with name and description')
+    .option('--names', 'Only list skill names, one per line')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Notes:',
+        '  Internal skills under .claude/skills/ are excluded, since they',
+        '  never install into a target project.',
+        '',
+      ].join('\n'),
+    )
+    .action((opts: SkillsListOptions) => {
+      process.exitCode = runSkillsList(opts)
+    })
 }
 
 function succeed(message: string): number {
@@ -347,3 +389,27 @@ async function runSeedsList(opts: SeedsListOptions): Promise<number> {
   outro()
   return 0
 }
+
+function runSkillsList(opts: SkillsListOptions): number {
+  const listings = listSkills(PROJECT_ROOT)
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify({ skills: listings })}\n`)
+    return 0
+  }
+
+  if (opts.names) {
+    process.stdout.write(
+      listings.map((listing) => listing.name).join('\n') + '\n',
+    )
+    return 0
+  }
+
+  intro('aitk claude')
+  logStep('Plugin skills')
+  for (const listing of listings) {
+    logInfo(listing.name)
+  }
+  outro()
+  return 0
+}

package/src/commands/context.ts

@@ -45,7 +45,9 @@ export function register(program: Command): void {
 
   context
     .command('audit')
-    .description('Report entry length, depth, citations, and index drift')
+    .description(
+      'Report entry length, depth, citations, provenance, and index drift',
+    )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
@@ -61,7 +63,7 @@ export function register(program: Command): void {
         '  2  a cited path did not resolve',
         '',
         'Only unresolved citations set a failing exit code. Length, depth,',
-        'table, and index findings are advisory.',
+        'table, provenance, and index findings are advisory.',
         '',
         'Examples:',
         '  aitk context audit',
@@ -134,6 +136,7 @@ async function runAudit(
     reportLength(entries)
     reportDepth(entries)
     reportTables(entries)
+    reportProvenance(entries)
     reportDrift(drift)
     outro()
   }
@@ -303,6 +306,46 @@ function reportTables(entries: readonly EntryReport[]): void {
   pipeOutput(candidates.join('\n'))
 }
 
+/**
+ * Groups by entry rather than listing every marker.
+ *
+ * The two entries carrying most of a corpus's markers carry them a dozen at a
+ * time, and a flat list of those buries the entries holding one. What a reader
+ * acts on is which file to open, so the count sits beside the name and the
+ * lines follow it.
+ */
+function reportProvenance(entries: readonly EntryReport[]): void {
+  logStep('Provenance')
+  logInfo('Fenced blocks are excluded. A marker is a judgment, never a defect.')
+
+  const carrying = entries
+    .filter((entry) => entry.provenance.length > 0)
+    .sort((a, b) => b.provenance.length - a.provenance.length)
+
+  if (carrying.length === 0) {
+    logInfo('No entry narrates a change.')
+    return
+  }
+
+  const total = carrying.reduce(
+    (sum, entry) => sum + entry.provenance.length,
+    0,
+  )
+  logWarn(
+    `${plural(total, 'marker')} across ${carrying.length} ${carrying.length === 1 ? 'entry' : 'entries'}`,
+  )
+  pipeOutput(
+    carrying
+      .map(
+        (entry) =>
+          `${entry.rel}  ${plural(entry.provenance.length, 'marker')}\n${entry.provenance
+            .map((found) => `  :${found.line}  ${found.kind}  ${found.text}`)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
 function reportDrift(drift: readonly FolderDrift[]): void {
   logStep('Index drift')
 

package/src/context/audit.ts

@@ -25,11 +25,35 @@ const TABLE_ROW = /^\s*\|/
 const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
 const NAMED_CELL = /`[^`]+`|\[[^\]]+\]\([^)]+\)/
 
+/**
+ * Spellings of how the domain reached its shape rather than what it is now.
+ *
+ * The standard admits a rejected alternative and its reasoning while refusing
+ * the provenance attached to it, and these three are what a session reaches for
+ * when it records the second: when a change landed, which change carried it,
+ * and which release labelled it. A marker is a judgment rather than a defect,
+ * so this is measured and reported and never gates.
+ */
+const PROVENANCE: readonly { kind: ProvenanceKind; pattern: RegExp }[] = [
+  { kind: 'date', pattern: /\b\d{4}-\d{2}-\d{2}\b/g },
+  { kind: 'change', pattern: /#\d{3,}\b/g },
+  { kind: 'release', pattern: /\bv\d+\.\d+(?:\.\d+)?\b/g },
+]
+
+export type ProvenanceKind = 'date' | 'change' | 'release'
+
 export interface TableFinding {
   readonly line: number
   readonly rows: number
 }
 
+export interface ProvenanceFinding {
+  readonly line: number
+  readonly kind: ProvenanceKind
+  /** The marker as written, so a report names what to go and look at. */
+  readonly text: string
+}
+
 export interface EntryReport {
   readonly rel: string
   readonly lines: number
@@ -37,6 +61,7 @@ export interface EntryReport {
   /** First line of the longest run, or 0 when the entry has no run at all. */
   readonly longestRunLine: number
   readonly catalogTables: readonly TableFinding[]
+  readonly provenance: readonly ProvenanceFinding[]
 }
 
 interface BodyLine {
@@ -191,6 +216,44 @@ function catalogTables(lines: readonly BodyLine[]): TableFinding[] {
   return findings
 }
 
+/**
+ * Finds the markers narrating a change rather than describing the domain.
+ *
+ * Fenced blocks are skipped for the same reason the table scan skips them: a
+ * sample command or a fixture inside an example is content the entry displays
+ * rather than a claim it makes, and a version pinned in an install line is the
+ * ordinary shape of one.
+ */
+function provenance(lines: readonly BodyLine[]): ProvenanceFinding[] {
+  // Scanning one pattern at a time emits a line's markers grouped by kind, so
+  // the column is carried out of the match and sorted on. Without it a line
+  // holding a date and two change numbers reports them in an order the reader
+  // cannot find by scanning left to right.
+  const found: { finding: ProvenanceFinding; column: number }[] = []
+  let fenced = false
+
+  for (const line of lines) {
+    if (FENCE.test(line.text)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+
+    for (const { kind, pattern } of PROVENANCE) {
+      for (const match of line.text.matchAll(pattern)) {
+        found.push({
+          finding: { line: line.number, kind, text: match[0] },
+          column: match.index,
+        })
+      }
+    }
+  }
+
+  return found
+    .sort((a, b) => a.finding.line - b.finding.line || a.column - b.column)
+    .map((each) => each.finding)
+}
+
 export function measureEntry(rel: string, source: string): EntryReport {
   const lines = bodyLines(source)
   const run = longestRun(lines)
@@ -201,6 +264,7 @@ export function measureEntry(rel: string, source: string): EntryReport {
     longestRun: run.length,
     longestRunLine: run.line,
     catalogTables: catalogTables(lines),
+    provenance: provenance(lines),
   }
 }
 

package/standards/context.md

@@ -94,11 +94,13 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Tutorials or human onboarding. Those go in `docs/` if a public audience exists.
 - Generated content (API references). Generate, do not write by hand.
 - Anything already in `.claude/REQUIREMENTS.md` or `.claude/ARCHITECTURE.md`.
+- The history of how the domain reached its current shape. An entry describes the repository as it stands, so a change number, release label, or date attached to a change goes wherever the project tracks work.
+- A rejected alternative's provenance, which is the same rule at the one place the section above admits history. Keep what was tried and why it lost. Cut who tried it and when.
 
 ## Length
 
 - Aim for one entry per domain. There is no hard cap. Length is a symptom, not the defect.
-- Past roughly 150 lines, check two things before adding more: whether the entry still covers a single domain, and whether it has filled with content `ls` or `--help` reproduces. Fix whichever is true rather than trimming to hit a number.
+- Past roughly 150 lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number.
 - Past roughly 40 lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint like the 150 above, not a cap.
 - Exempt a block whose lines are all list items at one level. A long list of peers is already navigable, and a subheading dropped into it splits a set that belongs together. Mixing prose with the list, or nesting levels inside it, ends the exemption.
 - Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.

package/standards/index.md

@@ -19,6 +19,6 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
-- [Tasks reference](tasks.md): Folder layout, filename convention, and content rules for .claude/tasks/
+- [Tasks reference](tasks.md): Folder layout, filename convention, readiness groups, and content rules for .claude/tasks/
 - [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
 - [Wireframe reference](wireframes.md): Shape and content rules for .claude/wireframes/<surface>.md files

package/standards/tasks.md

@@ -1,6 +1,6 @@
 ---
 title: Tasks reference
-description: Folder layout, filename convention, and content rules for .claude/tasks/
+description: Folder layout, filename convention, readiness groups, and content rules for .claude/tasks/
 ---
 
 # Tasks reference
@@ -11,7 +11,7 @@ The folder is gitignored. Board state changes when work ships rather than when a
 
 ## Scope
 
-Governs the task board under `.claude/tasks/`: folder layout, filenames, frontmatter, file format, origin lines, and archiving.
+Governs the task board under `.claude/tasks/`: folder layout, filenames, frontmatter, file format, origin lines, execution ordering, and archiving.
 
 Does not govern:
 
@@ -34,11 +34,23 @@ One file per task is what keeps the board safe under parallel sessions. Two sess
 
 `index.md` is generated from sibling frontmatter. The folder is gitignored, so the whole-repo index walk skips it and a hook passing the changed path regenerates it instead. Never hand-edit it.
 
+The `claude-tasks` skill creates and archives task files. `claude-docs` marks outcomes `[x]` in an existing file and sweeps the plans those tasks cite. Neither does the other's job.
+
+## Ordering
+
 `priority.md` carries execution order and what each task is waiting on. The generated index sorts by filename and says nothing about order, so without this file board state gets reconstructed by hand every session. Why the order is what it is belongs in `.claude/ROADMAP.md`, which is committed because that rationale has no substitute record.
 
-Group tasks by readiness rather than by status, one row per task, with a stated column for what each is blocked on. Keep it to links and blockers: tables, plus at most one sentence per section. A paragraph in `priority.md` is a defect whatever it says. Stating the shape this way is what lets a single diff fail, since a size cap only trips after the fact and every addition looks defensible on its own.
+Group tasks by readiness rather than by status, one row per task, under the columns each group fixes below. Keep it to links and blockers: tables, plus at most one sentence per section. A paragraph in `priority.md` is a defect whatever it says. Stating the shape this way is what lets a single diff fail, since a size cap only trips after the fact and every addition looks defensible on its own.
 
-The `claude-tasks` skill creates and archives task files. `claude-docs` marks outcomes `[x]` in an existing file and sweeps the plans those tasks cite. Neither does the other's job.
+Readiness is three groups under fixed headings, `## Run now`, `## Up next`, and `## Needs a plan`, in that order. The names are the contract rather than a suggestion, because a board grouped by readiness under names of its own satisfies every other rule here and still reads as empty to anything counting rows under a heading. Add no fourth group. A task belongs to exactly one, and the tests are read in order.
+
+- `## Run now`: a written plan covers every open outcome, and the files the task touches collide with nothing already running. A worker is handed a task from this group alone.
+- `## Up next`: a written plan exists, and the task either collides with something running or waits on another task to land. The blocker column names which.
+- `## Needs a plan`: everything else. The task has no plan, or the plan it carries no longer describes the work.
+
+Each group fixes its own columns, which follow from the test above it rather than from preference. `## Run now` carries `Task`, `Touches`, and `Plan`, since neither half of its test is checkable without the last two. `## Up next` carries `Task`, `Touches`, and `Waiting on`, the last naming whether a collision or a dependency holds it. `## Needs a plan` carries `Task` and `Waiting on` alone, because a task with no plan has no bounded file set to state.
+
+The tests live here so the board does not carry them. Writing them as a sentence under each heading produces the paragraph the rule above deletes, and a criterion with no home gets restated from memory every time the board is touched.
 
 ## Filenames