@erclx/aitk 0.29.0 → 0.30.1

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

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

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

@@ -16,6 +16,7 @@ Without this skill, the memory folder grows and never drains. Entries pile up re
 - Rewrite a rule into the destination's voice instead of moving it unchanged
 - Write the proposal to a receipt on disk and take no action until the user decides per item
 - Keep a promotion on its own commit, since a change to how the agent operates should not ride inside a feature a reviewer is vetting for something else
+- Confine the pass that runs after application to the one receipt it tested, so tidying up removes a file whose decisions are known to be resolved and leaves the pen and every untested receipt alone
 
 ## Must not
 
@@ -23,12 +24,14 @@ Without this skill, the memory folder grows and never drains. Entries pile up re
 - Author a governance rule inline. Coding-standards rules have an owner and a scaffolding path, and a rule written here bypasses both.
 - Mutate tracked files from the main worktree
 - Answer a question raised in a decision slot while applying. Discussion and application are separate passes so an approval is never inferred from a reply.
+- Delete a memory entry outside the approved-per-item pass. The folder is gitignored with no history behind it, so a removal any other phase makes has no undo and no record of what it took.
 
 ## Guards
 
 - No memory folder at the main root: stop
 - The folder holds only its index: stop with a pass, not an error
 - Apply invoked from the main worktree: stop and name the worktree command
+- Cleanup invoked with no receipt on disk: stop with a pass, not an error
 
 ## Out of scope
 

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

@@ -7,21 +7,22 @@ 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`.
 
-| User intent                                    | Phase     | Mutates                      |
-| ---------------------------------------------- | --------- | ---------------------------- |
-| "review memory", "promote memory" (no receipt) | Propose   | review file only             |
-| "challenge the promotes" (receipt exists)      | Challenge | review file only             |
-| "discuss", "respond to questions"              | Discuss   | review file only             |
-| "apply decisions", "commit", "ship the review" | Apply     | tracked files + memory files |
-| "cleanup", "sweep stale", "delete the receipt" | Cleanup   | memory files + review file   |
+| User intent                                                            | Phase     | Mutates                      |
+| ---------------------------------------------------------------------- | --------- | ---------------------------- |
+| "review memory", "promote memory", "sweep stale memories" (no receipt) | Propose   | review file only             |
+| "challenge the promotes" (receipt exists)                              | Challenge | review file only             |
+| "discuss", "respond to questions"                                      | Discuss   | review file only             |
+| "apply decisions", "commit", "ship the review"                         | Apply     | tracked files + memory files |
+| "cleanup", "delete the receipt"                                        | Cleanup   | one review file              |
 
-If the user just re-pings the skill with no new phrase and a receipt exists, default to Discuss when any `Decision:` contains `?`, otherwise Apply.
+If the user re-pings the skill with no new phrase and a receipt exists, default to Discuss when any `Decision:` contains `?`, otherwise Apply.
 
 ## Guards
 
 - All `.claude/memory/` reads, edits, and deletes resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
 - If no `.claude/memory/` directory exists at the main worktree root, stop: `❌ No .claude/memory/ directory found.`
 - If `.claude/memory/` contains no `*.md` entries other than `MEMORY.md`, stop: `✅ No memory entries to review.`
+- Cleanup is exempt from the two stops above. It works on receipts in `.claude/review/`, and a drained pen is the normal state once Apply has run, so a pen-shaped stop would strand the receipt it exists to delete.
 - Resolve the main root via `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. All review and memory reads anchor here.
 
 ## Propose phase
@@ -186,14 +187,17 @@ End with: `✅ Applied: <nums> | ⏭ Skipped: <nums> | 📝 Pending: <nums>`. Om
 
 ## Cleanup phase
 
-Trigger: user says "cleanup", "sweep stale memories", or "delete the receipt" after Apply has run.
+Trigger: user says "cleanup" or "delete the receipt" after Apply has run.
 
-1. Read the latest `.claude/review/memory-review-*.md` to see which entries were skipped.
-2. Treat a `Skip` decision as terminal. Do not delete a memory just because it would Skip again next review. Target only entries whose decision value is exhausted: already-applied promotions and stale receipts.
-3. Delete the review file itself.
-4. Leave applied promotions, governance handoffs, and user-type memories alone.
+Cleanup removes one receipt and nothing else. Apply is the only phase that deletes a memory entry, and it does so per approved item against a folder that is gitignored with no history behind it, so a deletion made anywhere else has no undo and leaves no record of what it took. A user asking to sweep stale memories wants Propose, which classifies entries and writes a decision slot per entry.
 
-Do not promote or rewrite. Cleanup only.
+If no `.claude/review/memory-review-*.md` exists at the main root, stop: `✅ No review receipt to clean up.` Every other refusal in this skill carries a message, and the phase reads a receipt before it does anything else.
+
+1. Read the latest `.claude/review/memory-review-*.md` at the main root and confirm Apply has run against it. If any item is still 📝 pending, stop and name the pending numbers.
+2. Delete that one file. Leave every other receipt beside it in place, because the pending test above covers the file it read and nothing has tested the rest.
+3. Leave every memory entry in place. A `Skip` decision is terminal, and applied promotions, governance handoffs, and user-type memories each stay as the review left them.
+
+Do not promote, rewrite, or delete a memory entry. Receipts only.
 
 ## After completion
 
@@ -202,5 +206,6 @@ Output one line per action taken in the most recent phase:
 - `✅ Promoted: .claude/memory/<memory-file> → <target>`
 - `✅ Handed off: .claude/memory/<memory-file> → governance`
 - `🗑  Deleted: .claude/memory/<memory-file>`
+- `🗑  Swept: .claude/review/<review-file>`
 
 If the user accepted nothing, output: `✅ No changes applied.`

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
@@ -387,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
 
@@ -395,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

package/package.json

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

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.