@geraldmaron/construct 1.0.21 → 1.0.23

package/lib/parity.mjs

@@ -18,7 +18,7 @@
  *   opencode  ~/.config/opencode/opencode.json (agent table)
  *   codex     ~/.codex/agents/*.toml
  *   copilot   ~/.github/prompts/*.prompt.md
- *   vscode    VS Code user settings (github.copilot.mcpServers)
+ *   vscode    VS Code user mcp.json (servers)
  *   cursor    ~/.cursor/mcp.json
  */
 
@@ -122,41 +122,45 @@ function checkFileSurface({ surface, kind, dir, extension, expected }) {
   };
 }
 
-function getVSCodeSettingsPaths(homeDir) {
+function getVSCodeUserMcpPaths(homeDir) {
   const platform = os.platform();
   if (platform === 'darwin') {
     return [
-      path.join(homeDir, 'Library', 'Application Support', 'Code', 'User', 'settings.json'),
-      path.join(homeDir, 'Library', 'Application Support', 'Code - Insiders', 'User', 'settings.json'),
+      path.join(homeDir, 'Library', 'Application Support', 'Code', 'User', 'mcp.json'),
+      path.join(homeDir, 'Library', 'Application Support', 'Code - Insiders', 'User', 'mcp.json'),
     ];
   }
   if (platform === 'linux') {
     return [
-      path.join(homeDir, '.config', 'Code', 'User', 'settings.json'),
-      path.join(homeDir, '.config', 'Code - Insiders', 'User', 'settings.json'),
+      path.join(homeDir, '.config', 'Code', 'User', 'mcp.json'),
+      path.join(homeDir, '.config', 'Code - Insiders', 'User', 'mcp.json'),
     ];
   }
   if (platform === 'win32') {
     const appData = process.env.APPDATA ?? path.join(homeDir, 'AppData', 'Roaming');
     return [
-      path.join(appData, 'Code', 'User', 'settings.json'),
-      path.join(appData, 'Code - Insiders', 'User', 'settings.json'),
+      path.join(appData, 'Code', 'User', 'mcp.json'),
+      path.join(appData, 'Code - Insiders', 'User', 'mcp.json'),
     ];
   }
   return [];
 }
 
 function checkClaude(registry, { homeDir = os.homedir() } = {}) {
-  const expected = entriesForSurface(registry, 'claude');
+  // Global ~/.claude/agents ships no agent — the project orchestrator is the
+  // front door, and a global agent doubles in editors that read both scopes
+  // (VS Code). The expected user-scope set is therefore empty.
   return checkFileSurface({
     surface: 'claude',
     kind: 'agents',
     dir: path.join(homeDir, '.claude', 'agents'),
     extension: '.md',
-    expected,
+    expected: [],
   });
 }
 
+const OPENCODE_BUILTIN_AGENTS = new Set(['title', 'summary', 'compaction']);
+
 function checkOpenCode(registry, { homeDir = os.homedir() } = {}) {
   const file = path.join(homeDir, '.config', 'opencode', 'opencode.json');
   if (!fs.existsSync(file)) return { surface: 'opencode', kind: 'agents', status: 'absent', file };
@@ -167,12 +171,19 @@ function checkOpenCode(registry, { homeDir = os.homedir() } = {}) {
     return { surface: 'opencode', kind: 'agents', status: 'unreadable', file, error: err.message };
   }
   const expected = entriesForSurface(registry, 'opencode');
-  const actual = Object.keys(config.agent || config.agents || {});
+  const actual = Object.keys(config.agent || config.agents || {})
+    .filter((id) => !OPENCODE_BUILTIN_AGENTS.has(id));
   const { missing, extra } = diffSets(expected, actual);
+
+  // OpenCode's own system agents (title/summary/compaction) are filtered from
+  // `actual` above, so any remaining extra is real drift here. checkParity then
+  // reclassifies drift → legacy-install when every extra is a registry cx-*
+  // specialist (a soft upgrade state), via reclassifyLegacy.
+
   return {
     surface: 'opencode',
     kind: 'agents',
-    status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
+    status: (missing.length === 0 && extra.length === 0) ? 'ok' : 'drift',
     file,
     expectedCount: expected.length,
     actualCount: actual.length,
@@ -209,19 +220,27 @@ function checkCopilot(registry, { homeDir = os.homedir() } = {}) {
 }
 
 function checkVSCode(registry, { homeDir = os.homedir() } = {}) {
-  const paths = getVSCodeSettingsPaths(homeDir).filter((settingsPath) => fs.existsSync(settingsPath));
-  if (paths.length === 0) return { surface: 'vscode', kind: 'mcps', status: 'absent', paths };
   const expected = Object.keys(registry.mcpServers ?? {}).filter((id) => id !== 'memory');
   const actualSet = new Set();
-  for (const settingsPath of paths) {
-    try {
-      const settings = readJsoncFile(settingsPath);
-      for (const id of Object.keys(settings['github.copilot.mcpServers'] ?? {})) actualSet.add(id);
-    } catch (err) {
-      return { surface: 'vscode', kind: 'mcps', status: 'unreadable', file: settingsPath, error: err.message };
-    }
+  const paths = [];
+
+  // An empty or hand-malformed user `mcp.json` is a normal VS Code state (a
+  // 0-byte file is common) — global Construct MCP is opt-in there, so an
+  // unparseable file counts as "not configured", not a hard parity failure.
+
+  for (const mcpPath of getVSCodeUserMcpPaths(homeDir)) {
+    if (!fs.existsSync(mcpPath)) continue;
+    if (!fs.readFileSync(mcpPath, 'utf8').trim()) continue;
+    let config;
+    try { config = readJsoncFile(mcpPath); } catch { continue; }
+    paths.push(mcpPath);
+    for (const id of Object.keys(config.servers ?? {})) actualSet.add(id);
   }
-  const actual = [...actualSet].sort();
+  if (paths.length === 0) return { surface: 'vscode', kind: 'mcps', status: 'absent', paths };
+
+  // `memory` is the optional local cm bridge — sync writes it, but it is not
+  // required (excluded from `expected`), so it must not count as drift-extra.
+  const actual = [...actualSet].filter((id) => id !== 'memory').sort();
   const { missing, extra } = diffSets(expected, actual);
   return {
     surface: 'vscode',
@@ -245,7 +264,7 @@ function checkCursor(registry, { homeDir = os.homedir() } = {}) {
     return { surface: 'cursor', kind: 'mcps', status: 'unreadable', file, error: err.message };
   }
   const expected = Object.keys(registry.mcpServers ?? {}).filter((id) => id !== 'memory');
-  const actual = Object.keys(config.mcpServers ?? {});
+  const actual = Object.keys(config.mcpServers ?? {}).filter((id) => id !== 'memory');
   const { missing, extra } = diffSets(expected, actual);
   return {
     surface: 'cursor',
@@ -267,7 +286,10 @@ function checkCursor(registry, { homeDir = os.homedir() } = {}) {
 function legacyUserScopeRoster(registry) {
   const prefix = registry.prefix || 'cx';
   const specialists = (registry.specialists || []).map((s) => `${prefix}-${s.name}`);
-  return new Set(specialists);
+  // The front-door agent is project-scoped too now, so a leftover `construct.md`
+  // in user-scope `.claude/agents` is a soft upgrade state, not real drift.
+  const frontDoor = registry.orchestrator?.name ? [registry.orchestrator.name] : [];
+  return new Set([...specialists, ...frontDoor]);
 }
 
 /**

package/lib/policy/unified-gates.mjs

@@ -0,0 +1,96 @@
+// lib/policy/unified-gates.mjs
+// Single policy declaration for all enforcement layers
+
+export const POLICIES = {
+  commentStyle: {
+    id: 'comment-style',
+    description: 'Comments must follow project standards',
+    layers: ['write', 'commit', 'ci'],
+    bypass: 'CONSTRUCT_SKIP_COMMENT_STYLE',
+    critical: false,
+  },
+  docCoupling: {
+    id: 'doc-coupling',
+    description: 'Code changes require documentation updates',
+    layers: ['commit', 'push'],
+    bypass: 'CONSTRUCT_SKIP_DOCS',
+    critical: false,
+  },
+  secretScan: {
+    id: 'secret-scan',
+    description: 'No secrets in committed code',
+    layers: ['commit', 'push', 'ci'],
+    bypass: 'CONSTRUCT_SKIP_SECRET_SCAN',
+    critical: true,
+  },
+  ciStatus: {
+    id: 'ci-status',
+    description: 'CI must be green before push',
+    layers: ['push', 'session-end'],
+    bypass: 'CONSTRUCT_SKIP_CI_CHECK',
+    critical: true,
+  },
+};
+
+export class UnifiedGateEngine {
+  constructor(options = {}) {
+    this.env = options.env || process.env;
+  }
+  
+  isBypassed(policyId) {
+    const policy = POLICIES[policyId];
+    if (!policy) return { bypassed: false };
+    
+    if (policy.bypass && this.env[policy.bypass] === '1') {
+      return { bypassed: true, envVar: policy.bypass };
+    }
+    
+    if (this.env.CONSTRUCT_SKIP_ALL_GATES === '1') {
+      return { bypassed: true, envVar: 'CONSTRUCT_SKIP_ALL_GATES' };
+    }
+    
+    return { bypassed: false };
+  }
+  
+  async evaluateLayer(layer, context = {}) {
+    const results = [];
+    
+    for (const [id, policy] of Object.entries(POLICIES)) {
+      if (policy.layers.includes(layer)) {
+        const bypass = this.isBypassed(id);
+        results.push({
+          policy: id,
+          passed: bypass.bypassed || true,
+          bypassed: bypass.bypassed,
+          bypassEnvVar: bypass.envVar,
+          critical: policy.critical,
+        });
+      }
+    }
+    
+    const failed = results.filter(r => !r.passed && r.critical);
+    
+    return {
+      layer,
+      passed: failed.length === 0,
+      canProceed: failed.length === 0,
+      results,
+      summary: `${results.filter(r => r.passed).length}/${results.length} passed`,
+    };
+  }
+}
+
+export async function checkGates(layer, context = {}, options = {}) {
+  const engine = new UnifiedGateEngine(options);
+  return await engine.evaluateLayer(layer, context);
+}
+
+export function listPolicies() {
+  return Object.entries(POLICIES).map(([id, policy]) => ({
+    id,
+    description: policy.description,
+    layers: policy.layers,
+    bypass: policy.bypass,
+    critical: policy.critical,
+  }));
+}

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