claudex-setup 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [1.9.0] - 2026-03-31
+
+### Added
+- 3 new domain packs: `monorepo`, `mobile`, `regulated-lite` (7→10 total)
+- 3 new MCP packs: `github-mcp`, `postgres-mcp`, `memory-mcp` (2→5 total)
+- smart MCP pack recommendation based on detected domain packs
+- `suggest-only --out report.md` exports full analysis as shareable markdown
+- `why` explanations for all strengths preserved (20+ specific reasons)
+- `why` explanations for all gap findings (12+ specific reasons)
+- 5 new hooks in governance registry: duplicate-id-check, injection-defense, trust-drift-check, session-init, protect-catalog
+- case study template in `content/case-study-template.md`
+- hook risk level display in governance output (color-coded low/medium/high)
+
+### Fixed
+- **Settings hierarchy bug**: `noBypassPermissions` and `secretsProtection` checks now correctly read `.claude/settings.json` before `.claude/settings.local.json`, so personal maintainer overrides no longer fail the shared audit
+- domain pack detection now handles monorepo (nx.json, turbo.json, lerna.json, workspaces), mobile (React Native, Flutter, iOS/Android dirs), and regulated repos (SECURITY.md, compliance dirs)
+
+### Changed
+- strengths preserved section now shows 8 items (was 6) with specific value explanations
+- claudex-sync.json updated with domain pack, MCP pack, and anti-pattern counts
+
 ## [1.8.0] - 2026-03-31
 
 ### Added

package/README.md

