claudex-setup 1.7.0 → 1.9.0

package/src/mcp-packs.js

@@ -0,0 +1,139 @@
+const MCP_PACKS = [
+  {
+    key: 'context7-docs',
+    label: 'Context7 Docs',
+    useWhen: 'Repos that benefit from live, current framework and library documentation during Claude sessions.',
+    adoption: 'Safe default docs pack for most application repos.',
+    servers: {
+      context7: {
+        command: 'npx',
+        args: ['-y', '@upstash/context7-mcp@latest'],
+      },
+    },
+  },
+  {
+    key: 'next-devtools',
+    label: 'Next.js Devtools',
+    useWhen: 'Next.js repos that need runtime-aware debugging and framework-specific tooling.',
+    adoption: 'Useful companion pack for frontend-ui repos running Next.js.',
+    servers: {
+      'next-devtools': {
+        command: 'npx',
+        args: ['-y', 'next-devtools-mcp@latest'],
+      },
+    },
+  },
+  {
+    key: 'github-mcp',
+    label: 'GitHub',
+    useWhen: 'Repos hosted on GitHub that benefit from issue, PR, and repository context during Claude sessions.',
+    adoption: 'Recommended for any GitHub-hosted project. Requires GITHUB_PERSONAL_ACCESS_TOKEN env var.',
+    servers: {
+      github: {
+        command: 'npx',
+        args: ['-y', '@modelcontextprotocol/server-github'],
+        env: { GITHUB_PERSONAL_ACCESS_TOKEN: '${GITHUB_PERSONAL_ACCESS_TOKEN}' },
+      },
+    },
+  },
+  {
+    key: 'postgres-mcp',
+    label: 'PostgreSQL',
+    useWhen: 'Repos with PostgreSQL databases that benefit from schema inspection and query assistance.',
+    adoption: 'Useful for backend-api and data-pipeline repos. Requires DATABASE_URL env var.',
+    servers: {
+      postgres: {
+        command: 'npx',
+        args: ['-y', '@modelcontextprotocol/server-postgres'],
+        env: { DATABASE_URL: '${DATABASE_URL}' },
+      },
+    },
+  },
+  {
+    key: 'memory-mcp',
+    label: 'Memory / Knowledge Graph',
+    useWhen: 'Long-running projects that benefit from persistent entity and relationship tracking across sessions.',
+    adoption: 'Useful for complex projects with many interconnected concepts. Stores data locally.',
+    servers: {
+      memory: {
+        command: 'npx',
+        args: ['-y', '@modelcontextprotocol/server-memory'],
+      },
+    },
+  },
+];
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function getMcpPack(key) {
+  return MCP_PACKS.find(pack => pack.key === key) || null;
+}
+
+function normalizeMcpPackKeys(keys = []) {
+  return [...new Set((Array.isArray(keys) ? keys : [])
+    .map(key => `${key}`.trim())
+    .filter(Boolean))]
+    .filter(key => !!getMcpPack(key));
+}
+
+function mergeMcpServers(existing = {}, packKeys = []) {
+  const merged = clone(existing || {});
+  for (const key of normalizeMcpPackKeys(packKeys)) {
+    const pack = getMcpPack(key);
+    if (!pack) continue;
+    for (const [serverName, serverConfig] of Object.entries(pack.servers || {})) {
+      if (!merged[serverName]) {
+        merged[serverName] = clone(serverConfig);
+      }
+    }
+  }
+  return merged;
+}
+
+function recommendMcpPacks(stacks = [], domainPacks = []) {
+  const recommended = new Set();
+  const stackKeys = new Set(stacks.map(stack => stack.key));
+
+  for (const pack of domainPacks) {
+    for (const key of pack.recommendedMcpPacks || []) {
+      recommended.add(key);
+    }
+  }
+
+  if (stackKeys.has('nextjs')) {
+    recommended.add('next-devtools');
+  }
+  if (stackKeys.size > 0) {
+    recommended.add('context7-docs');
+  }
+
+  // GitHub MCP for repos with .github directory
+  const domainKeys = new Set(domainPacks.map(p => p.key));
+  if (domainKeys.has('oss-library') || domainKeys.has('enterprise-governed')) {
+    recommended.add('github-mcp');
+  }
+
+  // Postgres MCP for data-heavy repos
+  if (domainKeys.has('data-pipeline') || domainKeys.has('backend-api')) {
+    recommended.add('postgres-mcp');
+  }
+
+  // Memory MCP for complex/monorepo projects
+  if (domainKeys.has('monorepo') || domainKeys.has('enterprise-governed')) {
+    recommended.add('memory-mcp');
+  }
+
+  return MCP_PACKS
+    .filter(pack => recommended.has(pack.key))
+    .map(pack => clone(pack));
+}
+
+module.exports = {
+  MCP_PACKS,
+  getMcpPack,
+  normalizeMcpPackKeys,
+  mergeMcpServers,
+  recommendMcpPacks,
+};

