@erclx/aitk 3.15.0 → 3.16.0

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

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

package/docs/agents/commands.md

@@ -37,6 +37,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk teach resource`      | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`)                                          |
 | `aitk teach glossary`      | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`)                                            |
 | `aitk records validate`    | Report a session record or a standard against the standard governing it, per kind (`--json`)                                                   |
+| `aitk records migrate`     | Rewrite the records a validate finding names a recoverable transform for (`--write`, `--json`)                                                 |
 | `aitk records size`        | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)                                                   |
 | `aitk records push`        | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                     |
 | `aitk records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                        |

package/docs/agents/index.md

@@ -24,7 +24,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
 - [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 session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
+- [Records](records.md): Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 - [Restated instructions](restated.md): Counting the instructions the always-loaded file shares with the seed and the shipped skill bodies, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
 - [Routing report](routing.md): Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills

package/docs/agents/records.md

@@ -1,6 +1,6 @@
 ---
 title: Records
-description: Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
+description: Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 ---
 
 # Records
@@ -72,6 +72,28 @@ aitk records validate plans --json | jq -r '.findings[] | "\(.kind): \(.subject)
 
 For the shapes each check enforces, see `.claude/standards/plan.md`, `.claude/standards/groundwork.md`, `.claude/standards/intake.md`, `.claude/standards/memory.md`, and `.claude/standards/standard.md`.
 
+## Migrate
+
+`aitk records migrate <kind>` rewrites the records a `validate` finding names a transform for. A standard that redefines its own required frontmatter breaks every record already written to the old shape, and this is the repair `validate` could only report until now.
+
+```bash
+aitk records migrate memory
+aitk records migrate memory --write
+aitk records migrate memory --json
+```
+
+| Option          | Behavior                                                            |
+| --------------- | ------------------------------------------------------------------- |
+| `--json`        | Add a machine-readable record on stdout                             |
+| `--write`       | Rewrite every record a transform can repair                         |
+| `--root <path>` | Project root, defaulting to the main worktree except on `standards` |
+
+It writes nothing until `--write` is passed, matching the write-flag contract `aitk tooling sync` carries: a session record has no history to undo a wrong repair from, so naming a kind is not consent to rewrite every record inside it. A dry run reports which records it would touch and exits non-zero either way, headless or not, since there is nothing to prompt for.
+
+A transform runs only where the missing value is recoverable from the file itself. The one shipped today repairs a memory record missing `category` alone, deriving it from the same filename prefix `checkMemory` already reads it from. `title` and `description` are prose nobody wrote down, so a finding naming either carries no transform and stays for a session to fix by hand, and `validate` keeps reporting it. The transform re-reads the file rather than trusting a value captured at validate time, so a check and its repair cannot disagree about the same record.
+
+Exit codes: `0` nothing carried a known transform, or `--write` repaired everything it found. `1` refused for a reason `validate` shares, every candidate it found failed to repair, or `--write` repaired only some of them. `2` a record carries a known transform and `--write` was not passed.
+
 ## Size
 
 `aitk records size` reports what each record folder holds and how much of it is recent. It reads the ten backed folders named under Push and pull, plus `.claude/.tmp`, and it gates nothing.

package/package.json

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

package/src/commands/records.ts

@@ -1,5 +1,8 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
 import type { Command } from 'commander'
 import { BACKED_FOLDERS, pullRecords, pushRecords } from '@/records/backup'
+import { migrateRecord } from '@/records/migrate'
 import {
   type FolderSize,
   formatBytes,
@@ -10,10 +13,12 @@ import {
 } from '@/records/size'
 import {
   type Finding,
+  type FindingRemedy,
   isRecordKind,
   isSharedScratch,
   RECORD_KINDS,
   type RecordKind,
+  recordsDir,
   type ValidateOutcome,
   validateRecords,
 } from '@/records/validate'
@@ -32,6 +37,9 @@ import { currentWorktreeRoot, mainWorktreeRoot } from '@/worktree'
 /** Returned when a record carries a finding, which is the gating result. */
 const EXIT_FINDINGS = 2
 
+/** Returned when a record carries a known transform and `--write` was not passed. */
+const EXIT_MIGRATABLE = 2
+
 interface ValidateCommandOptions {
   readonly json?: boolean
   readonly root?: string
@@ -39,6 +47,10 @@ interface ValidateCommandOptions {
 
 type BackupCommandOptions = ValidateCommandOptions
 
+interface MigrateCommandOptions extends ValidateCommandOptions {
+  readonly write?: boolean
+}
+
 export function register(program: Command): void {
   const records = program
     .command('records')
@@ -90,6 +102,44 @@ export function register(program: Command): void {
       process.exitCode = await runValidate(kind, opts)
     })
 
+  records
+    .command('migrate')
+    .description('Rewrite the records a validate finding names a transform for')
+    .argument('<kind>', `Record folder: ${RECORD_KINDS.join(', ')}`)
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--write', 'Rewrite every record a transform can repair')
+    .option(
+      '--root <path>',
+      'Project root, defaulting to the main worktree except on standards',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  nothing carries a known transform, or --write repaired every one',
+        '  1  refused, with the reason on stderr or in the JSON record, every',
+        '     candidate it found failed to repair, or --write repaired only',
+        '     some of them',
+        '  2  a record carries a known transform and --write was not passed',
+        '',
+        'It reports and never writes without --write, matching aitk records',
+        'validate: a session record has no history to undo a wrong repair from.',
+        'A transform is only offered where the old value is recoverable from the',
+        'file itself, so a finding with no transform is left for a session to fix.',
+        '',
+        'Examples:',
+        '  aitk records migrate memory',
+        '  aitk records migrate memory --write',
+        '  aitk records migrate memory --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (kind: string, opts: MigrateCommandOptions) => {
+      process.exitCode = await runMigrate(kind, opts)
+    })
+
   records
     .command('size')
     .description('Report what each record folder holds and how much is recent')
@@ -456,3 +506,223 @@ function describe(found: Finding): string {
   const scope = found.record === found.subject ? '' : `${found.record}: `
   return `${scope}${found.subject} ${found.message}`
 }
+
+export interface Repair {
+  readonly record: string
+  readonly remedy: FindingRemedy
+  readonly path: string
+  readonly text: string
+}
+
+export interface Refusal {
+  readonly record: string
+  readonly message: string
+}
+
+/** The message a rejected promise leaves, for a record whose read or write failed. */
+function describeFailure(reason: unknown): string {
+  return reason instanceof Error ? reason.message : String(reason)
+}
+
+/**
+ * Runs every finding's transform, without writing anything back.
+ *
+ * `Promise.allSettled` rather than `Promise.all`, so a record whose read
+ * fails, such as one deleted between `validate`'s listing and this read,
+ * becomes a refusal for that one record rather than an unhandled rejection
+ * that `program.parse()` has no top-level catch for.
+ */
+async function attemptMigrations(
+  dir: string,
+  findings: readonly Finding[],
+): Promise<{ repaired: Repair[]; refused: Refusal[] }> {
+  const candidates = findings.filter(
+    (found): found is Finding & { readonly remedy: FindingRemedy } =>
+      found.remedy !== undefined,
+  )
+
+  const settled = await Promise.allSettled(
+    candidates.map(async (found) => {
+      const path = join(dir, found.record)
+      const outcome = migrateRecord(
+        found.remedy,
+        found.record,
+        await readFile(path, 'utf8'),
+      )
+      return { record: found.record, remedy: found.remedy, path, outcome }
+    }),
+  )
+
+  const repaired: Repair[] = []
+  const refused: Refusal[] = []
+
+  settled.forEach((result, index) => {
+    if (result.status === 'rejected') {
+      refused.push({
+        record: candidates[index].record,
+        message: `could not be read: ${describeFailure(result.reason)}`,
+      })
+      return
+    }
+
+    const { record, remedy, path, outcome } = result.value
+
+    if (outcome.ok) {
+      repaired.push({ record, remedy, path, text: outcome.text })
+    } else {
+      refused.push({ record, message: outcome.message })
+    }
+  })
+
+  return { repaired, refused }
+}
+
+/**
+ * Writes every repair, independently. `Promise.allSettled` so one record's
+ * write failing does not abort the writes that would otherwise have
+ * succeeded, per the concurrency standard's rule on batched partial failure.
+ */
+async function writeRepairs(
+  repaired: readonly Repair[],
+): Promise<{ written: Repair[]; failed: Refusal[] }> {
+  const settled = await Promise.allSettled(
+    repaired.map((entry) => writeFile(entry.path, entry.text, 'utf8')),
+  )
+
+  const written: Repair[] = []
+  const failed: Refusal[] = []
+
+  settled.forEach((result, index) => {
+    const entry = repaired[index]
+
+    if (result.status === 'fulfilled') {
+      written.push(entry)
+    } else {
+      failed.push({
+        record: entry.record,
+        message: `could not be written: ${describeFailure(result.reason)}`,
+      })
+    }
+  })
+
+  return { written, failed }
+}
+
+async function runMigrate(
+  kind: string,
+  opts: MigrateCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (!isRecordKind(kind)) {
+    return reportRefusal(
+      'aitk records migrate',
+      {
+        reason: 'unknown-kind',
+        message: `Not a record kind: ${kind}. Expected one of: ${RECORD_KINDS.join(', ')}.`,
+      },
+      emitJson,
+    )
+  }
+
+  const root = opts.root ?? (await defaultRoot(kind))
+  const outcome = await validateRecords(root, kind)
+
+  if (!outcome.ok) {
+    return reportRefusal('aitk records migrate', outcome, emitJson)
+  }
+
+  const write = opts.write ?? false
+  const { repaired, refused } = await attemptMigrations(
+    recordsDir(root, kind),
+    outcome.findings,
+  )
+
+  if (!write) {
+    return reportMigrate(root, outcome.kind, repaired, refused, write, emitJson)
+  }
+
+  const { written, failed } = await writeRepairs(repaired)
+
+  return reportMigrate(
+    root,
+    outcome.kind,
+    written,
+    [...refused, ...failed],
+    write,
+    emitJson,
+  )
+}
+
+function reportMigrate(
+  root: string,
+  kind: RecordKind,
+  repaired: readonly Repair[],
+  refused: readonly Refusal[],
+  write: boolean,
+  emitJson: boolean,
+): number {
+  const total = repaired.length + refused.length
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        kind,
+        written: write,
+        migrated: repaired.map((entry) => entry.record),
+        refused,
+      })}\n`,
+    )
+  } else {
+    intro('aitk records migrate')
+
+    if (total === 0) {
+      logStep('Clean')
+      logInfo('no finding carries a known transform')
+    } else {
+      logStep(write ? 'Rewritten' : 'Would rewrite')
+      if (repaired.length === 0) {
+        logInfo('none, every candidate refused, see below')
+      } else {
+        for (const entry of repaired)
+          logInfo(`${entry.record}: ${entry.remedy}`)
+      }
+
+      if (refused.length > 0) {
+        logStep('Refused')
+        for (const entry of refused)
+          logWarn(`${entry.record}: ${entry.message}`)
+      }
+
+      if (!write && repaired.length > 0) {
+        logInfo('Re-run with --write to apply.')
+      }
+    }
+
+    outro()
+  }
+
+  return migrateExitCode(repaired, refused, write)
+}
+
+/**
+ * `repaired` carries only records a transform actually fixed, whether this
+ * is a dry run or the set `--write` wrote, so exit 2 (a write is available)
+ * never fires when every candidate refused. A dry run reaching that state
+ * previously returned the same code as a genuine offer to write, telling a
+ * caller `--write` would repair something when it would repair nothing.
+ */
+export function migrateExitCode(
+  repaired: readonly Repair[],
+  refused: readonly Refusal[],
+  write: boolean,
+): number {
+  const total = repaired.length + refused.length
+
+  if (total === 0) return 0
+  if (repaired.length === 0) return 1
+  if (!write) return EXIT_MIGRATABLE
+  return refused.length > 0 ? 1 : 0
+}

package/src/records/migrate.ts

@@ -0,0 +1,78 @@
+import { parseFrontmatter, readField } from '@/indexes/frontmatter'
+import {
+  CATEGORY_BY_TYPE,
+  type FindingRemedy,
+  MEMORY_NAME,
+  memoryType,
+} from '@/records/validate'
+
+export const MIGRATE_REFUSALS = ['field-unrecoverable'] as const
+
+export type MigrateRefusal = (typeof MIGRATE_REFUSALS)[number]
+
+export interface MigrateRepair {
+  readonly ok: true
+  readonly text: string
+}
+
+export interface MigrateRefused {
+  readonly ok: false
+  readonly reason: MigrateRefusal
+  readonly message: string
+}
+
+export type MigrateOutcome = MigrateRepair | MigrateRefused
+
+function refuse(message: string): MigrateRefused {
+  return { ok: false, reason: 'field-unrecoverable', message }
+}
+
+/**
+ * Repairs the one recoverable shape of `frontmatter-incomplete`: a memory
+ * record missing `category` alone. The value sits in the filename's type
+ * prefix already, which is the same fact `checkMemory` derives it from, so a
+ * repair here writes back what the record already states rather than a value
+ * a transform invented. It re-reads the file rather than trusting a value
+ * carried on the `Finding`, so a transform and the check it repairs cannot
+ * drift apart.
+ */
+function categoryFromName(name: string, text: string): MigrateOutcome {
+  const frontmatter = parseFrontmatter(text)
+  if (!frontmatter) {
+    return refuse(`${name} carries no frontmatter block to add category to.`)
+  }
+
+  if (readField(frontmatter, 'category')) {
+    return refuse(`${name} already carries a category.`)
+  }
+
+  const match = MEMORY_NAME.exec(name)
+  const type = match ? memoryType(match[1]) : undefined
+  if (!type) {
+    return refuse(
+      `${name} is not named <type>-<slug>.md, so category has no type to derive from.`,
+    )
+  }
+
+  const rewritten = frontmatter.raw.replace(
+    /\n---$/,
+    `\ncategory: ${CATEGORY_BY_TYPE[type]}\n---`,
+  )
+
+  return { ok: true, text: rewritten + text.slice(frontmatter.raw.length) }
+}
+
+const TRANSFORMS: Readonly<
+  Record<FindingRemedy, (name: string, text: string) => MigrateOutcome>
+> = {
+  'category-from-name': categoryFromName,
+}
+
+/** Applies the transform a finding's `remedy` names against its own text. */
+export function migrateRecord(
+  remedy: FindingRemedy,
+  name: string,
+  text: string,
+): MigrateOutcome {
+  return TRANSFORMS[remedy](name, text)
+}

package/src/records/validate.ts

@@ -72,12 +72,22 @@ export const FINDING_KINDS = [
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
 
+/**
+ * The transforms `migrate.ts` carries. Most finding kinds have none, since a
+ * transform is only safe where the old shape is recoverable from the file
+ * itself, so this stays optional on `Finding` rather than required.
+ */
+export const FINDING_REMEDIES = ['category-from-name'] as const
+
+export type FindingRemedy = (typeof FINDING_REMEDIES)[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
+  readonly remedy?: FindingRemedy
 }
 
 export interface ValidateReport {
@@ -134,8 +144,9 @@ function finding(
   record: string,
   subject: string,
   message: string,
+  remedy?: FindingRemedy,
 ): Finding {
-  return { kind, record, subject, message }
+  return { kind, record, subject, message, remedy }
 }
 
 async function listMarkdown(dir: string): Promise<string[]> {
@@ -748,26 +759,41 @@ const MEMORY_FIELDS = ['title', 'description', 'category'] as const
  * catches a prefix outside the set, a field disagreeing with the prefix, and a
  * casing drift that would open a second group in the catalog.
  */
-const CATEGORY_BY_TYPE = {
+export const CATEGORY_BY_TYPE = {
   feedback: 'Feedback',
   project: 'Project',
   user: 'User',
   reference: 'Reference',
 } as const
 
-type MemoryType = keyof typeof CATEGORY_BY_TYPE
+export type MemoryType = keyof typeof CATEGORY_BY_TYPE
 
 const MEMORY_TYPES = Object.keys(CATEGORY_BY_TYPE) as readonly MemoryType[]
 
-const MEMORY_NAME = /^([a-z]+)-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/
+export const MEMORY_NAME = /^([a-z]+)-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/
 
 /** The two markers a rule-bearing body carries, on top of the rule line itself. */
 const MEMORY_MARKERS = ['**Why:**', '**How to apply:**'] as const
 
-function memoryType(value: string): MemoryType | undefined {
+export function memoryType(value: string): MemoryType | undefined {
   return MEMORY_TYPES.find((type) => type === value)
 }
 
+/**
+ * The one missing-field shape `migrate.ts` can repair: `category` alone,
+ * recoverable from the same filename prefix `checkMemory` already read it
+ * from. `title` and `description` are prose nobody wrote down, so a finding
+ * naming either carries no remedy.
+ */
+function memoryRemedy(
+  missing: readonly string[],
+  named: MemoryType | undefined,
+): FindingRemedy | undefined {
+  return named && missing.length === 1 && missing[0] === 'category'
+    ? 'category-from-name'
+    : undefined
+}
+
 export function checkMemory(name: string, text: string): Finding[] {
   const findings: Finding[] = []
   const match = MEMORY_NAME.exec(name)
@@ -796,6 +822,7 @@ export function checkMemory(name: string, text: string): Finding[] {
         name,
         name,
         `carries no ${missing.join(' and no ')}.`,
+        memoryRemedy(missing, named),
       ),
     )
   }