@@ -227,7 +227,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: DnaFin/claudex-setup@v1.8.0
+      - uses: DnaFin/claudex-setup@v1.9.0
         with:
           threshold: 50
 ```

package/bin/cli.js

@@ -2,7 +2,7 @@
 
 const { audit } = require('../src/audit');
 const { setup } = require('../src/setup');
-const { analyzeProject, printAnalysis } = require('../src/analyze');
+const { analyzeProject, printAnalysis, exportMarkdown } = require('../src/analyze');
 const { buildProposalBundle, printProposalBundle, writePlanFile, applyProposalBundle, printApplyResult } = require('../src/plans');
 const { getGovernanceSummary, printGovernanceSummary, ensureWritableProfile } = require('../src/governance');
 const { runBenchmark, printBenchmark, writeBenchmarkReport } = require('../src/benchmark');
@@ -295,6 +295,12 @@ async function main() {
       return; // keep process alive for http
     } else if (normalizedCommand === 'augment' || normalizedCommand === 'suggest-only') {
       const report = await analyzeProject({ ...options, mode: normalizedCommand });
+      if (options.out && !options.json) {
+        const fs = require('fs');
+        const md = exportMarkdown(report);
+        fs.writeFileSync(options.out, md, 'utf8');
+        console.log(`\n  Report exported to ${options.out}\n`);
+      }
       printAnalysis(report, options);
     } else if (normalizedCommand === 'plan') {
       const bundle = await buildProposalBundle(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudex-setup",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Audit and improve Claude Code readiness with discover, plan, apply, governance, and benchmark workflows.",
   "main": "src/index.js",
   "bin": {

package/src/analyze.js

@@ -170,6 +170,30 @@ function moduleFromCategory(category) {
   return map[category] || category;
 }
 
+const STRENGTH_REASONS = {
+  claudeMd: 'Foundation of Claude workflow. Every session benefits from this.',
+  mermaidArchitecture: 'Architecture diagram saves 73% tokens vs prose — high-value asset.',
+  verificationLoop: 'Claude can self-verify, catching errors before human review.',
+  hooks: 'Automated enforcement (100% vs 80% from instructions alone).',
+  hooksInSettings: 'Hook registration in settings ensures consistent automation.',
+  preToolUseHook: 'Pre-execution validation adds a safety layer.',
+  postToolUseHook: 'Post-execution automation catches issues immediately.',
+  sessionStartHook: 'Session initialization ensures consistent starting state.',
+  customCommands: 'Reusable workflows encoded as one-liner commands.',
+  settingsPermissions: 'Explicit permissions prevent accidental dangerous operations.',
+  permissionDeny: 'Deny rules block risky operations at the system level.',
+  pathRules: 'Scoped rules ensure different code areas get appropriate guidance.',
+  fewShotExamples: 'Code examples guide Claude to match your conventions.',
+  constraintBlocks: 'XML constraint blocks improve rule adherence by 40%.',
+  xmlTags: 'Structured prompt sections improve consistency.',
+  context7Mcp: 'Real-time docs eliminate version-mismatch hallucinations.',
+  mcpServers: 'External tool integration extends Claude capabilities.',
+  compactionAwareness: 'Context management keeps sessions efficient.',
+  agents: 'Specialized agents delegate complex tasks effectively.',
+  noSecretsInClaude: 'No secrets in config — good security hygiene.',
+  gitIgnoreEnv: 'Environment files are properly excluded from git.',
+};
+
 function toStrengths(results) {
   return results
     .filter(r => r.passed === true)
@@ -177,15 +201,30 @@ function toStrengths(results) {
       const order = { critical: 3, high: 2, medium: 1, low: 0 };
       return (order[b.impact] || 0) - (order[a.impact] || 0);
     })
-    .slice(0, 6)
+    .slice(0, 8)
     .map(r => ({
       key: r.key,
       name: r.name,
       category: r.category,
-      note: `Already present and worth preserving: ${r.name}.`,
+      why: STRENGTH_REASONS[r.key] || `Already configured and working: ${r.name}.`,
     }));
 }
 
+const GAP_REASONS = {
+  noBypassPermissions: 'bypassPermissions skips all safety checks. Use explicit allow rules for control without risk.',
+  secretsProtection: 'Without deny rules for .env, Claude can read secrets and potentially expose them in outputs.',
+  testCommand: 'Without a test command, Claude cannot verify its changes work before you review them.',
+  lintCommand: 'Without a lint command, Claude may produce inconsistently formatted code.',
+  buildCommand: 'Without a build command, Claude cannot catch compilation errors early.',
+  ciPipeline: 'CI ensures every change is automatically tested. Without it, bugs reach main branch faster.',
+  securityReview: 'Claude Code has built-in OWASP Top 10 scanning. Not using it leaves vulnerabilities undetected.',
+  skills: 'Skills encode domain expertise as reusable components. Without them, you repeat context every session.',
+  multipleAgents: 'Multiple agents enable parallel specialized work (security review + code writing simultaneously).',
+  multipleMcpServers: 'More MCP servers give Claude access to more external context (docs, databases, APIs).',
+  roleDefinition: 'A role definition helps Claude calibrate response depth and technical level.',
+  importSyntax: '@import keeps CLAUDE.md lean while still providing deep instructions in focused modules.',
+};
+
 function toGaps(results) {
   return results
     .filter(r => r.passed === false)
@@ -200,6 +239,7 @@ function toGaps(results) {
       impact: r.impact,
       category: r.category,
       fix: r.fix,
+      why: GAP_REASONS[r.key] || r.fix,
     }));
 }
 
@@ -356,7 +396,10 @@ function printAnalysis(report, options = {}) {
   if (report.strengthsPreserved.length > 0) {
     console.log(c('  Strengths Preserved', 'green'));
     for (const item of report.strengthsPreserved) {
-      console.log(`  - ${item.name}`);
+      console.log(`  ${c('✓', 'green')} ${item.name}`);
+      if (item.why) {
+        console.log(c(`    ${item.why}`, 'dim'));
+      }
     }
     console.log('');
   }
@@ -420,4 +463,87 @@ function printAnalysis(report, options = {}) {
   }
 }
 
-module.exports = { analyzeProject, printAnalysis };
+function exportMarkdown(report) {
+  const lines = [];
+  lines.push(`# Claudex Setup Analysis Report`);
+  lines.push(`## ${report.mode === 'suggest-only' ? 'Suggest-Only' : 'Augment'} Mode`);
+  lines.push('');
+  lines.push(`**Project:** ${report.projectSummary.name}${report.projectSummary.description ? ` — ${report.projectSummary.description}` : ''}`);
+  lines.push(`**Date:** ${new Date().toISOString().split('T')[0]}`);
+  lines.push(`**Score:** ${report.projectSummary.score}/100 | **Organic:** ${report.projectSummary.organicScore}/100`);
+  lines.push(`**Stacks:** ${report.projectSummary.stacks.join(', ') || 'None detected'}`);
+  lines.push(`**Domain Packs:** ${report.projectSummary.domains.join(', ') || 'Baseline General'}`);
+  lines.push(`**Maturity:** ${report.projectSummary.maturity}`);
+  lines.push('');
+
+  if (report.strengthsPreserved.length > 0) {
+    lines.push('## Strengths Preserved');
+    lines.push('');
+    for (const item of report.strengthsPreserved) {
+      lines.push(`- **${item.name}** — ${item.why || 'Already configured.'}`);
+    }
+    lines.push('');
+  }
+
+  if (report.gapsIdentified.length > 0) {
+    lines.push('## Gaps Identified');
+    lines.push('');
+    lines.push('| Gap | Impact | Fix |');
+    lines.push('|-----|--------|-----|');
+    for (const item of report.gapsIdentified) {
+      lines.push(`| ${item.name} | ${item.impact} | ${item.fix} |`);
+    }
+    lines.push('');
+  }
+
+  if (report.topNextActions.length > 0) {
+    lines.push('## Top Next Actions');
+    lines.push('');
+    report.topNextActions.slice(0, 5).forEach((item, index) => {
+      lines.push(`${index + 1}. **${item.name}** — ${item.fix}`);
+    });
+    lines.push('');
+  }
+
+  if (report.recommendedDomainPacks.length > 0) {
+    lines.push('## Recommended Domain Packs');
+    lines.push('');
+    for (const pack of report.recommendedDomainPacks) {
+      lines.push(`- **${pack.label}**: ${pack.useWhen}`);
+    }
+    lines.push('');
+  }
+
+  if (report.recommendedMcpPacks.length > 0) {
+    lines.push('## Recommended MCP Packs');
+    lines.push('');
+    for (const pack of report.recommendedMcpPacks) {
+      lines.push(`- **${pack.label}**: ${pack.useWhen}`);
+    }
+    lines.push('');
+  }
+
+  if (report.riskNotes.length > 0) {
+    lines.push('## Risk Notes');
+    lines.push('');
+    for (const note of report.riskNotes) {
+      lines.push(`- ⚠️ ${note}`);
+    }
+    lines.push('');
+  }
+
+  if (report.suggestedRolloutOrder.length > 0) {
+    lines.push('## Suggested Rollout Order');
+    lines.push('');
+    report.suggestedRolloutOrder.forEach((item, index) => {
+      lines.push(`${index + 1}. ${item}`);
+    });
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push(`*Generated by claudex-setup v${require('../package.json').version}*`);
+  return lines.join('\n');
+}
+
+module.exports = { analyzeProject, printAnalysis, exportMarkdown };

