@geraldmaron/construct 1.0.20 → 1.0.23

package/lib/project-init-shared.mjs

@@ -25,179 +25,6 @@ export function writeStampedIfMissing({ targetRoot, created, skipped, filePath,
   return true;
 }
 
-export function buildAgentsGuide(projectName) {
-  return `<!--
-AGENTS.md — canonical operating contract for AI agents working in this repository.
-
-Generated by \`construct init\`. Keep this file concise, current, and pruned:
-- update it when workflow rules, tracker hierarchy, or required tools change
-- remove stale sections instead of preserving historical guidance here
-- avoid duplicating deeper docs when a canonical source already exists elsewhere
--->
-
-# ${projectName} Agent Guide
-
-## Operating hierarchy
-
-- Use Beads (\`bd\`) as the canonical durable tracker. All non-trivial work must have a Beads issue before implementation begins.
-- Use \`plan.md\` as the human-readable implementation plan tied to the active Beads issue set.
-- Use cass-memory through the MCP \`memory\` server for cross-session and cross-tool recall, not for task tracking.
-
-## Start-of-session rules
-
-- Read \`AGENTS.md\`, \`plan.md\`, \`.cx/context.md\`, and any canonical docs that exist before planning or coding.
-- Treat \`construct up\` as runtime hydration only. If services are unavailable, resume from durable state: \`plan.md\`, \`.cx/context.md\`, the latest \`.cx/handoffs/\` file, Beads, docs, and git.
-- Run \`bd ready\` to see unblocked work available to claim.
-- Run \`bd show <id>\` for the active issue to see its full context, dependencies, and notes.
-- Check \`.cx/handoffs/\` for the most recent handoff — if another session was active, read the latest handoff to understand what was in progress.
-- Carry tracker ids into plans, workflow entries, handoffs, and verification notes.
-- Use the single-writer rule: if two agent or harness sessions would touch the same file, one session owns the edit and the other reviews, researches, or waits for handoff.
-
-## Maintenance rules
-
-- Update \`plan.md\`, \`.cx/context.md\`, and \`.cx/context.json\` when work changes project reality.
-- Do not rely on dashboard chat history, running services, or an agent session as the source of truth. Persist recovery context in repo files, Beads, docs, and git before ending work.
-- Prune stale sections from managed docs as soon as they stop matching the repo.
-- Prefer updating an existing canonical file over creating a new top-level markdown file.
-
-## End-of-session rules
-
-- Before calling work done, update \`plan.md\` to reflect completed tasks: mark items \`done\`, add new phases or rows for work that was not previously tracked, and remove or correct rows that no longer match reality.
-- Session-level todo lists (OpenCode, Claude Code, etc.) are ephemeral. Any task that represents a durable change to the project must be reflected in \`plan.md\` before the session closes — not just in the todo tracker.
-- Write a handoff to \`.cx/handoffs/{date}-{slug}.md\` covering: current state, recent decisions, next actions, risks, do-not-touch files, and which Beads issue id(s) were in scope. Use \`bd note <id>\` to attach a summary to the tracker issue.
-- Do not close a session with a working-tree change that has no corresponding \`plan.md\` entry or Beads issue.
-- Check CI status after every push. Do not call work complete if CI is failing — either fix the failure or explicitly flag it as a known infrastructure issue (e.g. billing, secrets) that is outside the scope of the change.
-- Wait for CI to reach a terminal state (success or failure) before declaring done. "Queued" or "in progress" is not done. Run \`gh run list --limit 3\` and confirm the relevant workflow shows \`completed success\`.
-
-## Parallel agent coordination
-
-- **Embedded dolt lock contention**: Parallel \`bd\` commands fail because beads uses an embedded dolt database with a single writer lock. Always serialize beads operations.
-- **Use \`construct beads\`**: Instead of direct \`bd\` commands, use \`construct beads <command>\` for lock‑aware serialized execution.
-- **Merge‑slot coordination**: For batch operations like \`bd dolt push\` that need exclusive database access, check \`construct‑6uo\` (Merge slot coordination bead) using \`bd merge-slot check/acquire/release\`.
-- **Lock visibility**: Run \`construct beads status\` to see who holds the lock, pending queue, and stale lock cleanup.
-- **Queueing**: If lock is held, requests are queued in \`.beads/queue.jsonl\` and processed FIFO.
-- **Stale lock cleanup**: Run \`construct beads cleanup\` to remove locks from dead processes.
-
-### New workflow for beads operations
-
-1. **Check status**: \`construct beads status\` (or \`construct beads status --json\`)
-2. **Run commands**: \`construct beads ready\`, \`construct beads show construct-xxx\`, \`construct beads update construct-xxx --claim\`
-3. **Clean up**: \`construct beads cleanup\` if operations are stuck
-4. **View queue**: \`construct beads queue\` to see pending requests
-5. **Batch operations**: Before \`bd dolt push\`, check merge‑slot availability
-
-## Documentation System
-
-### README.md Maintenance
-- Update README.md when architecture changes
-- README.md must reflect current project capabilities  
-- Documentation updates belong in same PR as code changes
-- README.md should link to AGENTS.md, plan.md, and docs/
-
-### Documentation Quality Gates  
-- Run \`construct docs:verify\` before calling work complete
-- CI will fail if critical docs are missing or stale
-- Documentation drift must be addressed within one sprint
-
-### Documentation Lifecycle
-- Use \`construct init --docs-preset=product\` to establish documentation lanes
-- ADRs for architectural decisions, RFCs for proposals, PRDs for products
-- Documentation should be linked to beads issues in plan.md
-
-### Update Mechanism  
-- Run \`construct init:update\` quarterly to adopt new standards
-- Check \`.cx/context.json\` version matches current template
-- Review and apply migration scripts when prompted
-
-## CI Enforcement
-
-### Documentation Validation
-- \`construct docs:verify\` runs on every PR
-- Missing README.md, AGENTS.md, or plan.md fails CI
-- Stale plan.md (>7 days) or .cx/context.md (>7 days) fails CI
-- README.md missing basic sections warns but doesn't fail
-
-### Quality Gates
-- All local tests must pass before pushing
-- CI must be green after pushing
-- Documentation validation must pass
-- Comment policy must be enforced
-
-## Verification rules
-
-- Record verification evidence in the Beads issue (\`bd note <id>\`) or \`plan.md\`, or the relevant durable doc before calling work done.
-- If architecture, contracts, or operating rules change, update the relevant canonical docs in the same change.
-- All local tests must pass (\`npm test\`) before pushing. CI must be green after pushing before the task is considered done.
-- Push Beads changes alongside code: \`bd dolt push\` must succeed before the session closes.
-
-<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:placeholder -->
-## Beads Issue Tracker
-
-This project uses **bd (beads)** for issue tracking. Run \`bd prime\` to see full workflow context and commands.
-
-### Quick Reference
-
-\`\`\`bash
-bd ready              # Find available work
-bd show <id>          # View issue details  
-bd update <id> --claim  # Claim work
-bd close <id>         # Complete work
-
-# New: lock‑aware execution
-construct beads ready        # Run bd ready with lock management
-construct beads status       # Show lock and queue status
-construct beads cleanup      # Remove stale locks
-construct beads queue        # Show pending requests
-\`\`\`
-
-### Rules
-
-- Use \`bd\` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
-- **IMPORTANT**: For parallel agent safety, prefer \`construct beads <command>\` over direct \`bd\` calls
-- Run \`bd prime\` for detailed command reference and session close protocol
-- Use \`bd remember\` for persistent knowledge — do NOT use MEMORY.md files
-- Acquire the merge slot (\`bd merge-slot acquire\`) before batch operations like \`bd dolt push\`
-- **Beads hygiene is a project contract.** Read \`rules/common/beads-hygiene.md\` once per session — it defines when to claim, close, supersede, and prune beads. Stale tracker state is treated as broken work.
-
-## Session Completion
-
-**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until \`git push\` succeeds.
-
-**MANDATORY WORKFLOW:**
-
-1. **File issues for remaining work** - Create issues for anything that needs follow-up
-2. **Run quality gates** (if code changed) - Tests, linters, builds
-3. **Update issue status** - Close finished work, update in-progress items
-4. **PUSH TO REMOTE** - This is MANDATORY:
-   \`\`\`bash
-   git pull --rebase
-   # Check merge‑slot before dolt push
-   construct beads dolt push
-   git push
-   git status  # MUST show "up to date with origin"
-   \`\`\`
-5. **Run end‑of‑session automation**:
-   \`\`\`bash
-   # Sync plan.md with bead statuses
-   node -e "import('./lib/beads-automation.mjs').then(m => m.syncPlanWithBeads({ cwd: process.cwd() }))"
-   
-   # Create handoff
-   node -e "import('./lib/beads-automation.mjs').then(m => m.endOfSessionHook({ actor: process.env.USER, cwd: process.cwd() }))"
-   \`\`\`
-6. **Clean up** - Clear stashes, prune remote branches
-7. **Verify** - All changes committed AND pushed
-8. **Hand off** - Provide context for next session
-
-**CRITICAL RULES:**
-- Work is NOT complete until \`git push\` succeeds
-- NEVER stop before pushing - that leaves work stranded locally
-- NEVER say "ready to push when you are" - YOU must push
-- If push fails, resolve and retry until it succeeds
-- ALWAYS use \`construct beads\` for beads operations in multi‑agent sessions
-- Clean up stale locks with \`construct beads cleanup\` if operations hang
-<!-- END BEADS INTEGRATION -->`;
-}
-
 export function buildPlanTemplate() {
   return `<!--
 plan.md — current implementation plan for this repository.

package/lib/reconcile/adapter-prune.mjs

@@ -0,0 +1,105 @@
+/**
+ * lib/reconcile/adapter-prune.mjs — report and remove adapter directories for
+ * hosts not installed on this machine (ADR-0027 §1).
+ *
+ * `construct sync` writes adapter sets for the hosts it detects. A project
+ * synced where more hosts were installed, then opened on a leaner machine,
+ * carries adapter dirs for hosts absent from the current machine. Each adapter
+ * dir is sync-regenerated machine-specific state, so pruning the dirs for
+ * undetected hosts is safe — a later sync recreates whatever the current
+ * machine actually has.
+ *
+ * `.claude` stays untouched: it is the baseline set that VS Code reads
+ * natively, so its presence carries no implication about Claude Code. `.github`
+ * (Copilot prompts / instructions) is out of scope entirely.
+ *
+ * Safety: `ask`. Deleting generated directories runs only on explicit consent
+ * (`construct sync --reconcile=adapter-prune`), and the auto runner skips ask
+ * tasks. detect() reads only; apply() is idempotent because a removed dir drops
+ * out of the present set.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { ADAPTER_DIRS } from '../host-disposition.mjs';
+import { detectHostCapabilities } from '../host-capabilities.mjs';
+
+const HOST_TO_DIR = {
+  'Claude Code': '.claude',
+  OpenCode: '.opencode',
+  Codex: '.codex',
+  'VS Code': '.vscode',
+  Cursor: '.cursor',
+};
+
+const PROTECTED_DIRS = new Set(['.claude']);
+
+function isConstructProject(dir) {
+  return fs.existsSync(path.join(dir, '.cx')) || fs.existsSync(path.join(dir, '.construct'));
+}
+
+function detectedDirSet() {
+  const dirs = new Set();
+  for (const host of detectHostCapabilities()) {
+    if (host.availability !== 'installed') continue;
+    const dir = HOST_TO_DIR[host.host];
+    if (dir) dirs.add(dir);
+  }
+  return dirs;
+}
+
+// A candidate is a present adapter dir whose host is not installed, excluding
+// the protected baseline `.claude` that VS Code consumes natively.
+
+function prunableDirs(projectDir) {
+  const detected = detectedDirSet();
+  const out = [];
+  for (const dir of ADAPTER_DIRS) {
+    if (PROTECTED_DIRS.has(dir)) continue;
+    if (detected.has(dir)) continue;
+    if (fs.existsSync(path.join(projectDir, dir))) out.push(dir);
+  }
+  return out;
+}
+
+async function detect() {
+  const dir = process.cwd();
+  if (!isConstructProject(dir)) {
+    return { needsRepair: false, summary: 'Not a Construct project directory.' };
+  }
+  const prunable = prunableDirs(dir);
+  if (prunable.length === 0) {
+    return { needsRepair: false, summary: 'No adapter directories for uninstalled hosts.' };
+  }
+  return {
+    needsRepair: true,
+    summary: `${prunable.length} adapter director${prunable.length === 1 ? 'y' : 'ies'} for uninstalled hosts: ${prunable.join(', ')}.`,
+    details: { prunable },
+  };
+}
+
+async function apply() {
+  const dir = process.cwd();
+  const prunable = prunableDirs(dir);
+  const removed = [];
+  for (const adapter of prunable) {
+    const full = path.join(dir, adapter);
+    try {
+      fs.rmSync(full, { recursive: true, force: true });
+      removed.push(adapter);
+    } catch {
+      continue;
+    }
+  }
+  if (removed.length === 0) return { summary: 'Nothing to prune.' };
+  return { summary: `Removed ${removed.length} adapter director${removed.length === 1 ? 'y' : 'ies'} for uninstalled hosts: ${removed.join(', ')}.` };
+}
+
+export default {
+  id: 'adapter-prune',
+  description: 'Remove adapter directories for hosts not installed on this machine (never .claude or .github).',
+  safety: 'ask',
+  detect,
+  apply,
+};

package/lib/reconcile/agent-instructions-rewrap.mjs

@@ -0,0 +1,98 @@
+/**
+ * lib/reconcile/agent-instructions-rewrap.mjs — keep the CONSTRUCT INTEGRATION
+ * block current inside existing AGENTS.md / CLAUDE.md files (ADR-0027 §2).
+ *
+ * The integration block is versioned and hash-stamped. A changed managed body
+ * or version leaves files written by an earlier init carrying a stale block.
+ * Re-injection rewrites the current block into files that already contain one,
+ * replacing only the marker region and preserving every byte outside it.
+ *
+ * Scope is deliberately narrow: a file is touched only when it EXISTS in cwd
+ * and already carries a CONSTRUCT INTEGRATION marker. Files without a block are
+ * left for init to create — backward-repair never authors a block into a file
+ * the user never opted into. Safety: `auto`. detect() reads only; apply() is
+ * idempotent because injectIntoAgentFile returns `unchanged` once the stamp
+ * matches.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  injectIntoAgentFile,
+  injectConstructBlock,
+  buildConstructIntegrationBody,
+  CONSTRUCT_INTEGRATION_VERSION,
+} from '../agent-instructions/inject.mjs';
+
+const AGENT_FILES = ['AGENTS.md', 'CLAUDE.md'];
+const BEGIN_MARKER = '<!-- BEGIN CONSTRUCT INTEGRATION';
+const BEADS_BLOCK_RE = /<!-- BEGIN BEADS INTEGRATION/;
+
+function hasIntegrationBlock(content) {
+  return content.includes(BEGIN_MARKER);
+}
+
+// Re-injection that would change the file maps to a stale block. The body
+// dedups against a sibling Beads block, so the comparison rebuilds the body
+// the same way injectIntoAgentFile does before hashing.
+
+function wouldChange(content) {
+  const body = buildConstructIntegrationBody({ hasBeadsBlock: BEADS_BLOCK_RE.test(content) });
+  const { action } = injectConstructBlock(content, body, CONSTRUCT_INTEGRATION_VERSION);
+  return action !== 'unchanged';
+}
+
+function candidateFiles() {
+  const dir = process.cwd();
+  const out = [];
+  for (const name of AGENT_FILES) {
+    const full = path.join(dir, name);
+    if (!fs.existsSync(full)) continue;
+    let content = '';
+    try {
+      content = fs.readFileSync(full, 'utf8');
+    } catch {
+      continue;
+    }
+    if (!hasIntegrationBlock(content)) continue;
+    out.push({ name, full, content });
+  }
+  return out;
+}
+
+async function detect() {
+  const candidates = candidateFiles();
+  if (candidates.length === 0) {
+    return { needsRepair: false, summary: 'No agent file carries a CONSTRUCT INTEGRATION block.' };
+  }
+  const stale = candidates.filter((c) => wouldChange(c.content)).map((c) => c.name);
+  if (stale.length === 0) {
+    return { needsRepair: false, summary: 'CONSTRUCT INTEGRATION blocks are current.' };
+  }
+  return {
+    needsRepair: true,
+    summary: `Stale CONSTRUCT INTEGRATION block in ${stale.join(', ')}.`,
+    details: { stale },
+  };
+}
+
+async function apply() {
+  const candidates = candidateFiles();
+  const rewrapped = [];
+  for (const c of candidates) {
+    if (!wouldChange(c.content)) continue;
+    const result = injectIntoAgentFile(c.full, { version: CONSTRUCT_INTEGRATION_VERSION });
+    if (result.changed) rewrapped.push(c.name);
+  }
+  if (rewrapped.length === 0) return { summary: 'Already current.' };
+  return { summary: `Rewrapped CONSTRUCT INTEGRATION block in ${rewrapped.join(', ')}.` };
+}
+
+export default {
+  id: 'agent-instructions-rewrap',
+  description: 'Refresh stale CONSTRUCT INTEGRATION blocks in existing AGENTS.md / CLAUDE.md files.',
+  safety: 'auto',
+  detect,
+  apply,
+};

package/lib/reconcile/gitignore-coverage.mjs

@@ -0,0 +1,88 @@
+/**
+ * lib/reconcile/gitignore-coverage.mjs — repair a project `.gitignore` that
+ * predates the full Construct ignore set (ADR-0027 §1).
+ *
+ * The init writer seeds every machine-specific, sync-regenerated artifact into
+ * `.gitignore` so adapter dirs, the launcher, and runtime state never enter
+ * source control. A project initialized before a pattern was added carries a
+ * partial set; this task appends the missing patterns under the same comment
+ * header the init writer uses, leaving all user-authored lines untouched.
+ *
+ * Scope: a Construct project directory (cwd has `.cx/` or `.construct/`) that
+ * already has a `.gitignore`. Absent either, there is nothing to repair — init
+ * owns creation. Safety: `auto`. detect() reads only; apply() appends and is
+ * idempotent because missingIgnorePatterns() drains to empty once the patterns
+ * are present.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { missingIgnorePatterns, isConstructPackageRepo } from '../host-disposition.mjs';
+
+const HEADER = '# Construct — generated adapters, launcher, and runtime state.';
+const SUBHEADER = '# Machine-specific, recreated by `construct sync`; never source (ADR-0027).';
+
+function isConstructProject(dir) {
+  return fs.existsSync(path.join(dir, '.cx')) || fs.existsSync(path.join(dir, '.construct'));
+}
+
+function gitignorePath(dir) {
+  return path.join(dir, '.gitignore');
+}
+
+async function detect() {
+  const dir = process.cwd();
+  if (!isConstructProject(dir)) {
+    return { needsRepair: false, summary: 'Not a Construct project directory.' };
+  }
+  if (isConstructPackageRepo(dir)) {
+    return { needsRepair: false, summary: 'Construct package repo — .construct/ holds shipped templates, not a staged launcher.' };
+  }
+  const giPath = gitignorePath(dir);
+  if (!fs.existsSync(giPath)) {
+    return { needsRepair: false, summary: 'No .gitignore present (init owns creation).' };
+  }
+  let content = '';
+  try {
+    content = fs.readFileSync(giPath, 'utf8');
+  } catch (err) {
+    return { needsRepair: false, summary: `Could not read .gitignore: ${err.message}` };
+  }
+  const missing = missingIgnorePatterns(content);
+  if (missing.length === 0) {
+    return { needsRepair: false, summary: '.gitignore covers the full Construct ignore set.' };
+  }
+  return {
+    needsRepair: true,
+    summary: `${missing.length} Construct ignore pattern${missing.length === 1 ? '' : 's'} missing from .gitignore.`,
+    details: { missing },
+  };
+}
+
+async function apply() {
+  const dir = process.cwd();
+  const giPath = gitignorePath(dir);
+  if (!fs.existsSync(giPath)) return { summary: 'No .gitignore to repair.' };
+  const existing = fs.readFileSync(giPath, 'utf8');
+  const missing = missingIgnorePatterns(existing);
+  if (missing.length === 0) return { summary: 'Already covered.' };
+
+  // Mirror the init writer's separator and header so forward-fix and
+  // backward-repair produce byte-identical blocks.
+
+  const prefix = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+  const block = `${prefix}\n${HEADER}\n${SUBHEADER}\n${missing.join('\n')}\n`;
+  fs.writeFileSync(giPath, existing + block, 'utf8');
+  return {
+    summary: `Appended ${missing.length} Construct ignore pattern${missing.length === 1 ? '' : 's'} to .gitignore.`,
+  };
+}
+
+export default {
+  id: 'gitignore-coverage',
+  description: 'Append missing Construct ignore patterns to a project .gitignore that predates the full set.',
+  safety: 'auto',
+  detect,
+  apply,
+};

package/lib/reconcile/index.mjs

@@ -0,0 +1,171 @@
+/**
+ * lib/reconcile/index.mjs — registry of state-reconciliation tasks that
+ * bring on-disk state in line with the expected disposition contract
+ * (ADR-0027). Separate from lib/migrations/ (artifact-JSON schema
+ * versioning) and lib/storage/migrations.mjs (Postgres schema).
+ *
+ * Each task declares: id (kebab), description (one line), safety
+ * (`auto` = run silently from `construct sync` when detect() reports
+ * needsRepair; `ask` = surfaced by `construct doctor` and runs only on
+ * explicit `construct sync --reconcile=<id>`), detect() (async, cheap,
+ * side-effect-free, returns { needsRepair, summary, ... }), and apply()
+ * (async, idempotent, returns { summary }).
+ *
+ * Two invariants every task must hold:
+ *   1. Never touch a user-authored file without consent — `safety: 'ask'`
+ *      gates anything that could remove user edits, and detect() must
+ *      exclude paths whose mtime suggests user interaction.
+ *   2. Calling detect() after apply() must return needsRepair: false on
+ *      the same input. A task that would loop is a detection bug — the
+ *      stamp file is a hint and a record, not a correctness guard.
+ *
+ * Stamps land at ~/.construct/reconcile.json so the dashboard and doctor
+ * can show what's been applied; loss of the file does not break apply()
+ * (apply() stays idempotent on its own).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { constructDir } from '../paths.mjs';
+import legacySkillsCleanup from './legacy-skills-cleanup.mjs';
+import gitignoreCoverage from './gitignore-coverage.mjs';
+import agentInstructionsRewrap from './agent-instructions-rewrap.mjs';
+import legacyDoctrineStrip from './legacy-doctrine-strip.mjs';
+import legacyGuideDecommit from './legacy-guide-decommit.mjs';
+import mcpEntryReconcile from './mcp-entry-reconcile.mjs';
+import adapterPrune from './adapter-prune.mjs';
+import postgresNamespace from './postgres-namespace.mjs';
+
+export const RECONCILIATIONS = [
+  legacySkillsCleanup,
+  gitignoreCoverage,
+  agentInstructionsRewrap,
+  legacyDoctrineStrip,
+  legacyGuideDecommit,
+  mcpEntryReconcile,
+  adapterPrune,
+  postgresNamespace,
+];
+
+const STAMP_FILE = 'reconcile.json';
+
+function stampPath() {
+  return path.join(constructDir(), STAMP_FILE);
+}
+
+function readStamps() {
+  try {
+    const raw = fs.readFileSync(stampPath(), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' && parsed.applied
+      ? parsed
+      : { applied: {} };
+  } catch {
+    return { applied: {} };
+  }
+}
+
+function writeStamp(id, summary) {
+  const stamps = readStamps();
+  stamps.applied[id] = { at: new Date().toISOString(), summary };
+  try {
+    fs.mkdirSync(path.dirname(stampPath()), { recursive: true });
+    fs.writeFileSync(stampPath(), JSON.stringify(stamps, null, 2));
+  } catch {
+    // Stamp failure is non-fatal — apply() must be idempotent so a missing
+    // stamp just means the next detect() catches the same state again.
+  }
+}
+
+async function safeDetect(task) {
+  try {
+    const result = await task.detect();
+    return result && typeof result === 'object'
+      ? { needsRepair: !!result.needsRepair, summary: result.summary || null, details: result.details || null }
+      : { needsRepair: false, summary: null, details: null };
+  } catch (err) {
+    return { needsRepair: false, summary: null, details: null, error: err.message };
+  }
+}
+
+export async function listReconciliations() {
+  const stamps = readStamps();
+  const out = [];
+  for (const task of RECONCILIATIONS) {
+    const detected = await safeDetect(task);
+    out.push({
+      id: task.id,
+      description: task.description,
+      safety: task.safety,
+      needsRepair: detected.needsRepair,
+      summary: detected.summary,
+      details: detected.details,
+      error: detected.error || null,
+      previouslyApplied: !!stamps.applied[task.id],
+      appliedAt: stamps.applied[task.id]?.at || null,
+    });
+  }
+  return out;
+}
+
+export async function runAutoReconciliations({ dryRun = false, verbose = false, logger = console } = {}) {
+  const applied = [];
+  const skipped = [];
+  for (const task of RECONCILIATIONS) {
+    if (task.safety !== 'auto') {
+      skipped.push({ id: task.id, reason: 'safety:ask' });
+      continue;
+    }
+    const detected = await safeDetect(task);
+    if (detected.error) {
+      skipped.push({ id: task.id, reason: `detect-error:${detected.error}` });
+      continue;
+    }
+    if (!detected.needsRepair) {
+      skipped.push({ id: task.id, reason: 'no-op' });
+      continue;
+    }
+    if (dryRun) {
+      applied.push({ id: task.id, summary: detected.summary, dryRun: true });
+      if (verbose && logger?.log) logger.log(`[reconcile:${task.id}] would apply: ${detected.summary}`);
+      continue;
+    }
+    try {
+      const result = await task.apply();
+      const summary = result?.summary || detected.summary || '';
+      writeStamp(task.id, summary);
+      applied.push({ id: task.id, summary });
+      if (verbose && logger?.log) logger.log(`[reconcile:${task.id}] ${summary}`);
+    } catch (err) {
+      skipped.push({ id: task.id, reason: `apply-error:${err.message}` });
+      if (verbose && logger?.error) logger.error(`[reconcile:${task.id}] failed: ${err.message}`);
+    }
+  }
+  return { applied, skipped };
+}
+
+export async function runReconciliation(id, { dryRun = false } = {}) {
+  const task = RECONCILIATIONS.find((x) => x.id === id);
+  if (!task) {
+    return { ok: false, reason: `Unknown reconciliation: ${id}`, available: RECONCILIATIONS.map((x) => x.id) };
+  }
+  const detected = await safeDetect(task);
+  if (detected.error) return { ok: false, reason: `detect-error:${detected.error}` };
+  if (!detected.needsRepair) {
+    return { ok: true, ran: false, reason: 'no-op', summary: detected.summary || 'Nothing to reconcile.' };
+  }
+  if (dryRun) return { ok: true, ran: false, dryRun: true, summary: detected.summary };
+  try {
+    const result = await task.apply();
+    const summary = result?.summary || detected.summary || '';
+    writeStamp(id, summary);
+    return { ok: true, ran: true, summary };
+  } catch (err) {
+    return { ok: false, ran: false, reason: `apply-error:${err.message}` };
+  }
+}
+
+export function reconcileStampPath() {
+  return stampPath();
+}