runlist 0.95.3 → 0.95.6

package/README.md

@@ -47,8 +47,8 @@ controls are experimental; live retrieval depends on a compatible external
 provider. Local chat and push are deferred.
 
 <!-- runlist:release:start -->
-CLI and desktop release version: **0.95.3**.
-[Mac installer and release notes](https://github.com/reowens/runlist/releases/tag/desktop-v0.95.3).
+CLI and desktop release version: **0.95.6**.
+[Mac installer and release notes](https://github.com/reowens/runlist/releases/tag/desktop-v0.95.6).
 Normal product releases publish both components; an installed Mac app is updated with rollback after it has quit.
 <!-- runlist:release:end -->
 

package/bin/runlist.mjs

@@ -293,7 +293,7 @@ Validate & Fix:
   doctor --transactions             Report/clear wedged mutation transactions (run this if mutations refuse repo-wide)
   doctor --claims                   Report/release plan claims held by sessions that are gone ("busy in another session")
   self-check                        Project/version skew diagnostic (alias: doctor --project)
-  lint [--fix]                      Check and auto-fix frontmatter issues
+  lint [files...] [--fix]                      Check and auto-fix frontmatter issues
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
   refs <old> <new> [--fix]          Report (or rewrite) code-root citations of a moved document
   refs repair [--fix]               Same, for every archived document still cited at its old path
@@ -923,7 +923,7 @@ Modes:
                          history; a "Migrated to v0.21 template" entry
                          in their Version History would be misleading).
   --migrate-template --json  Machine-readable result.
-  --frontmatter-fix      Auto-fix the long-frontmatter warnings that
+  --frontmatter-fix [path]  Repair only that document when supplied; otherwise auto-fix the long-frontmatter warnings that
                          \`runlist check\` flags: \`current_state\` >1500 chars
                          or \`next_step\` >800 chars. Truncates the
                          frontmatter field at the nearest sentence
@@ -1195,9 +1195,9 @@ Options:
   --summarize            Generate AI summary using local model
   --model <name>         Model to use (default: the one \`runlist model\` shows)`,
 
-  lint: `runlist lint [--fix] — check and auto-fix frontmatter issues
+  lint: `runlist lint [files...] [--fix] — check and auto-fix frontmatter issues
 
-Scans all docs for fixable problems:
+Scans the selected documents, or all docs when no file is supplied, for fixable problems:
   - Missing status (inferred via local AI model when available)
   - Missing updated date (set to today)
   - Status casing (e.g. Active → active)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist",
-  "version": "0.95.3",
+  "version": "0.95.6",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/plugins/runlist-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist-codex",
-  "version": "0.95.3",
+  "version": "0.95.6",
   "description": "Runlist workflow skill, session orientation, and tool guard for Codex",
   "author": {
     "name": "Reo Owens"

package/src/commands.mjs

@@ -170,7 +170,7 @@ const definitions = [
     options: [value('--status'), value('--title'), value('--runlist'), flag('--coordination'), flag('--roadmap'), flag('--lite', '--minimal'), flag('--audit', '--findings'), value('--body', '--message'), value('--root'), flag('--show-files'), flag('--list-templates', '--list-types'), flag('--render-preview'), value('--question'), value('--answers'), value('--disposition')],
     dashPositionalsAfter: 1,
   })]),
-  command('lint', mutates('managed source sweep with --fix; otherwise read-only'), 'mutate', [form('', { options: [flag('--fix')] })]),
+  command('lint', mutates('selected managed sources with --fix; otherwise read-only'), 'mutate', [form('[files...]', { args: positionals(0, Infinity), options: [flag('--fix')] })]),
   command('rename', mutates('managed source, same-root destination, and rewrite sweep'), 'mutate', [form('<old> [new]', { args: positionals(1, 2), options: [flag('--show-files'), flag('--fix-refs'), flag('--strings')] })]),
   command('migrate', mutates('managed source sweep'), 'mutate', [form('<field> <old> <new> [files...]', { args: positionals(3, Infinity), options: [flag('--show-files')] })]),
   command('fix-refs', mutates('managed source sweep'), 'mutate', [form('', { options: [flag('--show-files')] })]),