package/src/claudex-sync.json

@@ -1,7 +1,11 @@
 {
   "synced_from": "claudex",
-  "synced_at": "2026-03-30T23:05:29Z",
+  "synced_at": "2026-03-31T19:30:00Z",
   "total_items": 1107,
   "tested": 948,
-  "last_id": 1157
+  "last_id": 1157,
+  "domain_packs": 10,
+  "mcp_packs": 5,
+  "anti_patterns": 53,
+  "contract_version": "1.0.0"
 }

package/src/domain-packs.js

@@ -55,6 +55,30 @@ const DOMAIN_PACKS = [
     recommendedMcpPacks: ['context7-docs'],
     benchmarkFocus: ['policy-aware rollout', 'approval flow readiness', 'benchmark export quality'],
   },
+  {
+    key: 'monorepo',
+    label: 'Monorepo',
+    useWhen: 'Nx, Turborepo, Lerna, or workspace-based repos with multiple packages sharing a root.',
+    recommendedModules: ['path-specific rules', 'commands per package', 'governance', 'agents'],
+    recommendedMcpPacks: ['context7-docs'],
+    benchmarkFocus: ['package-scoped rule coverage', 'cross-package safety', 'workspace-aware starter output'],
+  },
+  {
+    key: 'mobile',
+    label: 'Mobile App',
+    useWhen: 'React Native, Flutter, Swift, or Kotlin repos with mobile-specific build and release workflows.',
+    recommendedModules: ['verification', 'commands', 'rules', 'agents'],
+    recommendedMcpPacks: ['context7-docs'],
+    benchmarkFocus: ['build verification', 'platform-specific rules', 'release workflow quality'],
+  },
+  {
+    key: 'regulated-lite',
+    label: 'Regulated Lite',
+    useWhen: 'Repos in regulated environments (fintech, health, legal) that need auditability without full enterprise governance overhead.',
+    recommendedModules: ['governance', 'activity artifacts', 'suggest-only profile', 'audit logging'],
+    recommendedMcpPacks: ['context7-docs'],
+    benchmarkFocus: ['audit trail completeness', 'change traceability', 'policy compliance readiness'],
+  },
 ];
 
 function uniqueByKey(items) {
@@ -144,6 +168,45 @@ function detectDomainPacks(ctx, stacks, assets = null) {
     ]);
   }
 
