@geraldmaron/construct 1.0.21 → 1.0.23

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();
+}

package/lib/reconcile/legacy-doctrine-strip.mjs

@@ -0,0 +1,139 @@
+/**
+ * lib/reconcile/legacy-doctrine-strip.mjs — collapse a legacy un-fenced doctrine
+ * body in an existing AGENTS.md / CLAUDE.md down to the project header plus the
+ * marker blocks (ADR-0027 §2 backward-repair).
+ *
+ * An earlier `construct init` pre-wrote ~120 lines of generic Construct operating
+ * doctrine ABOVE the marker blocks, so a host repo carries Construct-the-tool
+ * content outside any fence — content `construct sync` cannot reconcile because
+ * the marker-only injector preserves everything outside its markers. This task
+ * removes the known doctrine sections while preserving: the project H1, any
+ * non-doctrine section the user added, and every marker block (BEADS, CONSTRUCT).
+ *
+ * Safety: `ask` — it edits a user-owned tracked file, so it never runs from the
+ * auto sync path and only applies on explicit `construct sync --reconcile=<id>`.
+ * detect() reads only; apply() is idempotent: a stripped file lacks the doctrine
+ * fingerprint, so a second detect() reports clean.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const AGENT_FILES = ['AGENTS.md', 'CLAUDE.md'];
+const CONSTRUCT_MARKER = '<!-- BEGIN CONSTRUCT INTEGRATION';
+const BEADS_MARKER = '<!-- BEGIN BEADS INTEGRATION';
+
+// The H2 sections the retired buildAgentsGuide() authored. The five core
+// headings form the fingerprint; the rest are stripped too when the head is
+// confirmed as that doctrine.
+
+const CORE_DOCTRINE_HEADINGS = [
+  'Operating hierarchy',
+  'Start-of-session rules',
+  'Maintenance rules',
+  'End-of-session rules',
+  'Verification rules',
+];
+
+const ALL_DOCTRINE_HEADINGS = new Set([
+  ...CORE_DOCTRINE_HEADINGS,
+  'Parallel agent coordination',
+  'Documentation System',
+  'CI Enforcement',
+]);
+
+function firstMarkerIndex(content) {
+  const idxs = [content.indexOf(BEADS_MARKER), content.indexOf(CONSTRUCT_MARKER)].filter((i) => i >= 0);
+  return idxs.length ? Math.min(...idxs) : -1;
+}
+
+function splitHeadTail(content) {
+  const idx = firstMarkerIndex(content);
+  if (idx < 0) return { head: content, tail: '' };
+  return { head: content.slice(0, idx), tail: content.slice(idx) };
+}
+
+function hasDoctrine(head) {
+  return CORE_DOCTRINE_HEADINGS.every((h) => head.includes(`## ${h}`));
+}
+
+function deriveProjectName(head) {
+  const guide = head.match(/^#\s+(.+?)\s+Agent Guide\s*$/m);
+  if (guide) return guide[1].trim();
+  const h1 = head.match(/^#\s+(.+?)\s*$/m);
+  if (h1) return h1[1].trim();
+  return path.basename(process.cwd());
+}
+
+// The rebuilt head is a plain project H1 followed by only the user-authored
+// sections: any section whose heading is in the doctrine set is excluded, as are
+// the generator comment and the "X Agent Guide" title.
+
+function stripDoctrineFromHead(head, projectName) {
+  const withoutFrontmatter = head.replace(/^---\n[\s\S]*?\n---\s*\n/, '');
+  const withoutComment = withoutFrontmatter.replace(/^\s*<!--[\s\S]*?-->\s*/, '');
+  const afterH1 = withoutComment.replace(/^#\s+.+?\n+/, '');
+  const sections = afterH1.split(/\n(?=## )/).map((s) => s.trim()).filter(Boolean);
+  const kept = sections.filter((section) => {
+    const title = section.match(/^##\s+(.+?)\s*$/m)?.[1]?.trim();
+    return title ? !ALL_DOCTRINE_HEADINGS.has(title) : true;
+  });
+  const body = kept.length ? `${kept.join('\n\n')}\n\n` : '';
+  return `# ${projectName}\n\n${body}`;
+}
+
+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 (!content.includes(CONSTRUCT_MARKER)) continue;
+    const { head } = splitHeadTail(content);
+    if (!hasDoctrine(head)) 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 legacy un-fenced doctrine body.' };
+  }
+  const names = candidates.map((c) => c.name);
+  return {
+    needsRepair: true,
+    summary: `Legacy un-fenced Construct doctrine in ${names.join(', ')}; collapse to the project header plus marker blocks.`,
+    details: { files: names },
+  };
+}
+
+async function apply() {
+  const candidates = candidateFiles();
+  const stripped = [];
+  for (const c of candidates) {
+    const { head, tail } = splitHeadTail(c.content);
+    const projectName = deriveProjectName(head);
+    const next = stripDoctrineFromHead(head, projectName) + tail;
+    if (next === c.content) continue;
+    fs.writeFileSync(c.full, next, 'utf8');
+    stripped.push(c.name);
+  }
+  if (stripped.length === 0) return { summary: 'No legacy doctrine to strip.' };
+  return { summary: `Stripped legacy doctrine from ${stripped.join(', ')}; user content and marker blocks preserved.` };
+}
+
+export default {
+  id: 'legacy-doctrine-strip',
+  description: 'Collapse a legacy un-fenced Construct doctrine body in AGENTS.md / CLAUDE.md to the project header plus marker blocks.',
+  safety: 'ask',
+  detect,
+  apply,
+};

package/lib/reconcile/legacy-guide-decommit.mjs

@@ -0,0 +1,67 @@
+/**
+ * lib/reconcile/legacy-guide-decommit.mjs — relocate a legacy root-level
+ * construct_guide.md into the ignored .cx/ tree (ADR-0027 §1 backward-repair).
+ *
+ * An earlier `construct init` copied the "Welcome to Construct" orientation guide
+ * to the host repo root, where it reads as project content and is git-eligible.
+ * The canonical home is `.cx/construct_guide.md` (ignored). This task ensures the
+ * content survives under .cx/ and removes the root copy; when the root copy was
+ * committed, the summary names the `git rm --cached` follow-up (the reconcile
+ * framework runs no git on the host).
+ *
+ * Safety: `ask` — editing the working tree of a possibly-committed file requires
+ * explicit consent, so the auto sync path skips this task; only
+ * `construct sync --reconcile=<id>` applies it. detect() reads only; apply() is
+ * idempotent: a moved guide leaves no root-level file for the next detect().
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ROOT_NAME = 'construct_guide.md';
+
+function paths() {
+  const dir = process.cwd();
+  return {
+    root: path.join(dir, ROOT_NAME),
+    dest: path.join(dir, '.cx', ROOT_NAME),
+  };
+}
+
+async function detect() {
+  const { root } = paths();
+  if (!fs.existsSync(root)) {
+    return { needsRepair: false, summary: 'No root-level construct_guide.md.' };
+  }
+  return {
+    needsRepair: true,
+    summary: 'Root-level construct_guide.md presents Construct tooling as project content; relocate to .cx/ (ignored).',
+    details: { path: ROOT_NAME },
+  };
+}
+
+async function apply() {
+  const { root, dest } = paths();
+  if (!fs.existsSync(root)) return { summary: 'Nothing to relocate.' };
+
+  // Preserve content under the ignored canonical home, then drop the root copy.
+  // An existing .cx/ guide is the canonical one and is left intact.
+
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (!fs.existsSync(dest)) {
+    fs.copyFileSync(root, dest);
+  }
+  fs.rmSync(root);
+
+  return {
+    summary: `Relocated ${ROOT_NAME} to .cx/${ROOT_NAME} (ignored). If it was committed, run: git rm --cached ${ROOT_NAME}`,
+  };
+}
+
+export default {
+  id: 'legacy-guide-decommit',
+  description: 'Relocate a legacy root-level construct_guide.md into the ignored .cx/ tree.',
+  safety: 'ask',
+  detect,
+  apply,
+};

package/lib/reconcile/legacy-skills-cleanup.mjs

@@ -0,0 +1,200 @@
+/**
+ * lib/reconcile/legacy-skills-cleanup.mjs — clean up SKILL.md files at
+ * ~/.agents/skills/ whose frontmatter is missing the `name` and
+ * `description` fields required by the Anthropic Agent Skills loader.
+ *
+ * The cleanup is constrained to files whose frontmatter matches the
+ * Construct doc-stamp shape (cx_doc_id + generator: construct/sync-specialists
+ * + body_hash), so non-Construct skill authors in the same tree are
+ * untouched. Empty parent directories prune upward; ~/.agents itself is
+ * removed only if Construct emptied it.
+ *
+ * Safety: `auto`. detect() is pure-read; apply() never modifies files
+ * outside the matched-stamp set and never touches files whose mtime falls
+ * after the doc-stamp timestamp recorded in the frontmatter (a signal
+ * that something other than Construct's sync may have edited the file).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { homeDir } from '../paths.mjs';
+
+const LEGACY_REL = path.join('.agents', 'skills');
+
+function legacyRoot() {
+  return path.join(homeDir(), LEGACY_REL);
+}
+
+const STAMP_RE = /^cx_doc_id:\s*\S+/m;
+const GENERATOR_RE = /^generator:\s*construct\/sync-specialists/m;
+const BODY_HASH_RE = /^body_hash:\s*sha256:/m;
+const NAME_RE = /^name:\s*\S+/m;
+const DESCRIPTION_RE = /^description:\s*\S/m;
+const UPDATED_AT_RE = /^updated_at:\s*(\S+)/m;
+
+// Frontmatter shapes the Construct sync writer has emitted. The "stale"
+// shape is doc-stamp-only (cx_doc_id + generator + body_hash, no name, no
+// description) — the Anthropic Agent Skills loader rejects it. The current
+// shape carries name + description and parses cleanly.
+
+function classifyFrontmatter(content) {
+  if (!content || !content.startsWith('---\n')) return { kind: 'no-frontmatter' };
+  const closeIdx = content.indexOf('\n---', 4);
+  if (closeIdx === -1) return { kind: 'malformed' };
+  const fm = content.slice(4, closeIdx);
+  const isConstructStamp = STAMP_RE.test(fm) && GENERATOR_RE.test(fm) && BODY_HASH_RE.test(fm);
+  const hasName = NAME_RE.test(fm);
+  const hasDescription = DESCRIPTION_RE.test(fm);
+  const updatedMatch = fm.match(UPDATED_AT_RE);
+  const updatedAtMs = updatedMatch ? Date.parse(updatedMatch[1]) : NaN;
+  if (isConstructStamp && !hasName && !hasDescription) {
+    return { kind: 'construct-stale', updatedAtMs };
+  }
+  if (isConstructStamp && hasName && hasDescription) {
+    return { kind: 'construct-current', updatedAtMs };
+  }
+  return { kind: 'foreign' };
+}
+
+function walkSkillFiles(dir) {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return out; }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walkSkillFiles(full));
+    else if (entry.isFile() && entry.name === 'SKILL.md') out.push(full);
+  }
+  return out;
+}
+
+function inspectFile(file) {
+  let content = '';
+  let stat;
+  try {
+    content = fs.readFileSync(file, 'utf8');
+    stat = fs.statSync(file);
+  } catch {
+    return { file, classification: { kind: 'unreadable' } };
+  }
+  const classification = classifyFrontmatter(content);
+  return { file, classification, mtimeMs: stat.mtimeMs };
+}
+
+// A file is safe to remove when (a) it matches the Construct stale shape,
+// (b) its mtime is within a small skew of its declared updated_at — if
+// the user edited it after Construct wrote it, mtime drifts ahead, and
+// the file is preserved.
+
+const USER_EDIT_SKEW_MS = 5 * 60 * 1000;
+
+function isSafeToRemove(inspection) {
+  const c = inspection.classification;
+  if (c.kind !== 'construct-stale') return false;
+  if (!Number.isFinite(c.updatedAtMs)) return true;
+  const drift = inspection.mtimeMs - c.updatedAtMs;
+  return drift <= USER_EDIT_SKEW_MS;
+}
+
+function pruneEmptyDirsUpward(startDir, stopDir) {
+  let cur = startDir;
+  while (cur && cur.startsWith(stopDir) && cur !== stopDir) {
+    let entries;
+    try { entries = fs.readdirSync(cur); } catch { return; }
+    if (entries.length > 0) return;
+    try { fs.rmdirSync(cur); } catch { return; }
+    cur = path.dirname(cur);
+  }
+}
+
+async function detect() {
+  const root = legacyRoot();
+  if (!fs.existsSync(root)) {
+    return { needsRepair: false, summary: 'No legacy ~/.agents/skills directory present.' };
+  }
+  const files = walkSkillFiles(root);
+  if (files.length === 0) {
+    return { needsRepair: false, summary: 'Legacy directory present but empty.' };
+  }
+  let stale = 0;
+  let staleUserEdited = 0;
+  let constructCurrent = 0;
+  let foreign = 0;
+  let unreadable = 0;
+  for (const file of files) {
+    const inspection = inspectFile(file);
+    const kind = inspection.classification.kind;
+    if (kind === 'construct-stale') {
+      if (isSafeToRemove(inspection)) stale += 1;
+      else staleUserEdited += 1;
+    } else if (kind === 'construct-current') {
+      constructCurrent += 1;
+    } else if (kind === 'foreign') {
+      foreign += 1;
+    } else {
+      unreadable += 1;
+    }
+  }
+  if (stale === 0) {
+    return {
+      needsRepair: false,
+      summary: `Legacy directory present, no Construct-shaped stale files to remove (current: ${constructCurrent}, foreign: ${foreign}, user-edited stale: ${staleUserEdited}).`,
+      details: { stale, staleUserEdited, constructCurrent, foreign, unreadable, total: files.length },
+    };
+  }
+  return {
+    needsRepair: true,
+    summary: `${stale} stale Construct SKILL.md files at ~/.agents/skills (current: ${constructCurrent}, foreign: ${foreign}, user-edited stale: ${staleUserEdited}, unreadable: ${unreadable}).`,
+    details: { stale, staleUserEdited, constructCurrent, foreign, unreadable, total: files.length },
+  };
+}
+
+async function apply() {
+  const root = legacyRoot();
+  if (!fs.existsSync(root)) return { summary: 'Already clean.' };
+  const files = walkSkillFiles(root);
+  let removed = 0;
+  let preserved = 0;
+  const dirsToCheck = new Set();
+  for (const file of files) {
+    const inspection = inspectFile(file);
+    if (!isSafeToRemove(inspection)) {
+      preserved += 1;
+      continue;
+    }
+    try {
+      fs.unlinkSync(file);
+      removed += 1;
+      dirsToCheck.add(path.dirname(file));
+    } catch {
+      preserved += 1;
+    }
+  }
+  for (const dir of [...dirsToCheck].sort((a, b) => b.length - a.length)) {
+    pruneEmptyDirsUpward(dir, root);
+  }
+  // If the root is now empty, prune it and the .agents parent if also empty.
+
+  try {
+    if (fs.readdirSync(root).length === 0) {
+      fs.rmdirSync(root);
+      const parent = path.dirname(root);
+      try {
+        if (fs.readdirSync(parent).length === 0) fs.rmdirSync(parent);
+      } catch { /* parent has unrelated content */ }
+    }
+  } catch { /* root has remaining entries */ }
+  return {
+    summary: `Removed ${removed} stale SKILL.md file${removed === 1 ? '' : 's'} from ~/.agents/skills${preserved > 0 ? ` (preserved ${preserved} with user-edit signal)` : ''}.`,
+  };
+}
+
+export default {
+  id: 'legacy-skills-cleanup',
+  description: 'Remove SKILL.md files at ~/.agents/skills whose frontmatter lacks the required name/description fields.',
+  safety: 'auto',
+  detect,
+  apply,
+};