package/src/doctor.mjs

@@ -252,7 +252,7 @@ export function runDoctor(argv, config, opts = {}) {
     return;
   }
   if (argv.includes('--frontmatter-fix')) {
-    runFrontmatterFix(config, opts);
+    runFrontmatterFix(config, { ...opts, files: argv.filter(arg => !arg.startsWith('-')) });
     return;
   }
   if (argv.includes('--transactions')) {

package/src/extractors.mjs

@@ -81,7 +81,7 @@ export function extractBodyLinks(body) {
 }
 
 export function extractChecklistCounts(body) {
-  const matches = [...body.matchAll(/^\s*[-*]\s+\[([ xX])\]\s+/gm)];
+  const matches = [...body.matchAll(/^\s*[-*]\s+\[([ xX~])\]\s+/gm)];
   let completed = 0;
   let open = 0;
 

package/src/filing-categories.mjs

@@ -0,0 +1,54 @@
+// Condense cycles before propagating outer categories through local hub indexes.
+export function resolveHubCategories(hubs, rows) {
+  const next = new Map(hubs.map(hub => [hub, new Set()]));
+  const prev = new Map(hubs.map(hub => [hub, new Set()]));
+  for (const child of hubs) for (const row of rows.get(child) ?? []) {
+    if (!next.has(row.hub)) continue;
+    next.get(row.hub).add(child);
+    prev.get(child).add(row.hub);
+  }
+  const seen = new Set(), order = [];
+  for (const hub of hubs) {
+    if (seen.has(hub)) continue;
+    seen.add(hub);
+    const stack = [[hub, next.get(hub).values()]];
+    while (stack.length) {
+      const [node, children] = stack.at(-1), child = children.next();
+      if (child.done) { order.push(node); stack.pop(); }
+      else if (!seen.has(child.value)) {
+        seen.add(child.value);
+        stack.push([child.value, next.get(child.value).values()]);
+      }
+    }
+  }
+  const component = new Map(), groups = [];
+  for (const hub of order.reverse()) {
+    if (component.has(hub)) continue;
+    const id = groups.length, stack = [hub];
+    groups.push({ categories: new Set(), fallback: new Set(), children: new Map(), incoming: 0 });
+    component.set(hub, id);
+    while (stack.length) for (const parent of prev.get(stack.pop())) {
+      if (!component.has(parent)) { component.set(parent, id); stack.push(parent); }
+    }
+  }
+  for (const child of hubs) for (const row of rows.get(child) ?? []) {
+    if (!component.has(row.hub)) continue;
+    const from = component.get(row.hub), to = component.get(child);
+    if (from === to) { if (row.category) groups[to].fallback.add(row.category); continue; }
+    if (!groups[from].children.has(to)) {
+      groups[from].children.set(to, new Set());
+      groups[to].incoming++;
+    }
+    if (row.category) groups[from].children.get(to).add(row.category);
+  }
+  const queue = groups.flatMap((group, id) => group.incoming === 0 ? [id] : []);
+  for (let i = 0; i < queue.length; i++) {
+    const group = groups[queue[i]];
+    if (!group.categories.size) for (const label of group.fallback) group.categories.add(label);
+    for (const [child, labels] of group.children) {
+      for (const label of group.categories.size ? group.categories : labels) groups[child].categories.add(label);
+      if (--groups[child].incoming === 0) queue.push(child);
+    }
+  }
+  return new Map(hubs.map(hub => [hub, groups[component.get(hub)].categories]));
+}

package/src/filing.mjs

@@ -1,3 +1,4 @@
+import { resolveHubCategories } from './filing-categories.mjs';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter } from './frontmatter.mjs';
@@ -167,26 +168,8 @@ export function assembleFilingCoverage(docs, config, preparedRows, parentTargets
 
   // Explicit first-cell hub index rows pass categories to the hub's plan rows,
   // including indexes without status columns. Hub titles are not guessed.
-  const hubCategories = new Map();
   const liveHubs = docs.filter(doc => isHubDoc(doc) && !closed(doc, config));
-  for (const hub of liveHubs) hubCategories.set(hub.path, new Set());
-  const dependents = new Map();
-  const queue = [];
-  const addCategory = (hub, category) => {
-    const categories = hubCategories.get(hub);
-    if (categories && !categories.has(category)) { categories.add(category); queue.push([hub, category]); }
-  };
-  for (const hub of liveHubs) for (const row of categoryRows.get(hub.path) ?? []) {
-    if (row.category) addCategory(hub.path, row.category);
-    else {
-      if (!dependents.has(row.hub)) dependents.set(row.hub, new Set());
-      dependents.get(row.hub).add(hub.path);
-    }
-  }
-  for (let i = 0; i < queue.length; i++) {
-    const [hub, category] = queue[i];
-    for (const dependent of dependents.get(hub) ?? []) addCategory(dependent, category);
-  }
+  const hubCategories = resolveHubCategories(liveHubs.map(hub => hub.path), categoryRows);
   for (const rows of homes.values()) {
     // Metadata reads can finish in any order. Keep CLI/GUI evidence and home
     // pagination stable by source path and physical line, retaining duplicates.

package/src/frontmatter-fix.mjs

@@ -1,9 +1,8 @@
-import { readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, escapeRegex, warn } from './util.mjs';
-import { collectDocFiles } from './index.mjs';
+import { resolveRepairSources, publishRepairs } from './repair-sources.mjs';
 import { bold, green, dim } from './color.mjs';
-import { authorizeManagedSweep } from './managed-path.mjs';
 
 // Caps must stay in lockstep with the warnings emitted by validatePlanShape in
 // src/validate.mjs — that's where the user first sees these numbers. Targets
@@ -16,8 +15,8 @@ const FIELDS = [
 
 export function runFrontmatterFix(config, opts = {}) {
   const { dryRun, out = process.stdout } = opts;
-  const allFiles = collectDocFiles(config);
-  authorizeManagedSweep(allFiles, config, { kind: 'Frontmatter fix source' });
+  const allFiles = resolveRepairSources(opts.files ?? [], config);
+  const repairs = [];
   const results = [];
 
   for (const filePath of allFiles) {
@@ -52,13 +51,16 @@ export function runFrontmatterFix(config, opts = {}) {
       newBody = insertOrAppendSection(newBody, op.heading, op.tail);
     }
 
-    if (!dryRun) {
-      writeFileSync(filePath, `---\n${newFm}\n---\n${newBody}`, 'utf8');
-      try { config.hooks.onLint?.({ path: toRepoPath(filePath, config.repoRoot), fixes: ops.map(o => ({ field: o.field, type: 'frontmatter-fix' })) }); } catch (err) { warn(`Hook 'onLint' threw: ${err.message}`); }
-    }
+    repairs.push({ path: filePath, expectedContent: raw, content: `---\n${newFm}\n---\n${newBody}` });
     results.push({ filePath, repoPath: toRepoPath(filePath, config.repoRoot), ops });
   }
 
+  publishRepairs(repairs, config, opts);
+  if (!dryRun) for (const result of results) {
+    try { config.hooks.onLint?.({ path: result.repoPath, fixes: result.ops.map(op => ({ field: op.field, type: 'frontmatter-fix' })) }); }
+    catch (err) { warn(`Hook 'onLint' threw: ${err.message}`); }
+  }
+
   const prefix = dryRun ? dim('[dry-run] ') : '';
   const banner = dryRun ? dim(' [preview — run without --dry-run to write]') : '';
   out.write(bold('runlist doctor --frontmatter-fix') + banner + '\n\n');

package/src/index.mjs

@@ -335,12 +335,14 @@ export function parseDocFile(filePath, config, opts = {}) {
   if (text && text.shipsMetadataVersion !== 1) text = null;
   // Validation reads the body itself, so only a fast build can skip the read.
   let body = null;
+  let bodyLineOffset = 0;
   let rawSource = null;
   if (!text || !fast) {
     const raw = opts.source ?? readFileSync(filePath, 'utf8');
     rawSource = raw;
     const extracted = extractFrontmatter(raw);
     body = extracted.body;
+    bodyLineOffset = extracted.bodyLineOffset;
     // A file rewritten between the stat and the read no longer matches its stamp.
     if (text && Buffer.byteLength(raw) !== stampSize(stamp)) text = null;
     if (!text) {
@@ -471,7 +473,7 @@ export function parseDocFile(filePath, config, opts = {}) {
       return doc;
     }
     validateDoc(doc, parsedFrontmatter, headingTitle, config);
-    validatePlanShape(doc, body, parsedFrontmatter, config);
+    validatePlanShape(doc, body, parsedFrontmatter, config, bodyLineOffset);
     validateDocShape(doc, body, parsedFrontmatter, config);
   }
   return doc;

package/src/lint.mjs

@@ -1,12 +1,13 @@
-import { readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, escapeRegex, warn } from './util.mjs';
-import { buildIndex, collectDocFiles } from './index.mjs';
-import { updateFrontmatter } from './lifecycle.mjs';
+import { buildIndex } from './index.mjs';
+import { resolveRepairSources, publishRepairs } from './repair-sources.mjs';
+import { renderLifecycleMutation } from './lifecycle.mjs';
 import { runModel } from './ai.mjs';
 import { bold, green, yellow, dim } from './color.mjs';
-import { authorizeManagedSweep, findLexicalDocsRoot } from './managed-path.mjs';
+import { findLexicalDocsRoot } from './managed-path.mjs';
 
 const KEY_RENAMES = {
   nextStep: 'next_step',
@@ -69,7 +70,8 @@ function formatYamlScalar(value) {
 export function runLint(argv, config, opts = {}) {
   const { dryRun } = opts;
   const fix = argv.includes('--fix');
-  const allFiles = collectDocFiles(config);
+  const allFiles = resolveRepairSources(argv.filter(arg => !arg.startsWith('-')), config);
+  const selectedPaths = new Set(allFiles.map(file => toRepoPath(file, config.repoRoot)));
   const fixable = [];
 
   for (const filePath of allFiles) {
@@ -164,7 +166,7 @@ export function runLint(argv, config, opts = {}) {
     }
 
     if (fixes.length > 0) {
-      fixable.push({ filePath, repoPath, fixes });
+      fixable.push({ filePath, repoPath, fixes, source: raw });
     }
   }
 
@@ -187,6 +189,7 @@ export function runLint(argv, config, opts = {}) {
       }
     }
     nonFixable = [...index.errors, ...index.warnings].filter(issue => {
+      if (!selectedPaths.has(issue.path)) return false;
       if (issue.message.includes('Missing frontmatter `status`') && fixablePaths.has(issue.path)) return false;
       const dep = issue.message.match(/^`(module|surface):` \(singular\) is deprecated/);
       if (dep && fixableSingularKeys.has(`${issue.path}::${dep[1]}`)) return false;
@@ -235,11 +238,12 @@ export function runLint(argv, config, opts = {}) {
   }
 
   // Fix mode
-  authorizeManagedSweep(fixable.map(item => item.filePath), config, { kind: 'Lint fix source' });
+  const repairs = [];
   const prefix = dryRun ? dim('[dry-run] ') : '';
   let totalFixes = 0;
 
-  for (const { filePath, repoPath, fixes } of fixable) {
+  for (const { filePath, repoPath, fixes, source } of fixable) {
+    let raw = source;
     const updates = {};
     const keyRenames = [];
     let needsEofFix = false;
@@ -258,101 +262,94 @@ export function runLint(argv, config, opts = {}) {
         singularToPlural.push(f);
       } else if (f.type === 'drop-singular') {
         dropSingular.push(f);
-      } else {
+      } else if (f.type !== 'infer-status') {
         updates[f.field] = f.newValue;
       }
     }
 
-    if (!dryRun) {
-      // Apply infer-status fixes via AI
-      for (const f of fixes.filter(f => f.type === 'infer-status')) {
-        const raw = readFileSync(filePath, 'utf8');
-        const { frontmatter: fmInfer } = extractFrontmatter(raw);
-        const parsedInfer = parseSimpleFrontmatter(fmInfer);
-        const inferType = asString(parsedInfer.type);
-        const inferTypeSet = inferType ? config.typeStatuses?.get(inferType) : null;
-        const statusList = inferTypeSet ? [...inferTypeSet].join(', ') : config.statusOrder.join(', ');
-        const { body } = extractFrontmatter(raw);
-        const prompt = `Given this markdown document, classify it into exactly one of these statuses: ${statusList}.\nReply with ONLY the status word, nothing else.\n\nFile: ${repoPath}\n\n${(body ?? '').slice(0, 4000)}`;
-        const result = runModel(prompt, { maxTokens: 10 });
-        const suggested = result?.trim().toLowerCase().split(/\s+/)[0];
-        const inferValid = inferTypeSet ?? config.validStatuses;
-        if (suggested && inferValid.has(suggested)) {
-          updateFrontmatter(filePath, { status: suggested });
-          f.newValue = suggested;
-        }
+    // Apply infer-status fixes via AI
+    for (const f of dryRun ? [] : fixes.filter(f => f.type === 'infer-status')) {
+      const { frontmatter: fmInfer } = extractFrontmatter(raw);
+      const parsedInfer = parseSimpleFrontmatter(fmInfer);
+      const inferType = asString(parsedInfer.type);
+      const inferTypeSet = inferType ? config.typeStatuses?.get(inferType) : null;
+      const statusList = inferTypeSet ? [...inferTypeSet].join(', ') : config.statusOrder.join(', ');
+      const { body } = extractFrontmatter(raw);
+      const prompt = `Given this markdown document, classify it into exactly one of these statuses: ${statusList}.\nReply with ONLY the status word, nothing else.\n\nFile: ${repoPath}\n\n${(body ?? '').slice(0, 4000)}`;
+      const result = runModel(prompt, { maxTokens: 10 });
+      const suggested = result?.trim().toLowerCase().split(/\s+/)[0];
+      const inferValid = inferTypeSet ?? config.validStatuses;
+      if (suggested && inferValid.has(suggested)) {
+        updates.status = suggested;
+        f.newValue = suggested;
       }
+    }
 
-      // Apply singular-to-plural fixes (module/surface → modules/surfaces array).
-      // Removes the singular key block; merges its value(s) into the plural array,
-      // or creates the plural block if absent. Duplicates are skipped.
-      for (const sa of singularToPlural) {
-        let raw = readFileSync(filePath, 'utf8');
-        const { frontmatter: fm } = extractFrontmatter(raw);
-        const parsedFm = parseSimpleFrontmatter(fm);
-        const pluralValue = parsedFm[sa.pluralKey];
-        const existing = Array.isArray(pluralValue)
-          ? pluralValue.filter(value => typeof value === 'string' && value.trim())
-          : asString(pluralValue) ? [asString(pluralValue)] : [];
-        const merged = [...new Set([...sa.newValue, ...existing])];
-        const comments = [...frontmatterFieldComments(fm, sa.field), ...frontmatterFieldComments(fm, sa.pluralKey)];
-        let newFm = replaceFrontmatterFieldBlock(fm, sa.field);
-        const pluralLines = [sa.pluralKey + ':', ...comments.map(comment => `  ${comment}`), ...merged.map(v => `  - ${formatYamlScalar(v)}`)];
-        const pluralBlock = pluralLines.join('\n');
-        if (Object.prototype.hasOwnProperty.call(parsedFm, sa.pluralKey)) {
-          newFm = replaceFrontmatterFieldBlock(newFm, sa.pluralKey, pluralBlock);
-        } else {
-          newFm = `${newFm.trim()}\n${pluralBlock}`;
-        }
-        raw = replaceFrontmatter(raw, newFm.trim());
-        writeFileSync(filePath, raw, 'utf8');
+    // Apply singular-to-plural fixes (module/surface → modules/surfaces array).
+    // Removes the singular key block; merges its value(s) into the plural array,
+    // or creates the plural block if absent. Duplicates are skipped.
+    for (const sa of singularToPlural) {
+      const { frontmatter: fm } = extractFrontmatter(raw);
+      const parsedFm = parseSimpleFrontmatter(fm);
+      const pluralValue = parsedFm[sa.pluralKey];
+      const existing = Array.isArray(pluralValue)
+        ? pluralValue.filter(value => typeof value === 'string' && value.trim())
+        : asString(pluralValue) ? [asString(pluralValue)] : [];
+      const merged = [...new Set([...sa.newValue, ...existing])];
+      const comments = [...frontmatterFieldComments(fm, sa.field), ...frontmatterFieldComments(fm, sa.pluralKey)];
+      let newFm = replaceFrontmatterFieldBlock(fm, sa.field);
+      const pluralLines = [sa.pluralKey + ':', ...comments.map(comment => `  ${comment}`), ...merged.map(v => `  - ${formatYamlScalar(v)}`)];
+      const pluralBlock = pluralLines.join('\n');
+      if (Object.prototype.hasOwnProperty.call(parsedFm, sa.pluralKey)) {
+        newFm = replaceFrontmatterFieldBlock(newFm, sa.pluralKey, pluralBlock);
+      } else {
+        newFm = `${newFm.trim()}\n${pluralBlock}`;
       }
+      raw = replaceFrontmatter(raw, newFm.trim());
+    }
 
-      // Drop empty deprecated singular keys. The value is known-empty (the fix
-      // is only emitted for `[]`/`''`), so this matches the bare `key:` line
-      // exactly — never a line carrying content — and removes it.
-      for (const ds of dropSingular) {
-        let raw = readFileSync(filePath, 'utf8');
-        const { frontmatter: fm } = extractFrontmatter(raw);
-        const comments = frontmatterFieldComments(fm, ds.field);
-        const newFm = replaceFrontmatterFieldBlock(fm, ds.field, comments.join('\n'));
-        raw = replaceFrontmatter(raw, newFm.trim());
-        writeFileSync(filePath, raw, 'utf8');
-      }
+    // Drop empty deprecated singular keys. The value is known-empty (the fix
+    // is only emitted for `[]`/`''`), so this matches the bare `key:` line
+    // exactly — never a line carrying content — and removes it.
+    for (const ds of dropSingular) {
+      const { frontmatter: fm } = extractFrontmatter(raw);
+      const comments = frontmatterFieldComments(fm, ds.field);
+      const newFm = replaceFrontmatterFieldBlock(fm, ds.field, comments.join('\n'));
+      raw = replaceFrontmatter(raw, newFm.trim());
+    }
 
-      // Apply key renames and trim fixes via raw string manipulation
-      if (keyRenames.length > 0 || trimFixes.length > 0) {
-        let raw = readFileSync(filePath, 'utf8');
-        const { frontmatter: fm } = extractFrontmatter(raw);
-        let newFm = fm;
-        for (const kr of keyRenames) {
-          const regex = new RegExp(`^${escapeRegex(kr.oldValue)}:`, 'm');
-          newFm = newFm.replace(regex, `${kr.newValue}:`);
-        }
-        for (const tf of trimFixes) {
-          const regex = new RegExp(`^(${escapeRegex(tf.field)}:)${escapeRegex(tf.oldValue)}$`, 'm');
-          newFm = newFm.replace(regex, `$1${tf.newValue}`);
-        }
-        if (newFm !== fm) {
-          raw = replaceFrontmatter(raw, newFm);
-          writeFileSync(filePath, raw, 'utf8');
-        }
+    // Apply key renames and trim fixes via raw string manipulation
+    if (keyRenames.length > 0 || trimFixes.length > 0) {
+      const { frontmatter: fm } = extractFrontmatter(raw);
+      let newFm = fm;
+      for (const kr of keyRenames) {
+        const regex = new RegExp(`^${escapeRegex(kr.oldValue)}:`, 'm');
+        newFm = newFm.replace(regex, `${kr.newValue}:`);
       }
-
-      // Apply value updates via updateFrontmatter
-      if (Object.keys(updates).length > 0) {
-        updateFrontmatter(filePath, updates);
+      for (const tf of trimFixes) {
+        const regex = new RegExp(`^(${escapeRegex(tf.field)}:)${escapeRegex(tf.oldValue)}$`, 'm');
+        newFm = newFm.replace(regex, `$1${tf.newValue}`);
       }
-
-      // EOF fix
-      if (needsEofFix) {
-        const current = readFileSync(filePath, 'utf8');
-        if (!current.endsWith('\n')) {
-          writeFileSync(filePath, current + '\n', 'utf8');
-        }
+      if (newFm !== fm) {
+        raw = replaceFrontmatter(raw, newFm);
       }
     }
 
+    // Apply value updates to the prepared source
+    if (Object.keys(updates).length > 0) {
+      raw = renderLifecycleMutation(raw, updates, null);
+    }
+
+    // EOF fix
+    if (needsEofFix) {
+      if (!raw.endsWith('\n')) raw += '\n';
+    }
+
+    repairs.push({ path: filePath, expectedContent: source, content: raw });
+  }
+  publishRepairs(repairs, config, opts);
+
+  for (const { repoPath, fixes } of fixable) {
     process.stdout.write(`${prefix}${green('Fixed')}: ${repoPath} (${fixes.length} issue${fixes.length > 1 ? 's' : ''})\n`);
     for (const f of fixes) {
       if (f.type === 'rename-key') {

package/src/parse-cache.mjs

@@ -17,7 +17,7 @@ import { readEnv, stateDir } from './naming.mjs';
 // a missing, unreadable or foreign-version file is treated as empty, a failed
 // write is dropped, and `RUNLIST_NO_PARSE_CACHE=1` turns it off.
 
-const SCHEMA = 1;
+const SCHEMA = 2;
 const FILE_NAME = 'parse-cache';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const VERSION = (() => {

package/src/repair-sources.mjs

@@ -0,0 +1,23 @@
+import { collectDocFiles, resolveDocArg } from './index.mjs';
+import { authorizeManagedSweep } from './managed-path.mjs';
+import { assertPlanMutationAuthorized, ownershipPathFor, availableSessionId } from './pickup.mjs';
+import { mutateFileSet } from './atomic-mutation.mjs';
+
+export function resolveRepairSources(inputs, config) {
+  const files = inputs.length ? [...new Set(inputs.map(input => resolveDocArg(input, config)))] : collectDocFiles(config);
+  authorizeManagedSweep(files, config, { kind: 'Repair source' });
+  return files;
+}
+
+export function publishRepairs(repairs, config, opts = {}) {
+  const changed = repairs.filter(item => item.content !== item.expectedContent);
+  const guards = changed.map(item => {
+    const ownership = assertPlanMutationAuthorized(item.path, config, { sessionId: availableSessionId() });
+    return ownership ? { path: ownership.recordPath, expectedContent: ownership.raw }
+      : { path: ownershipPathFor(item.path, config), absent: true };
+  });
+  if (opts.dryRun || !changed.length) return;
+  mutateFileSet({ updates: changed.map(item => ({ path: item.path,
+    expectedContent: item.expectedContent, render: () => item.content })), guards },
+  { repoRoot: config.repoRoot, testHooks: opts.testHooks });
+}

package/src/section.mjs

@@ -73,7 +73,7 @@ export function findSection(sections, name) {
 const GLYPH_PATTERNS = [
   { kind: 'shipped',     re: /(✅|☑|✔|✓)/ },
   { kind: 'skipped',     re: /(⏭)/ },
-  { kind: 'in-progress', re: /(🟡|🔄)/ },
+  { kind: 'in-progress', re: /(🟡|🟨|🔄)/ },
   { kind: 'blocked',     re: /(🚧|🔴)/ },
   { kind: 'todo',        re: /(⬜|⬛|◻|☐)/ },
 ];
@@ -115,7 +115,7 @@ export function detectMarker(heading) {
 // and the space, is not \s, and ends the run — so a heading led by the
 // emoji-presentation form was not a phase heading at all, while the bare
 // codepoint was. Reported by the owner, 2026-08-16.
-const PHASE_DECORATION = String.raw`[\s>*_~\`#-]*(?:[✅🚧⬜🟡⏭☑✔✓◻☐⬛🔴🔄][︎️]?\s*)*`;
+const PHASE_DECORATION = String.raw`[\s>*_~\`#-]*(?:[✅🚧⬜🟡🟨⏭☑✔✓◻☐⬛🔴🔄][︎️]?\s*)*`;
 const PHASE_LEAD = new RegExp(`^${PHASE_DECORATION}phase\\b`, 'i');
 const FILES_MANIFEST_ANCESTOR = new RegExp(`^${PHASE_DECORATION}files\\b`, 'i');
 
@@ -154,12 +154,28 @@ const PHASE_COMPOUND_COMMENTARY = new RegExp(
   'i',
 );
 
+// Dated execution receipts describe an attempt or acceptance record, not a work phase.
+const PHASE_DATED_RECEIPT = new RegExp(
+  `^${PHASE_DECORATION}phase\\s+\\S+\\s+` +
+  `(?:execution|completed[- ]work\\s+record|personal\\s+billing\\s+acceptance|portal\\s+attempt|` +
+  `receipts?|state|verification|build|shaping\\s+walk)` +
+  `\\s*,\\s*(?:closed\\s+)?(?:[A-Z][a-z]+\\s+\\d{1,2},\\s+\\d{4}|\\d{4}-\\d{2}-\\d{2})\\b`,
+  'i',
+);
+
+const PHASE_RECORDED_MECHANICS = new RegExp(
+  `^${PHASE_DECORATION}phase\\s+\\S+\\s+mechanics\\s*,\\s*recorded\\b`,
+  'i',
+);
+
 export function isPhaseHeading(section) {
   if (section.level !== 3) return false;
   if (FILES_MANIFEST_ANCESTOR.test(section.h2Ancestor ?? '')) return false;
   return PHASE_LEAD.test(section.heading)
     && !PHASE_COMMENTARY.test(section.heading)
-    && !PHASE_COMPOUND_COMMENTARY.test(section.heading);
+    && !PHASE_COMPOUND_COMMENTARY.test(section.heading)
+    && !PHASE_DATED_RECEIPT.test(section.heading)
+    && !PHASE_RECORDED_MECHANICS.test(section.heading);
 }
 
 // A phase's OWN checklist — the boxes directly under its heading, stopping at
@@ -170,7 +186,7 @@ export function phaseTally(section) {
   for (const line of String(section?.body ?? '').split('\n')) {
     if (/^#{1,6}\s/.test(line)) break;
     if (/^\s*[-*]\s*\[x\]/i.test(line)) checked++;
-    else if (/^\s*[-*]\s*\[ \]/.test(line)) unchecked++;
+    else if (/^\s*[-*]\s*\[[ ~]\]/.test(line)) unchecked++;
   }
   return { checked, unchecked, total: checked + unchecked };
 }

package/src/validate.mjs

@@ -626,7 +626,7 @@ export function checkGitStaleness(docs, config, options = {}) {
 
 // Plan-shape lint: soft warnings on convention drift. Plan-only.
 // Body is the unparsed plan body (everything after the closing `---`).
-export function validatePlanShape(doc, body, frontmatter, config) {
+export function validatePlanShape(doc, body, frontmatter, config, bodyLineOffset = 0) {
   if (doc.type !== 'plan') return;
   // Skip plans in terminal/archive statuses (closed work shouldn't generate noise)
   if (config.lifecycle.terminalStatuses.has(doc.status) || config.lifecycle.archiveStatuses.has(doc.status)) return;
@@ -707,7 +707,7 @@ export function validatePlanShape(doc, body, frontmatter, config) {
     doc.warnings.push({
       path: doc.path,
       level: 'warning',
-      message: `Phase marker contradicts its own checklist (line ${phase.lineStart}): \`${phase.heading.trim()}\` is marked ${conflict.declared}, but ${conflict.checked}/${conflict.total} boxes are checked — that reads as ${conflict.implied}. Update whichever half is stale.`,
+      message: `Phase marker contradicts its own checklist (line ${bodyLineOffset + phase.lineStart}): \`${phase.heading.trim()}\` is marked ${conflict.declared}, but ${conflict.checked}/${conflict.total} boxes are checked — that reads as ${conflict.implied}. Update whichever half is stale.`,
     });
   }
 }