+  // Monorepo detection
+  const isMonorepo = ctx.files.includes('nx.json') || ctx.files.includes('turbo.json') ||
+    ctx.files.includes('lerna.json') || ctx.hasDir('packages') ||
+    (pkg.workspaces && (Array.isArray(pkg.workspaces) ? pkg.workspaces.length > 0 : true));
+  if (isMonorepo) {
+    addMatch('monorepo', [
+      'Detected monorepo or workspace configuration.',
+      ctx.files.includes('nx.json') ? 'Nx workspace detected.' : null,
+      ctx.files.includes('turbo.json') ? 'Turborepo detected.' : null,
+      ctx.hasDir('packages') ? 'Packages directory detected.' : null,
+    ]);
+  }
+
+  // Mobile detection
+  const isMobile = deps['react-native'] || deps.expo || deps.flutter ||
+    ctx.files.includes('Podfile') || ctx.files.includes('build.gradle') ||
+    ctx.files.includes('build.gradle.kts') || ctx.hasDir('ios') || ctx.hasDir('android');
+  if (isMobile) {
+    addMatch('mobile', [
+      'Detected mobile app structure or dependencies.',
+      deps['react-native'] ? 'React Native detected.' : null,
+      ctx.hasDir('ios') ? 'iOS directory detected.' : null,
+      ctx.hasDir('android') ? 'Android directory detected.' : null,
+    ]);
+  }
+
+  // Regulated-lite detection
+  const isRegulated = ctx.files.includes('SECURITY.md') ||
+    ctx.files.includes('COMPLIANCE.md') || ctx.hasDir('compliance') ||
+    ctx.hasDir('audit') || ctx.hasDir('policies') ||
+    (pkg.keywords && pkg.keywords.some(k => ['hipaa', 'fintech', 'compliance', 'regulated', 'sox', 'pci'].includes(k)));
+  if (isRegulated && !isEnterpriseGoverned) {
+    addMatch('regulated-lite', [
+      'Detected compliance or regulatory signals without full enterprise governance.',
+      ctx.files.includes('SECURITY.md') ? 'SECURITY.md present.' : null,
+      ctx.hasDir('compliance') ? 'Compliance directory detected.' : null,
+    ]);
+  }
+
   const deduped = uniqueByKey(matches);
   if (deduped.length === 0) {
     return [{

package/src/governance.js

@@ -86,6 +86,54 @@ const HOOK_REGISTRY = [
     dryRunExample: 'Edit one file and verify the log entry is appended.',
     rollbackPath: 'Remove the PostToolUse hook entry and delete the log file if desired.',
   },
+  {
+    key: 'duplicate-id-check',
+    file: '.claude/hooks/check-duplicate-ids.sh',
+    triggerPoint: 'PostToolUse',
+    matcher: 'Write|Edit',
+    purpose: 'Detects duplicate IDs in catalog or structured data files after edits.',
+    filesTouched: [],
+    sideEffects: ['Returns a systemMessage warning if duplicates are found.'],
+    risk: 'low',
+    dryRunExample: 'Edit a catalog file and verify duplicate check runs without blocking.',
+    rollbackPath: 'Remove the PostToolUse hook entry from settings.',
+  },
+  {
+    key: 'injection-defense',
+    file: '.claude/hooks/injection-defense.sh',
+    triggerPoint: 'PostToolUse',
+    matcher: 'WebFetch|WebSearch',
+    purpose: 'Scans web tool outputs for common prompt injection patterns.',
+    filesTouched: ['tools/failure-log.txt'],
+    sideEffects: ['Logs alerts to failure log.', 'Returns a systemMessage warning if patterns detected.'],
+    risk: 'low',
+    dryRunExample: 'Run a WebFetch and verify output is scanned for injection patterns.',
+    rollbackPath: 'Remove the PostToolUse hook entry from settings.',
+  },
+  {
+    key: 'trust-drift-check',
+    file: '.claude/hooks/trust-drift-check.sh',
+    triggerPoint: 'PostToolUse',
+    matcher: 'Write|Edit',
+    purpose: 'Runs trust drift validation after file changes to catch metric/docs inconsistencies.',
+    filesTouched: [],
+    sideEffects: ['Returns a systemMessage warning if drift is detected.'],
+    risk: 'low',
+    dryRunExample: 'Edit a product-facing file and verify drift check runs.',
+    rollbackPath: 'Remove the PostToolUse hook entry from settings.',
+  },
+  {
+    key: 'session-init',
+    file: '.claude/hooks/rotate-logs.sh',
+    triggerPoint: 'SessionStart',
+    matcher: null,
+    purpose: 'Rotates large log files and loads workspace context at session start.',
+    filesTouched: ['tools/change-log.txt', 'tools/failure-log.txt'],
+    sideEffects: ['Archives logs over 500KB.', 'Returns a systemMessage with workspace info.'],
+    risk: 'low',
+    dryRunExample: 'Start a new session and verify log rotation runs.',
+    rollbackPath: 'Remove the SessionStart hook entry from settings.',
+  },
 ];
 
 const POLICY_PACKS = [
@@ -307,8 +355,9 @@ function printGovernanceSummary(summary, options = {}) {
 
   console.log('  Hook Registry');
   for (const hook of summary.hookRegistry) {
-    console.log(`  - ${hook.file}`);
-    console.log(`    ${hook.triggerPoint} ${hook.matcher} -> ${hook.purpose}`);
+    const riskColor = hook.risk === 'low' ? '\x1b[32m' : hook.risk === 'medium' ? '\x1b[33m' : '\x1b[31m';
+    console.log(`  - ${hook.file} ${riskColor}[${hook.risk} risk]\x1b[0m`);
+    console.log(`    ${hook.triggerPoint}${hook.matcher ? ` ${hook.matcher}` : ''} -> ${hook.purpose}`);
   }
   console.log('');
 

package/src/mcp-packs.js

@@ -23,6 +23,44 @@ const MCP_PACKS = [
       },
     },
   },
+  {
+    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) {
@@ -71,6 +109,22 @@ function recommendMcpPacks(stacks = [], domainPacks = []) {
     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));

package/src/techniques.js

@@ -358,9 +358,15 @@ const TECHNIQUES = {
     id: 2402,
     name: 'Default mode is not bypassPermissions',
     check: (ctx) => {
-      const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-      if (!settings || !settings.permissions) return null; // no settings = skip (not applicable)
-      return settings.permissions.defaultMode !== 'bypassPermissions';
+      // Check shared settings first (committed to git) — if the shared baseline
+      // is safe, a personal settings.local.json override should not fail the audit.
+      const shared = ctx.jsonFile('.claude/settings.json');
+      if (shared && shared.permissions) {
+        return shared.permissions.defaultMode !== 'bypassPermissions';
+      }
+      const local = ctx.jsonFile('.claude/settings.local.json');
+      if (!local || !local.permissions) return null;
+      return local.permissions.defaultMode !== 'bypassPermissions';
     },
     impact: 'critical',
     rating: 5,
@@ -373,7 +379,8 @@ const TECHNIQUES = {
     id: 1096,
     name: 'Secrets protection configured',
     check: (ctx) => {
-      const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
+      // Prefer shared settings.json (committed) over local override
+      const settings = ctx.jsonFile('.claude/settings.json') || ctx.jsonFile('.claude/settings.local.json');
       if (!settings || !settings.permissions) return false;
       const deny = JSON.stringify(settings.permissions.deny || []);
       return deny.includes('.env') || deny.includes('secrets');