forgedev 1.2.0 → 1.3.0

package/src/cli.js

@@ -5,7 +5,13 @@ import { log } from './utils.js';
 
 export async function parseCommand(args) {
   if (args.includes('--version') || args.includes('-v')) {
-    const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+    let pkg;
+    try {
+      pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+    } catch (err) {
+      console.error(`Could not read package.json: ${err.message}`);
+      process.exit(1);
+    }
     console.log(pkg.version);
     process.exit(0);
   }
@@ -18,8 +24,10 @@ export async function parseCommand(args) {
   const command = args[0];
 
   if (!command) {
-    showUsage();
-    process.exit(0);
+    const { showInteractiveMenu, handleMenuSelection } = await import('./menu.js');
+    const selected = await showInteractiveMenu();
+    await handleMenuSelection(selected);
+    return;
   }
 
   if (command === 'new') {
@@ -46,6 +54,12 @@ export async function parseCommand(args) {
     return;
   }
 
+  if (command === 'ci') {
+    const { runCI } = await import('./ci-mode.js');
+    await runCI(process.cwd());
+    return;
+  }
+
   if (command === 'update') {
     const { runUpdate } = await import('./update.js');
     await runUpdate();
@@ -73,12 +87,13 @@ export async function parseCommand(args) {
 
 function showUsage() {
   console.log(`
-  ${chalk.bold.cyan('DevForge')} — AI-first project scaffolding
+  ${chalk.bold.cyan('DevForge')}  AI-first project scaffolding
 
   ${chalk.bold('Usage:')}
     devforge new <name>     Create a new project
     devforge init           Add dev guardrails to current project
     devforge doctor         Diagnose and optimize current project
+    devforge ci             Run health checks for CI/CD (non-interactive)
     devforge update         Check for newer version
     devforge <name>         Shorthand for ${chalk.dim('devforge new <name>')}
 
@@ -92,14 +107,14 @@ function showUsage() {
 
 function showHelp() {
   console.log(`
-  ${chalk.bold.cyan('DevForge')} — Universal, AI-first project scaffolding
+  ${chalk.bold.cyan('DevForge')}  Universal, AI-first project scaffolding
 
   ${chalk.bold('Commands:')}
 
     ${chalk.bold('devforge new <name>')}
       Create a new project. Choose between:
-      ${chalk.dim('• Guided mode — describe what you want in plain English')}
-      ${chalk.dim('• Developer mode — pick your stack directly')}
+      ${chalk.dim('• Guided mode: describe what you want in plain English')}
+      ${chalk.dim('• Developer mode: pick your stack directly')}
 
     ${chalk.bold('devforge init')}
       Add Claude Code infrastructure to an existing project.
@@ -112,6 +127,11 @@ function showHelp() {
       flaky tests, dead code, duplicate code, and more.
       Generates Claude Code prompts to fix each issue.
 
+    ${chalk.bold('devforge ci')}
+      Run project health checks non-interactively for CI/CD.
+      Exits with code 1 if critical issues found.
+      Saves report to docs/ci-report.md if docs/ exists.
+
     ${chalk.bold('devforge update')}
       Check if a newer version of DevForge is available.
       Shows upgrade instructions if an update exists.
@@ -120,6 +140,9 @@ function showHelp() {
     - Next.js full-stack (TypeScript + Prisma + PostgreSQL)
     - FastAPI backend (Python + SQLAlchemy + PostgreSQL)
     - Polyglot full-stack (Next.js + FastAPI monorepo)
+    - React + Express (Vite + Express + Prisma + PostgreSQL)
+    - Remix full-stack (Vite + Tailwind + Prisma + PostgreSQL)
+    - Hono API (TypeScript + Prisma + PostgreSQL)
 
   ${chalk.bold('Examples:')}
     devforge new my-app

package/src/composer.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { ROOT_DIR, ensureDir, readTemplate, replaceVars, toPascalCase, toSnakeCase, log } from './utils.js';
+import { ROOT_DIR, ensureDir, readTemplate, replaceVars, toPascalCase, toSnakeCase, getStackCommands, copyEnvCmd, log } from './utils.js';
 
 const TEMPLATES_DIR = path.join(ROOT_DIR, 'templates');
 
@@ -12,7 +12,7 @@ export async function compose(outputDir, stackConfig) {
   for (const mod of stackConfig.templateModules) {
     const templateDir = path.join(TEMPLATES_DIR, mod.path);
     if (!fs.existsSync(templateDir)) {
-      log.warn(`Template module not found: ${mod.path} — skipping`);
+      log.warn(`Template module not found: ${mod.path}, skipping`);
       continue;
     }
     processTemplateDir(templateDir, outputDir, variables, mod.prefix || '');
@@ -20,6 +20,9 @@ export async function compose(outputDir, stackConfig) {
 
   // Inject auth dependencies into package.json if auth is enabled
   injectAuthDependencies(outputDir, stackConfig);
+
+  // Apply user plugins from ~/.devforge/templates/ if they exist
+  applyUserPlugins(outputDir, variables, stackConfig);
 }
 
 export function buildVariables(stackConfig) {
@@ -50,31 +53,27 @@ export function buildVariables(stackConfig) {
   vars.AUTH_TYPE = stackConfig.auth || 'none';
   vars.DEPLOYMENT = stackConfig.deployment || 'docker';
 
-  // Commands vary by stack
+  // Commands vary by stack (shared with claude-configurator)
+  Object.assign(vars, getStackCommands(stackConfig.stackId));
+
   if (stackConfig.stackId === 'nextjs-fullstack') {
-    vars.LINT_COMMAND = 'npx eslint .';
-    vars.TYPE_CHECK_COMMAND = 'npx tsc --noEmit';
-    vars.TEST_COMMAND = 'npx vitest run';
-    vars.BUILD_COMMAND = 'npm run build';
-    vars.DEV_COMMAND = 'npm run dev';
     vars.STACK_DESCRIPTION = 'Next.js full-stack application with TypeScript, Tailwind CSS, Prisma, and PostgreSQL';
     vars.EXTRA_IGNORES = '';
   } else if (stackConfig.stackId === 'fastapi-backend') {
-    vars.LINT_COMMAND = 'ruff check .';
-    vars.TYPE_CHECK_COMMAND = 'pyright';
-    vars.TEST_COMMAND = 'pytest';
-    vars.BUILD_COMMAND = 'docker build -t app .';
-    vars.DEV_COMMAND = 'uvicorn app.main:app --reload';
     vars.STACK_DESCRIPTION = 'FastAPI backend service with SQLAlchemy, PostgreSQL, and Alembic';
     vars.EXTRA_IGNORES = '\n# Python\n__pycache__/\n*.pyc\nvenv/\n.venv/\n*.egg-info/';
   } else if (stackConfig.stackId === 'polyglot-fullstack') {
-    vars.LINT_COMMAND = 'cd frontend && npx eslint . && cd ../backend && ruff check .';
-    vars.TYPE_CHECK_COMMAND = 'cd frontend && npx tsc --noEmit';
-    vars.TEST_COMMAND = 'cd frontend && npx vitest run && cd ../backend && pytest';
-    vars.BUILD_COMMAND = 'docker compose build';
-    vars.DEV_COMMAND = 'docker compose up';
     vars.STACK_DESCRIPTION = 'Full-stack application with Next.js frontend and FastAPI backend';
     vars.EXTRA_IGNORES = '\n# Python\n__pycache__/\n*.pyc\nvenv/\n.venv/\n*.egg-info/';
+  } else if (stackConfig.stackId === 'react-express') {
+    vars.STACK_DESCRIPTION = 'Full-stack application with React (Vite) frontend and Express backend';
+    vars.EXTRA_IGNORES = '\ndist/';
+  } else if (stackConfig.stackId === 'remix-fullstack') {
+    vars.STACK_DESCRIPTION = 'Full-stack Remix application with Vite, Tailwind CSS, and PostgreSQL';
+    vars.EXTRA_IGNORES = '\nbuild/';
+  } else if (stackConfig.stackId === 'hono-api') {
+    vars.STACK_DESCRIPTION = 'Hono API service with TypeScript, Prisma, and PostgreSQL';
+    vars.EXTRA_IGNORES = '\ndist/';
   }
 
   // Setup commands for README
@@ -87,7 +86,7 @@ export function buildVariables(stackConfig) {
 function buildSetupCommands(config) {
   if (config.stackId === 'nextjs-fullstack') {
     return `npm install
-cp .env.example .env
+${copyEnvCmd()}
 npx prisma db push
 npm run dev`;
   }
@@ -96,7 +95,7 @@ npm run dev`;
 python -m venv venv
 source venv/bin/activate
 pip install -r requirements.txt
-cp .env.example .env
+${copyEnvCmd()}
 uvicorn app.main:app --reload`;
   }
   if (config.stackId === 'polyglot-fullstack') {
@@ -105,30 +104,72 @@ uvicorn app.main:app --reload`;
 cd frontend && npm install && npm run dev
 # Backend
 cd backend && pip install -r requirements.txt && uvicorn app.main:app --reload`;
+  }
+  if (config.stackId === 'react-express') {
+    return `# Frontend
+cd frontend && npm install && npm run dev
+# Backend (in a separate terminal)
+cd backend && npm install && ${copyEnvCmd()} && npx prisma db push && npm run dev`;
+  }
+  if (config.stackId === 'remix-fullstack') {
+    return `npm install
+${copyEnvCmd()}
+npx prisma db push
+npm run dev`;
+  }
+  if (config.stackId === 'hono-api') {
+    return `npm install
+${copyEnvCmd()}
+npx prisma db push
+npm run dev`;
   }
   return '';
 }
 
 function buildAvailableScripts(config) {
   if (config.stackId === 'nextjs-fullstack') {
-    return `- \`npm run dev\` — Start development server
-- \`npm run build\` — Production build
-- \`npm run lint\` — Run ESLint
-- \`npx prisma studio\` — Database GUI
-- \`npx vitest\` — Run unit tests
-- \`npx playwright test\` — Run E2E tests`;
+    return `- \`npm run dev\`: Start development server
+- \`npm run build\`: Production build
+- \`npm run lint\`: Run ESLint
+- \`npx prisma studio\`: Database GUI
+- \`npx vitest\`: Run unit tests
+- \`npx playwright test\`: Run E2E tests`;
   }
   if (config.stackId === 'fastapi-backend') {
-    return `- \`uvicorn app.main:app --reload\` — Start dev server
-- \`pytest\` — Run tests
-- \`ruff check .\` — Run linter
-- \`alembic upgrade head\` — Run migrations`;
+    return `- \`uvicorn app.main:app --reload\`: Start dev server
+- \`pytest\`: Run tests
+- \`ruff check .\`: Run linter
+- \`alembic upgrade head\`: Run migrations`;
   }
   if (config.stackId === 'polyglot-fullstack') {
-    return `- \`docker compose up\` — Start all services
-- \`docker compose up -d postgres\` — Start database only
+    return `- \`docker compose up\`: Start all services
+- \`docker compose up -d postgres\`: Start database only
 - Frontend: \`cd frontend && npm run dev\`
 - Backend: \`cd backend && uvicorn app.main:app --reload\``;
+  }
+  if (config.stackId === 'react-express') {
+    return `- Frontend: \`cd frontend && npm run dev\` (Vite dev server)
+- Backend: \`cd backend && npm run dev\` (Express with tsx watch)
+- \`cd backend && npm run build\`: Build backend for production
+- \`cd frontend && npm run build\`: Build frontend for production
+- \`cd backend && npx prisma studio\`: Database GUI
+- \`cd frontend && npx vitest\`: Run frontend tests`;
+  }
+  if (config.stackId === 'remix-fullstack') {
+    return `- \`npm run dev\`: Start Remix dev server
+- \`npm run build\`: Production build
+- \`npm run start\`: Start production server
+- \`npm run lint\`: Run ESLint
+- \`npx prisma studio\`: Database GUI
+- \`npx vitest\`: Run unit tests`;
+  }
+  if (config.stackId === 'hono-api') {
+    return `- \`npm run dev\`: Start Hono dev server (tsx watch)
+- \`npm run build\`: Compile TypeScript
+- \`npm run start\`: Start production server
+- \`npm run lint\`: Run ESLint
+- \`npx prisma studio\`: Database GUI
+- \`npx vitest\`: Run unit tests`;
   }
   return '';
 }
@@ -138,7 +179,14 @@ export function processTemplateDir(templateDir, outputDir, variables, prefix) {
 
   for (const filePath of entries) {
     const relativePath = path.relative(templateDir, filePath);
-    let outputRelative = prefix ? path.join(prefix, relativePath) : relativePath;
+    const outputRelative = prefix ? path.join(prefix, relativePath) : relativePath;
+
+    // Guard against path traversal (e.g. ../../etc/passwd in plugin templates)
+    const resolved = path.resolve(outputDir, outputRelative);
+    if (!resolved.startsWith(path.resolve(outputDir))) {
+      log.warn(`Skipping "${outputRelative}" (path traversal detected)`);
+      continue;
+    }
 
     if (outputRelative.endsWith('.template')) {
       // Process template: replace vars, strip .template extension
@@ -184,7 +232,13 @@ function injectAuthDependencies(outputDir, stackConfig) {
     ];
     for (const pkgPath of pkgPaths) {
       if (!fs.existsSync(pkgPath)) continue;
-      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      let pkg;
+      try {
+        pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      } catch {
+        log.warn(`Skipping auth dependency injection — could not parse ${pkgPath}`);
+        continue;
+      }
       pkg.dependencies = pkg.dependencies || {};
       pkg.dependencies['next-auth'] = '^5.0.0-beta.25';
       pkg.dependencies['@auth/prisma-adapter'] = '^2.7.4';
@@ -212,3 +266,74 @@ function injectAuthDependencies(outputDir, stackConfig) {
     }
   }
 }
+
+function applyUserPlugins(outputDir, variables, stackConfig) {
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  if (!homeDir) return;
+
+  const pluginDir = path.join(homeDir, '.devforge');
+  if (!fs.existsSync(pluginDir)) return;
+
+  // User templates: ~/.devforge/templates/<stackId>/ → overlay onto output
+  const userTemplatesDir = path.join(pluginDir, 'templates', stackConfig.stackId);
+  if (fs.existsSync(userTemplatesDir)) {
+    processTemplateDir(userTemplatesDir, outputDir, variables, '');
+    log.dim(`  Applied user templates from ~/.devforge/templates/${stackConfig.stackId}/`);
+  }
+
+  // Universal user templates: ~/.devforge/templates/universal/ → always applied
+  const universalDir = path.join(pluginDir, 'templates', 'universal');
+  if (fs.existsSync(universalDir)) {
+    processTemplateDir(universalDir, outputDir, variables, '');
+    log.dim('  Applied user templates from ~/.devforge/templates/universal/');
+  }
+
+  // User agents: ~/.devforge/agents/*.md → copy into .claude/agents/
+  const userAgentsDir = path.join(pluginDir, 'agents');
+  if (fs.existsSync(userAgentsDir)) {
+    const agents = fs.readdirSync(userAgentsDir).filter(f => f.endsWith('.md'));
+    for (const agent of agents) {
+      const src = path.join(userAgentsDir, agent);
+      const dest = path.join(outputDir, '.claude', 'agents', agent);
+      ensureDir(path.dirname(dest));
+      fs.copyFileSync(src, dest);
+    }
+    if (agents.length > 0) {
+      log.dim(`  Applied ${agents.length} user agent(s) from ~/.devforge/agents/`);
+    }
+  }
+
+  // User commands: ~/.devforge/commands/*.md → copy into .claude/commands/
+  const userCommandsDir = path.join(pluginDir, 'commands');
+  if (fs.existsSync(userCommandsDir)) {
+    const commands = fs.readdirSync(userCommandsDir).filter(f => f.endsWith('.md'));
+    for (const cmd of commands) {
+      const src = path.join(userCommandsDir, cmd);
+      const dest = path.join(outputDir, '.claude', 'commands', cmd);
+      ensureDir(path.dirname(dest));
+      fs.copyFileSync(src, dest);
+    }
+    if (commands.length > 0) {
+      log.dim(`  Applied ${commands.length} user command(s) from ~/.devforge/commands/`);
+    }
+  }
+
+  // User skills: ~/.devforge/skills/<name>/SKILL.md → copy into .claude/skills/
+  const userSkillsDir = path.join(pluginDir, 'skills');
+  if (fs.existsSync(userSkillsDir)) {
+    const skills = fs.readdirSync(userSkillsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+    for (const skill of skills) {
+      const skillFile = path.join(userSkillsDir, skill, 'SKILL.md');
+      if (fs.existsSync(skillFile)) {
+        const dest = path.join(outputDir, '.claude', 'skills', skill, 'SKILL.md');
+        ensureDir(path.dirname(dest));
+        fs.copyFileSync(skillFile, dest);
+      }
+    }
+    if (skills.length > 0) {
+      log.dim(`  Applied ${skills.length} user skill(s) from ~/.devforge/skills/`);
+    }
+  }
+}

package/src/doctor-checks-chainproof.js

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+export function checkChainproofExists(projectDir) {
+  const cpDir = path.join(projectDir, '.chainproof');
+  if (fs.existsSync(cpDir)) return [];
+
+  return [{
+    severity: 'info',
+    title: 'ChainProof trust chain not initialized',
+    impact: 'No provenance tracking for AI-generated code changes',
+    files: [],
+    autoFixable: true,
+    promptId: 'CHAINPROOF_MISSING',
+    effort: 'quick',
+  }];
+}
+
+export function checkChainproofIntegrity(projectDir) {
+  const chainPath = path.join(projectDir, '.chainproof', 'chain.json');
+  if (!fs.existsSync(chainPath)) return [];
+
+  try {
+    const chain = JSON.parse(fs.readFileSync(chainPath, 'utf-8'));
+    let expectedHash = '0'.repeat(64);
+
+    for (let i = 0; i < chain.entries.length; i++) {
+      const entry = chain.entries[i];
+      if (entry.prevHash !== expectedHash) {
+        return [{
+          severity: 'critical',
+          title: `ChainProof hash chain broken at entry ${i}`,
+          impact: 'Trust chain integrity compromised. Provenance trail is unreliable',
+          files: ['.chainproof/chain.json'],
+          autoFixable: false,
+          promptId: 'CHAINPROOF_BROKEN',
+          effort: 'medium',
+        }];
+      }
+      const contentHash = createHash('sha256').update(entry.content, 'utf-8').digest('hex');
+      const computedChainHash = createHash('sha256').update(entry.prevHash + contentHash, 'utf-8').digest('hex');
+      if (entry.chainHash !== computedChainHash) {
+        return [{
+          severity: 'critical',
+          title: `ChainProof chainHash mismatch at entry ${i}`,
+          impact: 'Entry hash does not match computed value. Chain may have been tampered with',
+          files: ['.chainproof/chain.json'],
+          autoFixable: false,
+          promptId: 'CHAINPROOF_BROKEN',
+          effort: 'medium',
+        }];
+      }
+      expectedHash = computedChainHash;
+    }
+
+    // Verify currentHash matches the last entry (same check as runtime verifier)
+    if (chain.entries.length > 0 && chain.currentHash !== expectedHash) {
+      return [{
+        severity: 'critical',
+        title: 'ChainProof currentHash is inconsistent with chain',
+        impact: 'The stored current hash does not match the last entry. Chain state is corrupted',
+        files: ['.chainproof/chain.json'],
+        autoFixable: false,
+        promptId: 'CHAINPROOF_BROKEN',
+        effort: 'medium',
+      }];
+    }
+  } catch {
+    // Malformed chain.json
+    return [{
+      severity: 'critical',
+      title: 'ChainProof chain.json is malformed',
+      impact: 'Cannot verify trust chain integrity',
+      files: ['.chainproof/chain.json'],
+      autoFixable: false,
+      promptId: 'CHAINPROOF_MALFORMED',
+      effort: 'medium',
+    }];
+  }
+
+  return [];
+}
+
+export function checkChainproofUnsigned(projectDir) {
+  const chainPath = path.join(projectDir, '.chainproof', 'chain.json');
+  if (!fs.existsSync(chainPath)) return [];
+
+  try {
+    const chain = JSON.parse(fs.readFileSync(chainPath, 'utf-8'));
+    const unsigned = chain.entries.filter(e => !e.signature);
+    if (unsigned.length === 0) return [];
+
+    return [{
+      severity: 'warning',
+      title: `${unsigned.length} unsigned entries in ChainProof trust chain`,
+      impact: 'Unsigned entries cannot be cryptographically verified',
+      files: ['.chainproof/chain.json'],
+      autoFixable: false,
+      promptId: 'CHAINPROOF_UNSIGNED',
+      effort: 'quick',
+    }];
+  } catch {
+    return [];
+  }
+}

package/src/doctor-checks.js

@@ -1,5 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import {
+  checkChainproofExists,
+  checkChainproofIntegrity,
+  checkChainproofUnsigned,
+} from './doctor-checks-chainproof.js';
+
+export { checkChainproofExists, checkChainproofIntegrity, checkChainproofUnsigned };
 
 export function runAllChecks(projectDir, scan) {
   const issues = [];
@@ -21,6 +28,9 @@ export function runAllChecks(projectDir, scan) {
   issues.push(...checkDuplicateCode(projectDir));
   issues.push(...checkDeadFeatures(projectDir, scan));
   issues.push(...checkAIPrompts(projectDir));
+  issues.push(...checkChainproofExists(projectDir));
+  issues.push(...checkChainproofIntegrity(projectDir));
+  issues.push(...checkChainproofUnsigned(projectDir));
 
   return issues.sort((a, b) => {
     const order = { critical: 0, warning: 1, info: 2 };
@@ -36,7 +46,7 @@ function checkClaudeMdLength(projectDir, scan) {
   return [{
     severity: lines > 500 ? 'critical' : 'warning',
     title: `CLAUDE.md is ${lines} lines (recommended limit: 150)`,
-    impact: 'Instructions are being dropped — Claude Code ignores rules randomly when context is too large',
+    impact: 'Instructions are being dropped. Claude Code ignores rules randomly when context is too large',
     files: ['CLAUDE.md'],
     autoFixable: false,
     promptId: 'CLAUDE_MD_TOO_LONG',
@@ -68,7 +78,7 @@ function checkUnauthEndpoints(projectDir, scan) {
             issues.push({
               severity: 'critical',
               title: `Unauthenticated endpoint: ${relPath}:${i + 1}`,
-              impact: 'Security vulnerability — data accessible without login',
+              impact: 'Security vulnerability, data accessible without login',
               files: [`${relPath}:${i + 1}`],
               autoFixable: false,
               promptId: 'UNAUTH_ENDPOINT',
@@ -86,11 +96,14 @@ function checkUnauthEndpoints(projectDir, scan) {
     const apiDir = path.join(projectDir, srcDir, 'app', 'api');
     if (!fs.existsSync(apiDir)) return issues;
 
-    const routeFiles = findFiles(apiDir, '.ts').concat(findFiles(apiDir, '.tsx'));
+    const routeFiles = findFiles(apiDir, '.ts').concat(findFiles(apiDir, '.tsx'))
+      .concat(findFiles(apiDir, '.js')).concat(findFiles(apiDir, '.jsx'));
     for (const file of routeFiles) {
-      if (path.basename(file) === 'route.ts' || path.basename(file) === 'route.tsx') {
+      const basename = path.basename(file);
+      if (basename === 'route.ts' || basename === 'route.tsx' ||
+          basename === 'route.js' || basename === 'route.jsx') {
         // Skip health endpoints
-        if (file.includes('/health/')) continue;
+        if (file.includes(`${path.sep}health${path.sep}`)) continue;
 
         const content = fs.readFileSync(file, 'utf-8');
         if (!content.includes('getServerSession') && !content.includes('auth(') &&
@@ -118,7 +131,7 @@ function checkUnauthEndpoints(projectDir, scan) {
     return [{
       severity,
       title: `${issues.length} endpoints have no authentication`,
-      impact: 'Security vulnerability — data accessible without login',
+      impact: 'Security vulnerability, data accessible without login',
       files: allFiles,
       autoFixable: false,
       promptId: 'UNAUTH_ENDPOINT',
@@ -161,7 +174,7 @@ function checkFlakyTestPatterns(projectDir) {
     issues.push({
       severity: 'critical',
       title: `${flakyFiles.length} tests use waitForTimeout() or hardcoded delays`,
-      impact: 'Tests fail randomly — unreliable CI',
+      impact: 'Tests fail randomly, which means unreliable CI',
       files: flakyFiles,
       autoFixable: false,
       promptId: 'FLAKY_TESTS',
@@ -191,7 +204,7 @@ function checkCrossDomainImports(projectDir, scan) {
         issues.push({
           severity: 'critical',
           title: `Cross-domain import: ${path.relative(projectDir, file)} imports from ${backendDir}`,
-          impact: 'Build will break or bundle server code into client — security risk',
+          impact: 'Build will break or bundle server code into client. This is a security risk',
           files: [path.relative(projectDir, file)],
           autoFixable: false,
           promptId: 'CROSS_DOMAIN_IMPORT',
@@ -206,7 +219,7 @@ function checkCrossDomainImports(projectDir, scan) {
     return [{
       severity: 'critical',
       title: `${issues.length} cross-domain imports (frontend importing backend or vice versa)`,
-      impact: 'Build will break or bundle server code into client — security risk',
+      impact: 'Build will break or bundle server code into client. This is a security risk',
       files: allFiles,
       autoFixable: false,
       promptId: 'CROSS_DOMAIN_IMPORT',
@@ -252,7 +265,7 @@ function checkBareExcepts(projectDir) {
   }];
 }
 
-function checkMissingHealthEndpoint(projectDir, scan) {
+function checkMissingHealthEndpoint(projectDir, _scan) {
   // Search for health endpoints by file path or content
   const patterns = ['/health', '/healthz', '/api/health'];
   const searchDirs = ['src', 'backend', 'app', 'frontend/src'];
@@ -286,7 +299,7 @@ function checkMissingHealthEndpoint(projectDir, scan) {
   }];
 }
 
-function checkMissingGracefulShutdown(projectDir, scan) {
+function checkMissingGracefulShutdown(projectDir, _scan) {
   const searchDirs = ['src', 'backend', 'app', 'frontend/src'];
   const signals = ['SIGTERM', 'SIGINT', 'process.on', 'signal.signal', 'lifespan'];
 
@@ -318,7 +331,7 @@ function checkMissingUAT(scan) {
   return [{
     severity: 'warning',
     title: 'No UAT scenarios',
-    impact: 'No formal acceptance criteria — features may not work as intended',
+    impact: 'No formal acceptance criteria, so features may not work as intended',
     files: [],
     autoFixable: false,
     promptId: 'MISSING_UAT',
@@ -340,7 +353,7 @@ function checkScatteredAPICalls(projectDir, scan) {
     // Skip files that ARE the API client
     if (['api.ts', 'api.js', 'apiClient.ts', 'apiClient.js', 'fetcher.ts', 'fetcher.js'].includes(basename)) continue;
     // Skip non-component files
-    if (file.includes('/lib/') || file.includes('/services/') || file.includes('/utils/')) continue;
+    if (file.includes(`${path.sep}lib${path.sep}`) || file.includes(`${path.sep}services${path.sep}`) || file.includes(`${path.sep}utils${path.sep}`)) continue;
 
     const content = fs.readFileSync(file, 'utf-8');
     if (/fetch\s*\(\s*['"`]\/api\//.test(content) || /fetch\s*\(\s*['"`]http/.test(content) ||
@@ -387,7 +400,7 @@ function checkLargeFiles(projectDir) {
 
   return [{
     severity: 'info',
-    title: `${largeFiles.length} files over 500 lines — candidates for splitting`,
+    title: `${largeFiles.length} files over 500 lines (candidates for splitting)`,
     impact: 'Large files are hard to navigate, review, and test',
     files: largeFiles.map(f => `${f.file} (${f.lines} lines)`),
     autoFixable: false,
@@ -406,7 +419,7 @@ function checkMissingScopedClaudeMd(projectDir, scan) {
   if (!fs.existsSync(path.join(projectDir, frontendDir, 'CLAUDE.md'))) {
     issues.push({
       severity: 'info',
-      title: `No ${frontendDir}/CLAUDE.md — frontend rules not scoped`,
+      title: `No ${frontendDir}/CLAUDE.md, frontend rules not scoped`,
       impact: 'Claude Code loads all rules even when working only on frontend',
       files: [],
       autoFixable: false,
@@ -418,7 +431,7 @@ function checkMissingScopedClaudeMd(projectDir, scan) {
   if (!fs.existsSync(path.join(projectDir, backendDir, 'CLAUDE.md'))) {
     issues.push({
       severity: 'info',
-      title: `No ${backendDir}/CLAUDE.md — backend rules not scoped`,
+      title: `No ${backendDir}/CLAUDE.md, backend rules not scoped`,
       impact: 'Claude Code loads all rules even when working only on backend',
       files: [],
       autoFixable: false,
@@ -430,11 +443,16 @@ function checkMissingScopedClaudeMd(projectDir, scan) {
   return issues;
 }
 
-function checkUnusedDependencies(projectDir, scan) {
+function checkUnusedDependencies(projectDir, _scan) {
   const pkgPath = path.join(projectDir, 'package.json');
   if (!fs.existsSync(pkgPath)) return [];
 
-  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  } catch {
+    return [];
+  }
   const deps = Object.keys(pkg.dependencies || {});
   if (deps.length === 0) return [];
 
@@ -526,7 +544,7 @@ function checkHardcodedValues(projectDir) {
   return [{
     severity: 'warning',
     title: `${hardcoded.length} hardcoded values that should be in environment variables`,
-    impact: 'Cannot change config without code changes — breaks deployment',
+    impact: 'Cannot change config without code changes, which breaks deployment',
     files: hardcoded,
     autoFixable: false,
     promptId: 'HARDCODED_VALUES',
@@ -709,7 +727,7 @@ function checkAIPrompts(projectDir) {
 
   return [{
     severity: 'info',
-    title: `${issues.length} files have inline AI prompts — consider a prompts file`,
+    title: `${issues.length} files have inline AI prompts. Consider a prompts file`,
     impact: 'Inline prompts are hard to version, test, and iterate on',
     files: issues,
     autoFixable: false,
@@ -741,3 +759,4 @@ function findFiles(dir, ext) {
 
   return results;
 }
+