@geraldmaron/construct 1.0.21 → 1.0.24

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,169 @@
+/**
+ * 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';
+
+export const RECONCILIATIONS = [
+  legacySkillsCleanup,
+  gitignoreCoverage,
+  agentInstructionsRewrap,
+  legacyDoctrineStrip,
+  legacyGuideDecommit,
+  mcpEntryReconcile,
+  adapterPrune,
+];
+
+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,
+};