package/src/plans.js

@@ -6,6 +6,7 @@ const { analyzeProject } = require('./analyze');
 const { ProjectContext } = require('./context');
 const { TECHNIQUES, STACKS } = require('./techniques');
 const { TEMPLATES } = require('./setup');
+const { buildSettingsForProfile } = require('./governance');
 const { writeActivityArtifact, writeRollbackArtifact } = require('./activity');
 
 const TEMPLATE_DIR_MAP = {
@@ -35,6 +36,26 @@ const TEMPLATE_MODULES = {
 };
 
 const IMPACT_ORDER = { critical: 3, high: 2, medium: 1, low: 0 };
+const FALLBACK_TEMPLATE_BY_KEY = {
+  importSyntax: 'claude-md',
+  verificationLoop: 'claude-md',
+  testCommand: 'claude-md',
+  lintCommand: 'claude-md',
+  buildCommand: 'claude-md',
+  securityReview: 'claude-md',
+  compactionAwareness: 'claude-md',
+  contextManagement: 'claude-md',
+  xmlTags: 'claude-md',
+  roleDefinition: 'claude-md',
+  constraintBlocks: 'claude-md',
+  claudeMdFreshness: 'claude-md',
+  permissionDeny: 'hooks',
+  secretsProtection: 'hooks',
+  preToolUseHook: 'hooks',
+  postToolUseHook: 'hooks',
+  sessionStartHook: 'hooks',
+  agentsHaveMaxTurns: 'agents',
+};
 
 function previewContent(content) {
   return content.split('\n').slice(0, 12).join('\n');
@@ -46,73 +67,242 @@ function riskFromImpact(impact) {
   return 'low';
 }
 
+function normalizeNewlines(content) {
+  return (content || '').replace(/\r\n/g, '\n');
+}
+
+function ensureTrailingNewline(content) {
+  const normalized = normalizeNewlines(content);
+  return normalized.endsWith('\n') ? normalized : `${normalized}\n`;
+}
+
+function upsertManagedBlock(content, id, block) {
+  const start = `<!-- claudex-setup:${id}:start -->`;
+  const end = `<!-- claudex-setup:${id}:end -->`;
+  const wrapped = `${start}\n${block.trim()}\n${end}`;
+  const pattern = new RegExp(`${start}[\\s\\S]*?${end}`);
+
+  if (pattern.test(content)) {
+    return {
+      changed: true,
+      content: content.replace(pattern, wrapped),
+    };
+  }
+
+  return {
+    changed: true,
+    content: `${content.trimEnd()}\n\n${wrapped}\n`,
+  };
+}
+
+function extractGeneratedBuildSection(content) {
+  const match = content.match(/## Build & Test\n([\s\S]*?)\n\n## Working Notes/);
+  return match ? `## Build & Test\n${match[1].trim()}` : null;
+}
+
+function extractGeneratedVerificationBlock(content) {
+  const match = content.match(/<verification>\n([\s\S]*?)\n<\/verification>/);
+  return match ? `<verification>\n${match[1].trim()}\n</verification>` : null;
+}
+
+function extractGeneratedWorkingNotes(content) {
+  const match = content.match(/## Working Notes\n([\s\S]*?)\n\n<constraints>/);
+  return match ? `## Working Notes\n${match[1].trim()}` : null;
+}
+
+function extractGeneratedConstraintsBlock(content) {
+  const match = content.match(/<constraints>\n([\s\S]*?)\n<\/constraints>/);
+  return match ? `<constraints>\n${match[1].trim()}\n</constraints>` : null;
+}
+
+function extractGeneratedContextSection(content) {
+  const match = content.match(/## Context Management\n([\s\S]*?)\n\n---/);
+  return match ? `## Context Management\n${match[1].trim()}` : null;
+}
+
 function getFailedTemplateGroups(ctx, only = []) {
   const groups = new Map();
   for (const [key, technique] of Object.entries(TECHNIQUES)) {
     const passed = technique.check(ctx);
-    if (passed !== false || !technique.template) continue;
-    if (technique.template === 'mermaid') continue;
-    if (only.length > 0 && !only.includes(key) && !only.includes(technique.template)) continue;
-    if (!groups.has(technique.template)) {
-      groups.set(technique.template, []);
+    const templateKey = technique.template || FALLBACK_TEMPLATE_BY_KEY[key];
+    if (passed !== false || !templateKey) continue;
+    if (templateKey === 'mermaid') continue;
+    if (only.length > 0 && !only.includes(key) && !only.includes(templateKey)) continue;
+    if (!groups.has(templateKey)) {
+      groups.set(templateKey, []);
     }
-    groups.get(technique.template).push({ key, ...technique });
+    groups.get(templateKey).push({ key, ...technique });
   }
   return groups;
 }
 
-function buildHookSettings(ctx, plannedHookFiles) {
+function buildClaudeMdPatchFile(ctx, stacks) {
+  const claudePath = ctx.fileContent('CLAUDE.md') !== null
+    ? 'CLAUDE.md'
+    : (ctx.fileContent('.claude/CLAUDE.md') !== null ? '.claude/CLAUDE.md' : null);
+  if (!claudePath) return null;
+
+  const existing = normalizeNewlines(ctx.fileContent(claudePath));
+  const generated = TEMPLATES['claude-md'](stacks, ctx);
+  const buildSection = extractGeneratedBuildSection(generated);
+  const verificationBlock = extractGeneratedVerificationBlock(generated);
+  const workingNotes = extractGeneratedWorkingNotes(generated);
+  const constraintsBlock = extractGeneratedConstraintsBlock(generated);
+  const contextSection = extractGeneratedContextSection(generated);
+  let merged = existing;
+  let changed = false;
+
+  const hasTest = /npm test|pytest|jest|vitest|cargo test|go test|mix test|rspec/.test(merged);
+  const hasLint = /eslint|prettier|ruff|black|clippy|golangci-lint|rubocop/.test(merged);
+  const hasBuild = /npm run build|cargo build|go build|make|tsc|gradle build|mvn compile/.test(merged);
+  const hasVerification = merged.includes('<verification>');
+  const hasSecurityWorkflow = merged.toLowerCase().includes('security') || merged.includes('/security-review');
+  const hasImportGuidance = merged.includes('@import');
+  const hasRoleDefinition = /you are|your role|act as|persona|behave as/i.test(merged);
+  const hasConstraintBlock = /<constraints|<rules|<requirements|<boundaries/i.test(merged);
+  const hasCompaction = /\/compact|compaction/i.test(merged);
+  const hasContextManagement = /context.*(manage|window|limit|budget|token)/i.test(merged);
+  const modernFeatures = ['hook', 'skill', 'agent', 'subagent', 'mcp', 'worktree'];
+  const hasFreshness = modernFeatures.filter(feature => merged.toLowerCase().includes(feature)).length >= 2;
+
+  if ((!hasTest || !hasLint || !hasBuild) && buildSection) {
+    const result = upsertManagedBlock(merged, 'build-test', buildSection);
+    merged = result.content;
+    changed = true;
+  }
+
+  if (!hasRoleDefinition && workingNotes) {
+    const result = upsertManagedBlock(merged, 'working-style', workingNotes);
+    merged = result.content;
+    changed = true;
+  }
+
+  if (!hasConstraintBlock && constraintsBlock) {
+    const result = upsertManagedBlock(merged, 'constraints', constraintsBlock);
+    merged = result.content;
+    changed = true;
+  }
+
+  if (!hasVerification && verificationBlock) {
+    const result = upsertManagedBlock(merged, 'verification', verificationBlock);
+    merged = result.content;
+    changed = true;
+  }
+
+  if (!hasSecurityWorkflow) {
+    const result = upsertManagedBlock(merged, 'security-workflow', [
+      '## Security Workflow',
+      '- Run `/security-review` when touching authentication, permissions, secrets, or customer data.',
+      '- Treat secret access, shell commands, and risky file operations as review-worthy changes.',
+    ].join('\n'));
+    merged = result.content;
+    changed = true;
+  }
+
+  if (!hasImportGuidance) {
+    const result = upsertManagedBlock(merged, 'modularity', [
+      '## Modularity',
+      '- If this file grows, split it with `@import ./docs/...` so the base instructions stay concise.',
+    ].join('\n'));
+    merged = result.content;
+    changed = true;
+  }
+
+  if ((!hasCompaction || !hasContextManagement || !hasFreshness) && contextSection) {
+    const result = upsertManagedBlock(merged, 'context-management', contextSection);
+    merged = result.content;
+    changed = true;
+  }
+
+  if (!changed) {
+    return null;
+  }
+
+  return {
+    path: claudePath,
+    action: 'patch',
+    currentState: 'existing CLAUDE.md is missing recommended verification or security sections',
+    proposedState: 'append managed sections for verification, security workflow, and modularity',
+    content: ensureTrailingNewline(merged),
+  };
+}
+
+function buildAgentPatchFiles(ctx) {
+  if (!ctx.hasDir('.claude/agents')) {
+    return [];
+  }
+
+  return ctx.dirFiles('.claude/agents')
+    .filter(file => file.endsWith('.md'))
+    .map((file) => {
+      const relativePath = `.claude/agents/${file}`;
+      const content = normalizeNewlines(ctx.fileContent(relativePath) || '');
+      if (!content.startsWith('---\n') || content.includes('\nmaxTurns:')) {
+        return null;
+      }
+
+      const updated = content.replace(/^---\n([\s\S]*?)\n---/, (match, frontmatter) => `---\n${frontmatter}\nmaxTurns: 50\n---`);
+      if (updated === content) {
+        return null;
+      }
+
+      return {
+        path: relativePath,
+        action: 'patch',
+        currentState: 'existing agent is missing a maxTurns safety limit',
+        proposedState: 'add maxTurns: 50 to the agent frontmatter',
+        content: ensureTrailingNewline(updated),
+      };
+    })
+    .filter(Boolean);
+}
+
+function buildHookSettings(ctx, plannedHookFiles, options = {}) {
   const existing = ctx.hasDir('.claude/hooks')
     ? ctx.dirFiles('.claude/hooks').filter(file => file.endsWith('.sh'))
     : [];
   const hookFiles = [...new Set([...existing, ...plannedHookFiles])].sort();
-  if (hookFiles.length === 0 || ctx.fileContent('.claude/settings.json')) {
+  if (hookFiles.length === 0) {
     return null;
   }
+  const settingsPath = '.claude/settings.json';
+  const existingSettings = ctx.jsonFile(settingsPath);
+  const settings = buildSettingsForProfile({
+    profileKey: options.profile || 'safe-write',
+    hookFiles,
+    existingSettings,
+    mcpPackKeys: options.mcpPacks || [],
+  });
+  const content = `${JSON.stringify(settings, null, 2)}\n`;
+  const existingContent = existingSettings ? `${JSON.stringify(existingSettings, null, 2)}\n` : null;
 
-  const settings = {
-    permissions: {
-      defaultMode: 'acceptEdits',
-      deny: [
-        'Read(./.env*)',
-        'Read(./secrets/**)',
-        'Bash(rm -rf *)',
-        'Bash(git reset --hard *)',
-        'Bash(git checkout -- *)',
-        'Bash(git clean *)',
-        'Bash(git push --force *)',
-      ],
-    },
-    hooks: {
-      PostToolUse: [{
-        matcher: 'Write|Edit',
-        hooks: hookFiles.filter(file => file !== 'protect-secrets.sh').map(file => ({
-          type: 'command',
-          command: `bash .claude/hooks/${file}`,
-          timeout: 10,
-        })),
-      }],
-    },
-  };
-
-  if (hookFiles.includes('protect-secrets.sh')) {
-    settings.hooks.PreToolUse = [{
-      matcher: 'Read|Write|Edit',
-      hooks: [{
-        type: 'command',
-        command: 'bash .claude/hooks/protect-secrets.sh',
-        timeout: 5,
-      }],
-    }];
+  if (existingContent === content) {
+    return null;
   }
 
   return {
-    path: '.claude/settings.json',
-    content: `${JSON.stringify(settings, null, 2)}\n`,
+    path: settingsPath,
+    action: existingSettings ? 'patch' : 'create',
+    currentState: existingSettings
+      ? 'existing settings are missing selected profile protections or hook registrations'
+      : 'settings file is missing',
+    proposedState: existingSettings
+      ? `merge ${options.profile || 'safe-write'} profile protections into existing settings`
+      : `create settings for ${options.profile || 'safe-write'} profile and register hooks`,
+    content,
   };
 }
 
-function buildTemplateFiles(templateKey, stacks, ctx) {
+function buildTemplateFiles(templateKey, stacks, ctx, triggers, options = {}) {
+  const patchFiles = templateKey === 'agents' ? buildAgentPatchFiles(ctx) : [];
+
+  if (templateKey === 'claude-md') {
+    const patchFile = buildClaudeMdPatchFile(ctx, stacks);
+    if (patchFile) {
+      return [patchFile];
+    }
+  }
+
   const template = TEMPLATES[templateKey];
   if (!template) return [];
 
@@ -124,10 +314,13 @@ function buildTemplateFiles(templateKey, stacks, ctx) {
   const targetDir = TEMPLATE_DIR_MAP[templateKey];
   if (!targetDir) return [];
 
-  return Object.entries(result).map(([fileName, content]) => ({
+  const generatedFiles = Object.entries(result).map(([fileName, content]) => ({
     path: path.posix.join(targetDir.replace(/\\/g, '/'), fileName),
     content,
   }));
+
+  const patchedPaths = new Set(patchFiles.map(file => file.path));
+  return [...patchFiles, ...generatedFiles.filter(file => !patchedPaths.has(file.path))];
 }
 
 function toProposal(templateKey, triggers, templateFiles, ctx) {
@@ -139,9 +332,9 @@ function toProposal(templateKey, triggers, templateFiles, ctx) {
   const highestImpact = sortedTriggers[0]?.impact || 'medium';
   const files = templateFiles.map(file => {
     const exists = ctx.fileContent(file.path) !== null || ctx.hasDir(file.path);
-    const action = exists ? 'manual-review' : 'create';
-    const currentState = exists ? 'file already exists and will be preserved' : 'missing';
-    const proposedState = exists ? 'generated baseline available for manual merge' : 'create new file';
+    const action = file.action || (exists ? 'manual-review' : 'create');
+    const currentState = file.currentState || (exists ? 'file already exists and will be preserved' : 'missing');
+    const proposedState = file.proposedState || (exists ? 'generated baseline available for manual merge' : 'create new file');
     const diffPreview = [
       `--- ${exists ? file.path : 'missing'}`,
       `+++ ${file.path}`,
@@ -173,7 +366,7 @@ function toProposal(templateKey, triggers, templateFiles, ctx) {
     })),
     rationale: sortedTriggers.map(trigger => trigger.fix),
     files,
-    readyToApply: files.some(file => file.action === 'create'),
+    readyToApply: files.some(file => ['create', 'patch'].includes(file.action)),
   };
 }
 
@@ -185,12 +378,12 @@ async function buildProposalBundle(options) {
   const proposals = [];
 
   for (const [templateKey, triggers] of groups.entries()) {
-    const templateFiles = buildTemplateFiles(templateKey, stacks, ctx);
+    const templateFiles = buildTemplateFiles(templateKey, stacks, ctx, triggers, options);
     if (templateKey === 'hooks') {
       const plannedHookFiles = templateFiles
         .map(file => path.basename(file.path))
         .filter(file => file.endsWith('.sh'));
-      const settingsFile = buildHookSettings(ctx, plannedHookFiles);
+      const settingsFile = buildHookSettings(ctx, plannedHookFiles, options);
       if (settingsFile) {
         templateFiles.push(settingsFile);
       }
@@ -256,11 +449,75 @@ function writePlanFile(bundle, outFile) {
   });
 }
 
+function tryParseJson(content) {
+  try {
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function applyRuntimeSettingsOverlays(bundle, options) {
+  if (!bundle || !Array.isArray(bundle.proposals)) {
+    return bundle;
+  }
+
+  const ctx = new ProjectContext(options.dir);
+  const existingHooks = ctx.hasDir('.claude/hooks')
+    ? ctx.dirFiles('.claude/hooks').filter(file => file.endsWith('.sh'))
+    : [];
+
+  const proposals = bundle.proposals.map((proposal) => {
+    const settingsIndex = proposal.files.findIndex(file => file.path === '.claude/settings.json');
+    if (settingsIndex === -1) {
+      return proposal;
+    }
+
+    const plannedHookFiles = proposal.files
+      .filter(file => file.path.startsWith('.claude/hooks/') && file.path.endsWith('.sh'))
+      .map(file => path.basename(file.path));
+    const hookFiles = [...new Set([...existingHooks, ...plannedHookFiles])].sort();
+    const currentSettings = tryParseJson(proposal.files[settingsIndex].content) || ctx.jsonFile('.claude/settings.json') || null;
+    const mergedSettings = buildSettingsForProfile({
+      profileKey: options.profile || 'safe-write',
+      hookFiles,
+      existingSettings: currentSettings,
+      mcpPackKeys: options.mcpPacks || [],
+    });
+    const updatedContent = `${JSON.stringify(mergedSettings, null, 2)}\n`;
+    const currentFile = proposal.files[settingsIndex];
+
+    const files = [...proposal.files];
+    files[settingsIndex] = {
+      ...currentFile,
+      content: updatedContent,
+      preview: previewContent(updatedContent),
+      diffPreview: [
+        `--- ${ctx.fileContent(currentFile.path) !== null ? currentFile.path : 'missing'}`,
+        `+++ ${currentFile.path}`,
+        ...previewContent(updatedContent).split('\n').map(line => `+${line}`),
+      ].join('\n'),
+      currentState: currentFile.currentState || 'existing settings are missing runtime-selected protections or MCP packs',
+      proposedState: `merge ${options.profile || 'safe-write'} profile protections and requested MCP packs into settings`,
+    };
+
+    return {
+      ...proposal,
+      files,
+    };
+  });
+
+  return {
+    ...bundle,
+    proposals,
+  };
+}
+
 function resolvePlan(bundle, options) {
   if (options.planFile) {
-    return JSON.parse(fs.readFileSync(options.planFile, 'utf8'));
+    return applyRuntimeSettingsOverlays(JSON.parse(fs.readFileSync(options.planFile, 'utf8')), options);
   }
-  return bundle;
+  return applyRuntimeSettingsOverlays(bundle, options);
 }
 
 async function applyProposalBundle(options) {
@@ -275,38 +532,49 @@ async function applyProposalBundle(options) {
   });
 
   const createdFiles = [];
+  const patchedFiles = [];
   const skippedFiles = [];
   for (const proposal of selected) {
     for (const file of proposal.files) {
-      if (file.action !== 'create') {
+      if (!['create', 'patch'].includes(file.action)) {
         skippedFiles.push(file.path);
         continue;
       }
       const fullPath = path.join(options.dir, file.path);
-      if (fs.existsSync(fullPath)) {
+      if (file.action === 'create' && fs.existsSync(fullPath)) {
         skippedFiles.push(file.path);
         continue;
       }
+      const previousContent = fs.existsSync(fullPath) ? fs.readFileSync(fullPath, 'utf8') : null;
       if (!options.dryRun) {
         fs.mkdirSync(path.dirname(fullPath), { recursive: true });
         fs.writeFileSync(fullPath, file.content, 'utf8');
       }
-      createdFiles.push(file.path);
+      if (file.action === 'create') {
+        createdFiles.push(file.path);
+      } else {
+        patchedFiles.push({ path: file.path, previousContent });
+      }
     }
   }
 
   let rollback = null;
   let activity = null;
-  if (!options.dryRun && createdFiles.length > 0) {
+  if (!options.dryRun && (createdFiles.length > 0 || patchedFiles.length > 0)) {
     rollback = writeRollbackArtifact(options.dir, {
       sourcePlan: options.planFile ? path.basename(options.planFile) : 'live-plan',
       createdFiles,
-      rollbackInstructions: createdFiles.map(file => `Delete ${file}`),
+      patchedFiles,
+      rollbackInstructions: [
+        ...createdFiles.map(file => `Delete ${file}`),
+        ...patchedFiles.map(file => `Restore previous content for ${file.path} from this manifest`),
+      ],
     });
     activity = writeActivityArtifact(options.dir, 'apply', {
       sourcePlan: options.planFile ? path.basename(options.planFile) : 'live-plan',
       appliedProposalIds: selected.map(item => item.id),
       createdFiles,
+      patchedFiles: patchedFiles.map(file => file.path),
       skippedFiles,
       rollbackArtifact: rollback.relativePath,
     });
@@ -316,6 +584,7 @@ async function applyProposalBundle(options) {
     proposalCount: bundle.proposals.length,
     appliedProposalIds: selected.map(item => item.id),
     createdFiles,
+    patchedFiles: patchedFiles.map(file => file.path),
     skippedFiles,
     dryRun: options.dryRun === true,
     rollbackArtifact: rollback ? rollback.relativePath : null,
@@ -337,6 +606,7 @@ function printApplyResult(result, options = {}) {
   }
   console.log(`  Applied proposal bundles: ${result.appliedProposalIds.join(', ') || 'none'}`);
   console.log(`  Created files: ${result.createdFiles.join(', ') || 'none'}`);
+  console.log(`  Patched files: ${result.patchedFiles.join(', ') || 'none'}`);
   if (result.rollbackArtifact) {
     console.log(`  Rollback: ${result.rollbackArtifact}`);
   }