@geraldmaron/construct 1.0.20 → 1.0.23

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,
+};

package/lib/reconcile/mcp-entry-reconcile.mjs

@@ -0,0 +1,142 @@
+/**
+ * lib/reconcile/mcp-entry-reconcile.mjs — strip Codex `[mcp_servers.<id>]`
+ * tables whose `bearer_token_env_var` references an unset env var from configs
+ * written before the sync-time fix (ADR-0027 / construct-n6h7).
+ *
+ * Codex aborts at startup when an MCP server's bearer_token_env_var names an
+ * env var that is unset. The sync writer now omits such entries, but a config
+ * written by an earlier version still carries them. This repair removes exactly
+ * those construct-managed tables from the global `~/.codex/config.toml` and a
+ * project `.codex/config.toml` when present, preserving every other table.
+ *
+ * Detection mirrors the sync-time gate (codexMcpEnvResolves): an entry whose
+ * token env var resolves is kept; only unresolved-credential tables are pruned.
+ * Tables with no credential requirement are never touched. Removal is scoped to
+ * registry-managed MCP ids by exact table name, so user-authored mcp_servers
+ * tables are out of scope. Safety: `auto`. detect() reads only; apply() is
+ * idempotent because removeTomlTables drains the matched tables to none.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { homeDir } from '../paths.mjs';
+import {
+  getCodexConfigPath,
+  buildCodexMcpEntry,
+  removeTomlTables,
+  tomlString,
+} from '../codex-config.mjs';
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function registryMcpServers() {
+  const installed = path.join(homeDir(), '.construct', 'specialists', 'registry.json');
+  const bundled = fileURLToPath(new URL('../../specialists/registry.json', import.meta.url));
+  for (const src of [installed, bundled]) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(src, 'utf8'));
+      if (parsed && parsed.mcpServers) return parsed.mcpServers;
+    } catch {
+      continue;
+    }
+  }
+  return {};
+}
+
+function hasMcpTable(text, id) {
+  return new RegExp(`^\\[mcp_servers\\.(?:${escapeRegExp(id)}|${escapeRegExp(tomlString(id))})\\]`, 'm').test(text);
+}
+
+// An entry with no bearer_token_env_var has no credential requirement and is
+// always valid. An entry whose token env var is set resolves; an unset value
+// (undefined or empty string) is the abort condition Codex hits at startup.
+
+function tokenResolves(id, def, env) {
+  const entry = buildCodexMcpEntry(id, def, env);
+  const tokenVar = entry?.bearer_token_env_var;
+  if (!tokenVar) return true;
+  const val = env[tokenVar];
+  return val !== undefined && val !== '';
+}
+
+function configTargets() {
+  const targets = [{ scope: 'global', file: getCodexConfigPath(homeDir()) }];
+  const projectConfig = path.join(process.cwd(), '.codex', 'config.toml');
+  if (fs.existsSync(projectConfig)) targets.push({ scope: 'project', file: projectConfig });
+  return targets;
+}
+
+function unresolvedTables(text, registryMcp, env) {
+  const ids = [];
+  for (const id of Object.keys(registryMcp)) {
+    if (!hasMcpTable(text, id)) continue;
+    if (tokenResolves(id, registryMcp[id], env)) continue;
+    ids.push(id);
+  }
+  return ids;
+}
+
+async function detect() {
+  const registryMcp = registryMcpServers();
+  if (Object.keys(registryMcp).length === 0) {
+    return { needsRepair: false, summary: 'No registry MCP servers to reconcile.' };
+  }
+  const env = process.env;
+  const offenders = [];
+  for (const target of configTargets()) {
+    let text = '';
+    try {
+      if (!fs.existsSync(target.file)) continue;
+      text = fs.readFileSync(target.file, 'utf8');
+    } catch {
+      continue;
+    }
+    const ids = unresolvedTables(text, registryMcp, env);
+    if (ids.length > 0) offenders.push({ ...target, ids });
+  }
+  if (offenders.length === 0) {
+    return { needsRepair: false, summary: 'No Codex MCP tables reference an unset token env var.' };
+  }
+  const total = offenders.reduce((acc, o) => acc + o.ids.length, 0);
+  return {
+    needsRepair: true,
+    summary: `${total} Codex MCP table${total === 1 ? '' : 's'} reference an unset token env var (${offenders.map((o) => `${o.scope}: ${o.ids.join(', ')}`).join('; ')}).`,
+    details: { offenders: offenders.map((o) => ({ scope: o.scope, ids: o.ids })) },
+  };
+}
+
+async function apply() {
+  const registryMcp = registryMcpServers();
+  const env = process.env;
+  let removed = 0;
+  const scopes = [];
+  for (const target of configTargets()) {
+    if (!fs.existsSync(target.file)) continue;
+    const text = fs.readFileSync(target.file, 'utf8');
+    const ids = unresolvedTables(text, registryMcp, env);
+    if (ids.length === 0) continue;
+
+    // Strip both the bare and quoted table forms per id, matching the names
+    // the sync writer emits, so a table written either way is removed.
+
+    const tableNames = ids.flatMap((id) => [`mcp_servers.${id}`, `mcp_servers.${tomlString(id)}`]);
+    const cleaned = removeTomlTables(text, tableNames);
+    fs.writeFileSync(target.file, `${cleaned.trimEnd()}\n`, 'utf8');
+    removed += ids.length;
+    scopes.push(`${target.scope}: ${ids.join(', ')}`);
+  }
+  if (removed === 0) return { summary: 'Already clean.' };
+  return { summary: `Removed ${removed} unresolved Codex MCP table${removed === 1 ? '' : 's'} (${scopes.join('; ')}).` };
+}
+
+export default {
+  id: 'mcp-entry-reconcile',
+  description: 'Strip Codex MCP tables whose bearer_token_env_var references an unset env var from existing configs.',
+  safety: 'auto',
+  detect,
+  apply,
+};

package/lib/reconcile/postgres-namespace.mjs

@@ -0,0 +1,102 @@
+/**
+ * lib/reconcile/postgres-namespace.mjs — migrate a local Postgres compose that
+ * predates per-home identifier derivation (ADR-0027 / construct-lb7b).
+ *
+ * Earlier versions wrote a singular `construct-postgres` container on the fixed
+ * 54329 port. Two isolated HOMEs sharing that container clobber each other's
+ * data and fight over the port. The derivation namespaces both per home; the
+ * repair rewrites a legacy compose file to the namespaced form.
+ *
+ * apply() is strictly data-safe: it only rewrites the compose via
+ * writeLocalPostgresCompose(home). It runs no docker command, removes no
+ * container, and deletes no volume — the existing volume and any data inside it
+ * are left intact. The returned summary instructs the operator to run
+ * `construct down && construct up` to recreate the container against the
+ * namespaced compose.
+ *
+ * Safety: `ask`. The rewrite changes the container/port a running stack binds
+ * to, so it runs only on explicit consent. detect() reads only; apply() is
+ * idempotent because the namespaced compose fails to match the legacy markers.
+ */
+
+import fs from 'node:fs';
+
+import { homeDir } from '../paths.mjs';
+import {
+  LEGACY_PG_CONTAINER,
+  LEGACY_PG_PORT,
+  postgresContainerName,
+  postgresPort,
+} from '../home-namespace.mjs';
+import { localPostgresComposePath, writeLocalPostgresCompose } from '../setup.mjs';
+
+// The container marker anchors to end-of-line so the namespaced form
+// `construct-postgres-<suffix>` does not match the singular legacy name as a
+// prefix (which would defeat idempotency).
+
+const LEGACY_CONTAINER_RE = new RegExp(`container_name:\\s*${LEGACY_PG_CONTAINER}\\s*$`, 'm');
+const LEGACY_PORT_RE = new RegExp(`:${LEGACY_PG_PORT}:`);
+
+function legacyMarkers(content, home) {
+  const derivedContainer = postgresContainerName(process.env, home);
+  const derivedPort = postgresPort(process.env, home);
+
+  // The legacy singular container only counts when the derivation would name it
+  // differently; an explicit CONSTRUCT_PG_CONTAINER override pinned to the
+  // singular name is the intended state, not drift.
+
+  const hasLegacyContainer = LEGACY_CONTAINER_RE.test(content) && derivedContainer !== LEGACY_PG_CONTAINER;
+  const hasLegacyPort = LEGACY_PORT_RE.test(content) && derivedPort !== LEGACY_PG_PORT;
+  return { hasLegacyContainer, hasLegacyPort, derivedContainer, derivedPort };
+}
+
+async function detect() {
+  const home = homeDir();
+  const composePath = localPostgresComposePath(home);
+  if (!fs.existsSync(composePath)) {
+    return { needsRepair: false, summary: 'No local Postgres compose file present.' };
+  }
+  let content = '';
+  try {
+    content = fs.readFileSync(composePath, 'utf8');
+  } catch (err) {
+    return { needsRepair: false, summary: `Could not read compose file: ${err.message}` };
+  }
+  const markers = legacyMarkers(content, home);
+  if (!markers.hasLegacyContainer && !markers.hasLegacyPort) {
+    return { needsRepair: false, summary: 'Local Postgres compose already uses per-home identifiers.' };
+  }
+  const reasons = [];
+  if (markers.hasLegacyContainer) reasons.push(`container ${LEGACY_PG_CONTAINER} → ${markers.derivedContainer}`);
+  if (markers.hasLegacyPort) reasons.push(`port ${LEGACY_PG_PORT} → ${markers.derivedPort}`);
+  return {
+    needsRepair: true,
+    summary: `Local Postgres compose predates per-home derivation (${reasons.join(', ')}).`,
+    details: { composePath, ...markers },
+  };
+}
+
+async function apply() {
+  const home = homeDir();
+  const composePath = localPostgresComposePath(home);
+  if (!fs.existsSync(composePath)) return { summary: 'No compose file to migrate.' };
+
+  // Rewrite the compose to the per-home form only. No docker invocation, no
+  // container removal, no volume deletion — the operator recreates the
+  // container themselves so data handling stays under their control.
+
+  writeLocalPostgresCompose(home);
+  const container = postgresContainerName(process.env, home);
+  const port = postgresPort(process.env, home);
+  return {
+    summary: `Rewrote local Postgres compose to per-home identifiers (container ${container}, port ${port}). Run \`construct down && construct up\` to recreate the container; existing data and volume are untouched.`,
+  };
+}
+
+export default {
+  id: 'postgres-namespace',
+  description: 'Rewrite a legacy local Postgres compose to per-home container/port identifiers (data-safe).',
+  safety: 'ask',
+  detect,
+  apply,
+};