@pcoliveira90/pdd 0.4.0 → 0.5.0

package/bin/pdd-ai.js

@@ -11,6 +11,10 @@ async function main() {
     console.log(`Provider: ${result.provider}`);
     console.log(`Task: ${result.task}`);
     console.log(`Model: ${result.model}`);
+    console.log(`Model selection: ${result.model_selection?.selected_automatically ? 'automatic' : 'user/fallback'}`);
+    if (result.model_selection?.note) {
+      console.log(`Selection note: ${result.model_selection.note}`);
+    }
     console.log(`Issue: ${result.issue}`);
     console.log('\nResult:\n');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pcoliveira90/pdd",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Patch-Driven Development CLI — safe, resilient and guided code changes",
   "type": "module",
   "bin": {

package/src/ai/model-router.js

@@ -0,0 +1,82 @@
+const TASK_ALIASES = {
+  analyze: 'analysis',
+  analysis: 'analysis',
+  recon: 'analysis',
+  build: 'build',
+  implement: 'build',
+  implementation: 'build',
+  test: 'test',
+  testing: 'test',
+  review: 'review',
+  security: 'review'
+};
+
+const PROVIDER_TASK_MODELS = {
+  openai: {
+    analysis: 'gpt-5',
+    build: 'gpt-5',
+    test: 'gpt-5-mini',
+    review: 'gpt-5'
+  },
+  claude: {
+    analysis: 'claude-sonnet-4-20250514',
+    build: 'claude-sonnet-4-20250514',
+    test: 'claude-sonnet-4-20250514',
+    review: 'claude-sonnet-4-20250514'
+  },
+  openrouter: {
+    analysis: 'anthropic/claude-3.5-sonnet',
+    build: 'openai/gpt-4.1',
+    test: 'openai/gpt-4.1-mini',
+    review: 'anthropic/claude-3.5-sonnet'
+  }
+};
+
+function normalizeTask(task) {
+  const key = String(task || 'analysis').trim().toLowerCase();
+  return TASK_ALIASES[key] || null;
+}
+
+export function resolveTaskModel({
+  provider,
+  task = 'analysis',
+  explicitModel = null,
+  fallbackModel
+}) {
+  if (explicitModel) {
+    return {
+      task: normalizeTask(task) || 'analysis',
+      model: explicitModel,
+      selectedAutomatically: false,
+      note: 'Using model explicitly provided by user.'
+    };
+  }
+
+  const normalizedTask = normalizeTask(task);
+  if (!normalizedTask) {
+    return {
+      task: 'analysis',
+      model: fallbackModel,
+      selectedAutomatically: false,
+      note: `Unknown task "${task}". Suggested fallback model selected.`
+    };
+  }
+
+  const providerMap = PROVIDER_TASK_MODELS[provider];
+  const model = providerMap?.[normalizedTask];
+  if (!model) {
+    return {
+      task: normalizedTask,
+      model: fallbackModel,
+      selectedAutomatically: false,
+      note: 'Automatic task model mapping unavailable for this provider. Suggested fallback model selected.'
+    };
+  }
+
+  return {
+    task: normalizedTask,
+    model,
+    selectedAutomatically: true,
+    note: 'Model selected automatically by task profile.'
+  };
+}

package/src/ai/run-fix-analysis.js

@@ -1,5 +1,6 @@
 import { buildBugfixPrompt } from './analyze-change.js';
 import { getAiProviderConfig } from './engine.js';
+import { resolveTaskModel } from './model-router.js';
 
 function extractArgValue(args, name, fallback = null) {
   const prefix = `${name}=`;
@@ -144,8 +145,15 @@ function parseJsonSafely(text) {
 export async function runAiFixAnalysis(argv = process.argv.slice(2)) {
   const provider = extractArgValue(argv, '--provider', 'openai');
   const providerConfig = getAiProviderConfig(provider);
-  const model = extractArgValue(argv, '--model', providerConfig.defaultModel);
+  const explicitModel = extractArgValue(argv, '--model', null);
   const task = extractArgValue(argv, '--task', 'analysis');
+  const modelSelection = resolveTaskModel({
+    provider,
+    task,
+    explicitModel,
+    fallbackModel: providerConfig.defaultModel
+  });
+  const model = modelSelection.model;
   const issue = getIssueFromArgs(argv);
 
   if (!issue) {
@@ -179,8 +187,12 @@ export async function runAiFixAnalysis(argv = process.argv.slice(2)) {
 
   return {
     provider,
-    task,
+    task: modelSelection.task,
     model,
+    model_selection: {
+      selected_automatically: modelSelection.selectedAutomatically,
+      note: modelSelection.note
+    },
     issue,
     result: parsed
   };

package/src/cli/index.js

@@ -1,7 +1,6 @@
 import { readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { spawnSync } from 'child_process';
 import { runValidation } from '../core/validator.js';
 import { openPullRequest } from '../core/pr-manager.js';
 import { generatePatchArtifacts } from '../core/patch-generator.js';
@@ -9,7 +8,13 @@ import { runInit } from './init-command.js';
 import { runDoctor } from './doctor-command.js';
 import { runStatus } from './status-command.js';
 import { runResilientFixWorkflow } from '../core/fix-runner.js';
-import { createLinkedWorktree, detectWorktreeContext } from '../core/worktree-guard.js';
+import {
+  analyzeStructuralImpact,
+  formatRiskSummary,
+  enforceStructuralRiskAck
+} from '../core/structural-risk-guard.js';
+import { runAutomaticGapCheck, formatGapCheckSummary } from '../core/gap-checker.js';
+import { maybeAutoRelocateToWorktree } from '../core/worktree-guard.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -20,6 +25,12 @@ function readCliVersion() {
 }
 
 function parseFixArgs(argv) {
+  const minCoverageArg = argv.find(arg => arg.startsWith('--min-coverage='));
+  const parsedMinCoverage = minCoverageArg ? Number(minCoverageArg.split('=')[1]) : null;
+  const minCoverage = Number.isFinite(parsedMinCoverage)
+    ? parsedMinCoverage
+    : Number(process.env.PDD_MIN_COVERAGE || 80);
+
   const issue = argv
     .filter(arg => !arg.startsWith('--') && arg !== 'fix')
     .join(' ')
@@ -30,48 +41,13 @@ function parseFixArgs(argv) {
     openPr: argv.includes('--open-pr'),
     dryRun: argv.includes('--dry-run'),
     noValidate: argv.includes('--no-validate'),
-    allowMainWorktree: argv.includes('--allow-main-worktree')
+    ackStructuralRisk: argv.includes('--ack-structural-risk'),
+    minCoverage,
+    requireCoverage: argv.includes('--require-coverage'),
+    noCoverageGate: argv.includes('--no-coverage-gate')
   };
 }
 
-function maybeAutoRelocateToWorktree({
-  cwd,
-  argv,
-  commandName,
-  enabled
-}) {
-  if (!enabled || argv.includes('--allow-main-worktree')) {
-    return false;
-  }
-
-  const context = detectWorktreeContext(cwd);
-  if (!context.isGitRepo || !context.isPrimaryWorktree) {
-    return false;
-  }
-
-  const { worktreePath, branchName } = createLinkedWorktree({
-    baseDir: cwd,
-    commandName
-  });
-
-  console.log(`🔀 Primary worktree detected. Auto-created linked worktree: ${worktreePath}`);
-  console.log(`🪴 Branch: ${branchName}`);
-  console.log('▶️ Continuing command in the new worktree...');
-
-  const result = spawnSync(
-    process.execPath,
-    [process.argv[1], ...argv],
-    { cwd: worktreePath, stdio: 'inherit' }
-  );
-
-  if (result.error) {
-    throw result.error;
-  }
-
-  process.exitCode = typeof result.status === 'number' ? result.status : 1;
-  return true;
-}
-
 export async function runCli(argv = process.argv.slice(2)) {
   const command = argv[0];
   const cwd = process.cwd();
@@ -82,28 +58,11 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
 
   if (command === 'init') {
-    const mutatesCurrentRepo = argv.includes('--here') || argv.includes('--upgrade');
-    if (maybeAutoRelocateToWorktree({
-      cwd,
-      argv,
-      commandName: 'init',
-      enabled: mutatesCurrentRepo
-    })) {
-      return;
-    }
     await runInit(argv);
     return;
   }
 
   if (command === 'doctor') {
-    if (maybeAutoRelocateToWorktree({
-      cwd,
-      argv,
-      commandName: 'doctor-fix',
-      enabled: argv.includes('--fix')
-    })) {
-      return;
-    }
     runDoctor(cwd, argv);
     return;
   }
@@ -114,38 +73,71 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
 
   if (command === 'fix') {
-    const { issue, openPr, dryRun, noValidate } = parseFixArgs(argv);
+    const relocated = maybeAutoRelocateToWorktree({
+      cwd,
+      argv,
+      commandName: 'fix'
+    });
+    if (relocated) return;
+
+    const {
+      issue,
+      openPr,
+      dryRun,
+      noValidate,
+      ackStructuralRisk,
+      minCoverage,
+      requireCoverage,
+      noCoverageGate
+    } = parseFixArgs(argv);
 
     if (!issue) {
       console.error('❌ Missing issue description.');
-      console.log('Use: pdd fix "description" [--open-pr] [--dry-run] [--no-validate] [--allow-main-worktree]');
+      console.log('Use: pdd fix "description" [--open-pr] [--dry-run] [--no-validate] [--ack-structural-risk] [--min-coverage=80] [--require-coverage] [--no-coverage-gate] [--allow-main-worktree]');
       process.exit(1);
     }
 
-    if (maybeAutoRelocateToWorktree({
-      cwd,
-      argv,
-      commandName: 'fix',
-      enabled: true
-    })) {
-      return;
-    }
-
     console.log('🔧 PDD Fix Workflow');
     console.log(`Issue: ${issue}`);
     console.log(`Open PR prep: ${openPr ? 'yes' : 'no'}`);
     console.log(`Dry run: ${dryRun ? 'yes' : 'no'}`);
     console.log(`Validation: ${noValidate ? 'skipped' : 'enabled'}`);
+    console.log(`Coverage gate: ${noCoverageGate ? 'disabled' : `enabled (min ${minCoverage}%)`}`);
+
+    const riskAssessment = analyzeStructuralImpact(issue);
+    console.log(formatRiskSummary(riskAssessment));
+    const gapCheck = runAutomaticGapCheck({
+      issue,
+      riskAssessment,
+      minCoverage
+    });
+    console.log(formatGapCheckSummary(gapCheck));
 
     try {
+      await enforceStructuralRiskAck({
+        assessment: riskAssessment,
+        ackFlag: ackStructuralRisk,
+        dryRun
+      });
+
       const result = await runResilientFixWorkflow({
         baseDir: cwd,
         issue,
         dryRun,
         noValidate,
         openPr,
-        generatePatchArtifacts,
-        runValidation,
+        generatePatchArtifacts: args =>
+          generatePatchArtifacts({
+            ...args,
+            riskAssessment,
+            gapCheck
+          }),
+        runValidation: targetBaseDir =>
+          runValidation(targetBaseDir, {
+            coverageGate: !noCoverageGate,
+            minCoverage,
+            requireCoverage
+          }),
         openPullRequest
       });
 
@@ -182,11 +174,12 @@ export async function runCli(argv = process.argv.slice(2)) {
     console.log('  pdd doctor [--fix]                                                Check installation health and optionally auto-repair');
     console.log('  pdd status                                                        Show current change workflow state');
     console.log('  pdd fix "description" [--open-pr] [--dry-run] [--no-validate]    Run fix workflow and generate artifacts');
+    console.log('      [--ack-structural-risk] [--min-coverage=80] [--require-coverage] [--no-coverage-gate] [--allow-main-worktree]');
     console.log('  pdd version   (or: pdd --version, pdd -v)                        Show CLI version');
     console.log('');
     console.log('Worktree policy:');
-    console.log('  Mutating commands auto-create and use a linked git worktree when needed.');
-    console.log('  Use --allow-main-worktree only if you intentionally want to run in primary.');
+    console.log('  Task execution auto-creates and uses a linked git worktree when needed.');
+    console.log('  Current scope: pdd fix. Use --allow-main-worktree to run in primary intentionally.');
     console.log('');
     console.log('AI command (official binary):');
     console.log('  pdd-ai [--provider=openai|claude|openrouter] [--task=analysis|build|test|review] [--model=<id>] "issue"');

package/src/core/gap-checker.js

@@ -0,0 +1,128 @@
+function hasAny(text, patterns) {
+  return patterns.some(pattern => pattern.test(text));
+}
+
+function mapTasks(issue, riskAssessment) {
+  const tasks = [
+    'Map current vs expected behavior',
+    'Confirm root cause',
+    'Define minimal safe delta',
+    'Define validation plan'
+  ];
+
+  if (riskAssessment?.hasHighRisk) {
+    tasks.push('Design structural mitigation and rollback plan');
+  }
+
+  return tasks;
+}
+
+export function runAutomaticGapCheck({ issue = '', riskAssessment = null, minCoverage = 80 }) {
+  const normalized = String(issue || '').toLowerCase();
+  const mappedTasks = mapTasks(normalized, riskAssessment);
+  const gaps = [];
+
+  const hasBusinessContext = hasAny(normalized, [
+    /\bregra\b/i,
+    /\bneg[oó]cio\b/i,
+    /\bpolicy\b/i,
+    /\bcrit[eé]rio\b/i,
+    /\baceita[cç][aã]o\b/i
+  ]);
+  if (!hasBusinessContext) {
+    gaps.push({
+      id: 'business-rules-context',
+      severity: 'high',
+      title: 'Business rules context is not explicit',
+      recommendation: 'Document business rules and acceptance criteria before implementation.'
+    });
+  }
+
+  const hasUsabilityContext = hasAny(normalized, [
+    /\busu[aá]rio\b/i,
+    /\bux\b/i,
+    /\busabilidade\b/i,
+    /\bfluxo\b/i,
+    /\bjornada\b/i,
+    /\binterface\b/i
+  ]);
+  if (!hasUsabilityContext) {
+    gaps.push({
+      id: 'usability-context',
+      severity: 'medium',
+      title: 'Usability impact is not explicit',
+      recommendation: 'Map affected journey and UI/interaction impact before implementation.'
+    });
+  }
+
+  const hasSecurityContext = hasAny(normalized, [
+    /\bsecurity\b/i,
+    /\bseguran[cç]a\b/i,
+    /\bauth\b/i,
+    /\bpermiss[aã]o\b/i,
+    /\bexposi[cç][aã]o\b/i,
+    /\bprivacidade\b/i
+  ]);
+  if (!hasSecurityContext) {
+    gaps.push({
+      id: 'security-context',
+      severity: 'medium',
+      title: 'Security impact is not explicit',
+      recommendation: 'Review auth, authorization, and data exposure risks for this change.'
+    });
+  }
+
+  const hasValidationContext = hasAny(normalized, [
+    /\btest\b/i,
+    /\bteste\b/i,
+    /\bvalida[cç][aã]o\b/i,
+    /\bqa\b/i
+  ]);
+  if (!hasValidationContext) {
+    gaps.push({
+      id: 'validation-plan',
+      severity: 'high',
+      title: 'Validation strategy is not explicit',
+      recommendation: `Define tests and minimum coverage target (currently ${minCoverage}%).`
+    });
+  }
+
+  if (riskAssessment?.hasHighRisk) {
+    const hasMitigationPlan = hasAny(normalized, [
+      /\brollback\b/i,
+      /\bmigration\b/i,
+      /\bcompatibil/i,
+      /\bbackward\b/i
+    ]);
+    if (!hasMitigationPlan) {
+      gaps.push({
+        id: 'structural-mitigation',
+        severity: 'critical',
+        title: 'Structural risk detected without mitigation details',
+        recommendation: 'Define migration strategy, compatibility approach, and rollback plan.'
+      });
+    }
+  }
+
+  const criticalCount = gaps.filter(gap => gap.severity === 'critical').length;
+  const highCount = gaps.filter(gap => gap.severity === 'high').length;
+
+  return {
+    mappedTasks,
+    gaps,
+    summary: {
+      total: gaps.length,
+      critical: criticalCount,
+      high: highCount,
+      status: gaps.length === 0 ? 'ok' : 'needs-review'
+    }
+  };
+}
+
+export function formatGapCheckSummary(gapCheck) {
+  if (!gapCheck || gapCheck.summary.total === 0) {
+    return 'Automatic gap check: no critical gaps detected.';
+  }
+
+  return `Automatic gap check: ${gapCheck.summary.total} gap(s) detected (${gapCheck.summary.critical} critical, ${gapCheck.summary.high} high).`;
+}

package/src/core/patch-generator.js

@@ -17,15 +17,138 @@ function slugify(value) {
     .replace(/^-+|-+$/g, '')
     .slice(0, 48);
 }
+function renderStructuralRiskSection(riskAssessment) {
+  if (!riskAssessment?.hasHighRisk) {
+    return 'No high structural impact signals detected from issue description.';
+  }
+
+  const lines = [];
+  for (const hit of riskAssessment.hits) {
+    lines.push(`- ${hit.label} (${hit.id})`);
+  }
+  return lines.join('\n');
+}
+
+function renderGapCheckSection(gapCheck) {
+  if (!gapCheck || gapCheck.summary.total === 0) {
+    return '- status: ok\n- notes: no automatic gaps detected';
+  }
+
+  const lines = [
+    `- status: ${gapCheck.summary.status}`,
+    `- total: ${gapCheck.summary.total}`,
+    `- critical: ${gapCheck.summary.critical}`,
+    `- high: ${gapCheck.summary.high}`
+  ];
+
+  for (const gap of gapCheck.gaps) {
+    lines.push(`- [${gap.severity}] ${gap.title}`);
+    lines.push(`  recommendation: ${gap.recommendation}`);
+  }
+
+  return lines.join('\n');
+}
+
+function renderMappedTasksSection(gapCheck) {
+  if (!gapCheck || !Array.isArray(gapCheck.mappedTasks) || gapCheck.mappedTasks.length === 0) {
+    return '- not available';
+  }
+
+  return gapCheck.mappedTasks.map(task => `- ${task}`).join('\n');
+}
+
+function writeWorkItemRecords({ baseDir, changeId, issue, gapCheck }) {
+  const recordsBase = path.join(baseDir, '.pdd', 'work-items');
+  const changeDir = path.join(recordsBase, 'changes', changeId);
+  const planDir = path.join(recordsBase, 'plans', changeId);
+  const featureDir = path.join(recordsBase, 'features');
+
+  writeFile(
+    path.join(changeDir, 'proposal.md'),
+    `# Change Proposal
+
+## Change ID
+${changeId}
+
+## Issue
+${issue}
 
-export function generatePatchArtifacts({ issue, baseDir = process.cwd(), changeId = null }) {
+## Proposed Solution (concise)
+
+## Why this is the minimal safe option
+
+## Validation with user
+- status: pending
+- feedback:
+
+## User edits to proposal
+`
+  );
+
+  writeFile(
+    path.join(changeDir, 'decision.md'),
+    `# Change Decision
+
+## Change ID
+${changeId}
+
+## Decision
+- approved: yes | no
+- approved_by:
+- approved_at:
+
+## Notes
+`
+  );
+
+  writeFile(
+    path.join(planDir, 'plan.md'),
+    `# Execution Plan
+
+## Change ID
+${changeId}
+
+## Mapped Tasks
+${renderMappedTasksSection(gapCheck)}
+
+## Planned Steps (concise)
+1.
+2.
+3.
+
+## Validation and Coverage
+- tests:
+- coverage target:
+`
+  );
+
+  writeFile(
+    path.join(featureDir, '.gitkeep'),
+    ''
+  );
+
+  return [
+    path.join('.pdd', 'work-items', 'changes', changeId, 'proposal.md'),
+    path.join('.pdd', 'work-items', 'changes', changeId, 'decision.md'),
+    path.join('.pdd', 'work-items', 'plans', changeId, 'plan.md')
+  ];
+}
+
+export function generatePatchArtifacts({
+  issue,
+  baseDir = process.cwd(),
+  changeId = null,
+  riskAssessment = null,
+  gapCheck = null
+}) {
   const resolvedChangeId = changeId || `change-${Date.now()}-${slugify(issue || 'update')}`;
   const changeDir = path.join(baseDir, 'changes', resolvedChangeId);
 
   const files = [
     path.join('changes', resolvedChangeId, 'delta-spec.md'),
     path.join('changes', resolvedChangeId, 'patch-plan.md'),
-    path.join('changes', resolvedChangeId, 'verification-report.md')
+    path.join('changes', resolvedChangeId, 'verification-report.md'),
+    path.join('changes', resolvedChangeId, 'gaps-report.md')
   ];
 
   writeFile(
@@ -55,6 +178,12 @@ bugfix | feature | refactor-safe | hotfix
 
 ## Constraints
 
+## Structural Impact Risks
+${renderStructuralRiskSection(riskAssessment)}
+
+## Automatic Gap Check
+${renderGapCheckSection(gapCheck)}
+
 ## Minimal Safe Delta
 
 ## Alternatives Considered
@@ -79,6 +208,9 @@ ${issue}
 
 ## Files to Change
 
+## Task Mapping
+${renderMappedTasksSection(gapCheck)}
+
 ## Execution Steps
 1. Reproduce issue
 2. Confirm root cause
@@ -88,6 +220,12 @@ ${issue}
 
 ## Regression Risks
 
+## Structural Impact Risks
+${renderStructuralRiskSection(riskAssessment)}
+
+## Automatic Gap Check
+${renderGapCheckSection(gapCheck)}
+
 ## Rollback Strategy
 `
   );
@@ -108,6 +246,11 @@ ${issue}
 
 ## Tests Run
 
+## Test Coverage
+- minimum threshold:
+- measured result:
+- status: pass | fail | not-available
+
 ## Manual Validation
 
 ## Residual Risks
@@ -117,6 +260,37 @@ pending
 `
   );
 
+  writeFile(
+    path.join(changeDir, 'gaps-report.md'),
+    `# Gaps Report
+
+## Change ID
+${resolvedChangeId}
+
+## Issue
+${issue}
+
+## Task Mapping
+${renderMappedTasksSection(gapCheck)}
+
+## Automatic Gap Check Summary
+${renderGapCheckSection(gapCheck)}
+
+## Reviewer Decision
+- approved: yes | no
+- notes:
+`
+  );
+
+  const workItemFiles = writeWorkItemRecords({
+    baseDir,
+    changeId: resolvedChangeId,
+    issue,
+    gapCheck
+  });
+
+  files.push(...workItemFiles);
+
   return {
     changeId: resolvedChangeId,
     changeDir,

package/src/core/structural-risk-guard.js

@@ -0,0 +1,120 @@
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+
+const STRUCTURAL_RISK_RULES = [
+  {
+    id: 'database-schema',
+    label: 'Database schema/data model changes',
+    patterns: [
+      /\bdatabase\b/i,
+      /\bdb\b/i,
+      /\bschema\b/i,
+      /\bmigration\b/i,
+      /\balter table\b/i,
+      /\bdrop table\b/i,
+      /\badd column\b/i,
+      /\bforeign key\b/i,
+      /\bprimary key\b/i,
+      /\bindex\b/i
+    ]
+  },
+  {
+    id: 'api-contract',
+    label: 'API/consumer contract changes',
+    patterns: [
+      /\bcontract\b/i,
+      /\bbreaking\b/i,
+      /\bapi\b/i,
+      /\bendpoint\b/i,
+      /\brequest\b/i,
+      /\bresponse\b/i,
+      /\bpayload\b/i,
+      /\bgraphql\b/i,
+      /\bopenapi\b/i
+    ]
+  },
+  {
+    id: 'integration-contract',
+    label: 'Event/message integration contract changes',
+    patterns: [
+      /\bevent\b/i,
+      /\bmessage\b/i,
+      /\btopic\b/i,
+      /\bqueue\b/i,
+      /\bkafka\b/i,
+      /\brabbitmq\b/i,
+      /\bsqs\b/i,
+      /\bsns\b/i
+    ]
+  }
+];
+
+export function analyzeStructuralImpact(issue = '') {
+  const text = String(issue || '');
+  const hits = [];
+
+  for (const rule of STRUCTURAL_RISK_RULES) {
+    const matchedPatterns = rule.patterns.filter(pattern => pattern.test(text)).map(pattern => pattern.source);
+    if (matchedPatterns.length > 0) {
+      hits.push({
+        id: rule.id,
+        label: rule.label,
+        evidence: matchedPatterns
+      });
+    }
+  }
+
+  return {
+    hasHighRisk: hits.length > 0,
+    hits
+  };
+}
+
+export function formatRiskSummary(assessment) {
+  if (!assessment?.hasHighRisk) {
+    return 'No high structural impact signals detected in issue description.';
+  }
+
+  const lines = ['High structural impact signals detected:'];
+  for (const hit of assessment.hits) {
+    lines.push(`- ${hit.label} (${hit.id})`);
+  }
+  return lines.join('\n');
+}
+
+async function askForAck() {
+  const rl = readline.createInterface({ input, output });
+  try {
+    console.log('');
+    console.log('⚠️ Structural-impact risk guard');
+    console.log('Type "STRUCTURAL_OK" to continue this fix workflow.');
+    const answer = await rl.question('> ');
+    return answer.trim() === 'STRUCTURAL_OK';
+  } finally {
+    rl.close();
+  }
+}
+
+export async function enforceStructuralRiskAck({
+  assessment,
+  ackFlag = false,
+  dryRun = false,
+  isInteractive = process.stdin.isTTY
+}) {
+  if (!assessment?.hasHighRisk || dryRun) {
+    return;
+  }
+
+  if (ackFlag) {
+    return;
+  }
+
+  if (isInteractive) {
+    const accepted = await askForAck();
+    if (accepted) return;
+  }
+
+  throw new Error(
+    'High structural-impact risk detected. Re-run with --ack-structural-risk after reviewing risks.'
+  );
+}

package/src/core/template-registry.js

@@ -1,4 +1,4 @@
-export const PDD_TEMPLATE_VERSION = '0.2.3';
+export const PDD_TEMPLATE_VERSION = '0.3.2';
 
 export const CORE_TEMPLATES = {
   '.pdd/constitution.md': `# PDD Constitution
@@ -24,8 +24,17 @@ Prefer existing patterns over new ones.
 ## 7. Verifiable Outcome
 Every change must be validated.
 
-## 8. Worktree First
-Always execute code changes from a linked git worktree, not from the primary worktree.
+## 8. Business Rule Integrity
+Never break core business rules while fixing or extending behavior.
+
+## 9. Usability First
+Every change must preserve or improve user experience and task flow.
+
+## 10. Security by Default
+Every change must evaluate security impact before implementation.
+
+## 11. Worktree First for Tasks
+When starting implementation tasks (for example, bug fixes), prefer a linked worktree over the primary worktree.
 `,
   '.pdd/templates/delta-spec.md': `# Delta Spec
 
@@ -48,6 +57,17 @@ bugfix | feature | refactor-safe | hotfix
 
 ## Constraints
 
+## Business Rules Impact
+
+## Usability Impact
+
+## Security Impact
+
+## Structural Impact Risks
+- database/schema/data migration impact
+- API/event contract compatibility impact
+- rollout/rollback complexity impact
+
 ## Minimal Safe Delta
 
 ## Alternatives Considered
@@ -71,6 +91,17 @@ bugfix | feature | refactor-safe | hotfix
 
 ## Regression Risks
 
+## Business Rules Risks
+
+## Usability Risks
+
+## Security Risks
+
+## Structural Impact Risks
+- database/schema/data migration impact
+- API/event contract compatibility impact
+- rollout/rollback complexity impact
+
 ## Rollback Strategy
 `,
   '.pdd/templates/verification-report.md': `# Verification Report
@@ -81,12 +112,40 @@ bugfix | feature | refactor-safe | hotfix
 
 ## Tests Run
 
+## Test Coverage
+- minimum threshold:
+- measured result:
+- status: pass | fail | not-available
+
+## Business Rule Validation
+
+## Usability Validation
+
+## Security Validation
+
 ## Manual Validation
 
 ## Residual Risks
 
 ## Final Status
 approved | needs-review | partial
+`,
+  '.pdd/templates/gaps-report.md': `# Gaps Report
+
+## Task Mapping
+
+## Automatic Gap Check Summary
+
+## Gaps by Severity
+- critical:
+- high:
+- medium:
+
+## Mitigation Plan
+
+## Reviewer Decision
+- approved: yes | no
+- notes:
 `,
   '.pdd/commands/pdd-recon.md': `# pdd.recon
 
@@ -171,6 +230,42 @@ Map the structure of the system.
 ## Hotspots
 - 
 `,
+  '.pdd/memory/model-routing.md': `# Model Routing
+
+## Goal
+Pick the most suitable AI model for each task type.
+
+## Task-to-Model Guidance
+- analysis/recon: prefer a more capable model for deep reasoning
+- implementation/build: prefer balanced model (quality + speed)
+- tests/coverage: prefer fast model for iterative feedback loops
+- review/risk/security: prefer a more capable model for edge cases
+
+## Decision Rule
+1. If model can be set automatically in this environment, set it by task type.
+2. If model cannot be set automatically, suggest the best model to the user.
+3. Ask for confirmation before continuing when model choice impacts quality/speed.
+
+## Output Requirement
+- chosen model profile
+- reason for choice
+- fallback suggested to user (if auto-selection is unavailable)
+`,
+  '.pdd/work-items/README.md': `# Work Items Registry
+
+PDD stores concise and editable records here:
+- plans/
+- changes/
+- features/
+
+Each change should include:
+- proposal (user can edit)
+- decision (approval and notes)
+- plan (execution and validation)
+`,
+  '.pdd/work-items/plans/.gitkeep': ``,
+  '.pdd/work-items/changes/.gitkeep': ``,
+  '.pdd/work-items/features/.gitkeep': ``,
   '.pdd/version.json': JSON.stringify({ templateVersion: PDD_TEMPLATE_VERSION }, null, 2) + '\n'
 };
 
@@ -254,7 +349,9 @@ This repo uses **PDD**: safe changes in existing systems. The agent should:
 - Prefer **minimal safe deltas**; avoid drive-by refactors.
 - Use templates under \`.pdd/templates/\` when producing specs or reports (\`delta-spec\`, \`patch-plan\`, \`verification-report\`).
 - Follow playbooks under \`.pdd/commands/\` when the user invokes a PDD slash command.
-- Use linked git worktrees for all mutating work. Avoid editing from the primary worktree.
+- For \`bugfix\` and \`feature\`, do not edit files before presenting context, business rules, risks, and plan, then waiting for explicit user approval.
+- Choose model by task type whenever possible (analysis/build/tests/review). If auto model switch is unavailable, suggest model to user and ask confirmation.
+- For implementation tasks, use linked git worktrees when needed (for example, \`pdd fix\`). Avoid changing code from primary worktree when auto-relocation is available.
 
 Slash commands live in \`.cursor/commands/\` (type \`/\` in Chat/Agent). They are the primary operational guidance for Cursor.
 `,
@@ -272,6 +369,7 @@ You are running **Patch-Driven Development** in this repository.
 - Obey \`.pdd/constitution.md\`.
 - Evidence before edits: locate behavior in code/tests before changing.
 - Smallest change that solves the problem; match local patterns.
+- For \`bugfix\` and \`feature\`, always stop for explicit user approval before any file edits.
 
 ## User request
 
@@ -281,15 +379,26 @@ $ARGUMENTS
 
 ## What to do
 
-1. Classify: bugfix vs feature vs exploration-only (**recon**).
-2. Name impacted files and risks.
-3. Propose a minimal plan, then implement or outline next steps.
-4. Say how to verify (tests, manual steps).
+1. Keep response concise and practical.
+2. Classify: bugfix vs feature vs recon.
+3. Map context + business rules (only essential points).
+4. Map key risks (regression, structural, usability, security).
+5. Run automatic gap check after task mapping.
+6. Present a concise proposal and ask the user to edit if needed.
+7. Ask explicit approval before any file edits.
+8. After approval, implement and validate.
 
 ## Output
 
-- Files touched or to touch
-- Risks and what you did not change on purpose
+Use this exact structure:
+1) Classification
+2) Context map
+3) Business rules
+4) Risks and structural impact
+5) Concise proposal (editable by user)
+6) Verification plan
+7) Automatic gap check
+8) Pending approval (explicit question)
 `,
     '.cursor/commands/pdd-recon.md': `---
 description: "PDD — recon (explore before editing)"
@@ -313,6 +422,7 @@ $ARGUMENTS
 - Short map: entry points, key modules, data flow if useful
 - List of files worth reading next
 - Risks and unknowns
+- Suggested model profile for next phase (analysis/build/tests/review)
 - No production edits unless the user explicitly asked to fix something
 `,
     '.cursor/commands/pdd-fix.md': `---
@@ -330,16 +440,44 @@ $ARGUMENTS
 
 ## Steps
 
+### Phase 1 — Investigation (no edits)
 1. Reproduce or infer current vs expected behavior (code/tests).
 2. Confirm root cause (not only symptoms).
-3. Apply the smallest fix; avoid scope creep.
-4. State how to verify (tests or manual).
+3. Map context (data flow, integrations, impacted modules/files).
+4. List business rules and constraints.
+5. Analyze usability impact (journeys, friction, discoverability).
+6. Analyze security impact (auth, authz, data exposure, abuse vectors).
+7. Build risk map (regression, data/contract, performance/ops, usability, security).
+   - Flag structural-impact actions explicitly (database/schema/migrations/contracts).
+8. Run automatic gap check immediately after task mapping and risk mapping.
+9. Present concise proposal and allow user edits.
+10. Ask explicit approval before editing files.
+
+### Phase 2 — Plan (no edits)
+11. Propose minimal safe delta and alternatives considered.
+12. Define verification plan (tests + manual checks + rollback).
+
+### Phase 3 — Execution (after approval)
+13. Implement approved minimal change.
+14. Validate and report residual risks.
 
 ## Output
 
-- Root cause (brief)
-- Files changed
-- Verification steps
+Use this exact structure:
+1) Current vs expected behavior
+2) Root cause
+3) Context map
+4) Business rules
+5) Risks and structural impact
+6) Concise proposal (editable by user)
+7) Verification + coverage plan
+8) Automatic gap check
+9) Pending approval (explicit question)
+
+After approval:
+10) Files changed
+11) Validation results
+12) Residual risks
 `,
     '.cursor/commands/pdd-feature.md': `---
 description: "PDD — feature (safe extension)"
@@ -356,16 +494,42 @@ $ARGUMENTS
 
 ## Steps
 
+### Phase 1 — Discovery (no edits)
 1. Understand current behavior and extension points.
-2. Define the smallest extension (APIs, files).
-3. Implement without breaking existing callers.
-4. Verification and rollback idea.
+2. Map context (user journey, modules/files, contracts, dependencies).
+3. List business rules and acceptance constraints.
+4. Analyze usability impact (journeys, accessibility, adoption friction).
+5. Analyze security impact (permissions, data exposure, misuse scenarios).
+6. Build risk map (compatibility, regression, data, performance, operational, usability, security).
+   - Flag structural-impact actions explicitly (database/schema/migrations/contracts).
+7. Run automatic gap check immediately after task mapping and risk mapping.
+8. Present concise proposal and allow user edits.
+9. Ask explicit approval before editing files.
+
+### Phase 2 — Plan (no edits)
+10. Define smallest safe extension and non-goals.
+11. Propose verification and rollback strategy.
+
+### Phase 3 — Execution (after approval)
+12. Implement approved scope.
+13. Validate compatibility and report residual risks.
 
 ## Output
 
-- Design note (what you extended and why)
-- Files changed
-- Tests or checks to run
+Use this exact structure:
+1) Feature scope
+2) Context map
+3) Business rules
+4) Risks and structural impact
+5) Concise proposal (editable by user)
+6) Verification + coverage + rollback plan
+7) Automatic gap check
+8) Pending approval (explicit question)
+
+After approval:
+9) Files changed
+10) Validation results
+11) Residual risks
 `,
     '.cursor/commands/pdd-verify.md': `---
 description: "PDD — verify (validation checklist)"
@@ -386,6 +550,7 @@ $ARGUMENTS
 - Regressions considered
 - Manual checks if needed
 - Residual risks
+- Model used for review and why
 
 ## Output
 

package/src/core/validator.js

@@ -6,7 +6,82 @@ function runCommand(command, baseDir) {
   execSync(command, { stdio: 'inherit', cwd: baseDir });
 }
 
-export function runValidation(baseDir = process.cwd()) {
+function resolveCoverageSummaryPath(baseDir) {
+  const candidates = [
+    `${baseDir}/coverage/coverage-summary.json`,
+    `${baseDir}/coverage/summary.json`
+  ];
+
+  return candidates.find(filePath => fs.existsSync(filePath)) || null;
+}
+
+function readCoverageMetrics(coverageSummaryPath) {
+  const raw = JSON.parse(fs.readFileSync(coverageSummaryPath, 'utf-8'));
+  const total = raw?.total || {};
+  const metrics = {
+    lines: Number(total?.lines?.pct),
+    statements: Number(total?.statements?.pct),
+    functions: Number(total?.functions?.pct),
+    branches: Number(total?.branches?.pct)
+  };
+
+  return Object.fromEntries(
+    Object.entries(metrics).filter(([, value]) => Number.isFinite(value))
+  );
+}
+
+function validateCoverage({
+  baseDir,
+  minCoverage = 80,
+  requireCoverage = false
+}) {
+  const summaryPath = resolveCoverageSummaryPath(baseDir);
+  if (!summaryPath) {
+    if (requireCoverage) {
+      throw new Error(
+        'Coverage report not found. Generate coverage (for example with npm run test:coverage) or disable this gate.'
+      );
+    }
+
+    console.log('⚠️ Coverage report not found. Skipping coverage gate.');
+    return;
+  }
+
+  const metrics = readCoverageMetrics(summaryPath);
+  const metricEntries = Object.entries(metrics);
+  if (metricEntries.length === 0) {
+    if (requireCoverage) {
+      throw new Error('Coverage summary is invalid or empty.');
+    }
+    console.log('⚠️ Coverage summary has no numeric metrics. Skipping coverage gate.');
+    return;
+  }
+
+  let minMetric = metricEntries[0];
+  for (const entry of metricEntries.slice(1)) {
+    if (entry[1] < minMetric[1]) {
+      minMetric = entry;
+    }
+  }
+
+  const [metricName, metricValue] = minMetric;
+  console.log(`Coverage (worst metric: ${metricName}) = ${metricValue.toFixed(2)}%`);
+  if (metricValue < minCoverage) {
+    throw new Error(
+      `Coverage gate failed: ${metricValue.toFixed(2)}% is below minimum ${minCoverage.toFixed(2)}%.`
+    );
+  }
+
+  console.log(`✅ Coverage gate passed (minimum ${minCoverage.toFixed(2)}%).`);
+}
+
+export function runValidation(baseDir = process.cwd(), options = {}) {
+  const {
+    coverageGate = true,
+    minCoverage = Number(process.env.PDD_MIN_COVERAGE || 80),
+    requireCoverage = false
+  } = options;
+
   console.log('Running validation...');
 
   const packageJsonPath = `${baseDir}/package.json`;
@@ -19,7 +94,11 @@ export function runValidation(baseDir = process.cwd()) {
   const scripts = pkg.scripts || {};
   const commands = [];
 
-  if (scripts.test) commands.push('npm test');
+  if (scripts['test:coverage']) {
+    commands.push('npm run test:coverage');
+  } else if (scripts.test) {
+    commands.push('npm test');
+  }
   if (scripts.lint) commands.push('npm run lint');
   if (scripts.build) commands.push('npm run build');
 
@@ -30,6 +109,13 @@ export function runValidation(baseDir = process.cwd()) {
 
   try {
     commands.forEach(command => runCommand(command, baseDir));
+    if (coverageGate) {
+      validateCoverage({
+        baseDir,
+        minCoverage,
+        requireCoverage
+      });
+    }
   } catch {
     throw new Error('Validation failed');
   }

package/src/core/worktree-guard.js

@@ -1,27 +1,37 @@
-import fs from 'fs';
-import { execSync, execFileSync } from 'child_process';
-import path from 'path';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 
-function runGit(command, baseDir) {
-  return execSync(command, { cwd: baseDir, stdio: 'pipe', encoding: 'utf-8' }).trim();
+function runGit(args, cwd) {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  }).trim();
 }
 
-function normalize(p) {
-  return path.resolve(String(p || '')).toLowerCase();
+function normalizePath(input) {
+  return path.resolve(String(input || '')).replace(/\\/g, '/').toLowerCase();
+}
+
+function slug(value, max = 40) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, max) || 'task';
 }
 
 export function detectWorktreeContext(baseDir = process.cwd()) {
   try {
-    const topLevel = runGit('git rev-parse --show-toplevel', baseDir);
-    const gitDir = runGit('git rev-parse --git-dir', baseDir);
-    const commonDir = runGit('git rev-parse --git-common-dir', baseDir);
-
-    const isPrimaryWorktree = normalize(gitDir) === normalize(commonDir);
+    const topLevel = runGit(['rev-parse', '--show-toplevel'], baseDir);
+    const gitDir = runGit(['rev-parse', '--git-dir'], baseDir);
+    const commonDir = runGit(['rev-parse', '--git-common-dir'], baseDir);
 
     return {
       isGitRepo: true,
       topLevel,
-      isPrimaryWorktree
+      isPrimaryWorktree: normalizePath(gitDir) === normalizePath(commonDir)
     };
   } catch {
     return {
@@ -32,14 +42,6 @@ export function detectWorktreeContext(baseDir = process.cwd()) {
   }
 }
 
-function slug(value) {
-  return String(value || '')
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .slice(0, 40);
-}
-
 export function createLinkedWorktree({
   baseDir = process.cwd(),
   commandName = 'change'
@@ -50,8 +52,8 @@ export function createLinkedWorktree({
   }
 
   const topLevel = context.topLevel;
-  const repoName = slug(path.basename(topLevel)) || 'repo';
-  const commandSlug = slug(commandName) || 'change';
+  const repoName = slug(path.basename(topLevel), 24);
+  const commandSlug = slug(commandName, 24);
   const stamp = Date.now();
   const branchName = `feature/pdd-auto-${commandSlug}-${stamp}`;
 
@@ -92,3 +94,31 @@ export function enforceLinkedWorktree({
 
   return context;
 }
+
+export function maybeAutoRelocateToWorktree({ cwd, argv, commandName }) {
+  if (argv.includes('--allow-main-worktree')) {
+    return false;
+  }
+
+  const context = detectWorktreeContext(cwd);
+  if (!context.isGitRepo || !context.isPrimaryWorktree) {
+    return false;
+  }
+
+  const { worktreePath, branchName } = createLinkedWorktree({
+    baseDir: cwd,
+    commandName
+  });
+
+  console.log('🔀 Primary worktree detected. Auto-created linked worktree for task execution.');
+  console.log(`- branch: ${branchName}`);
+  console.log(`- path: ${worktreePath}`);
+  console.log('');
+
+  execFileSync(process.execPath, [process.argv[1], ...argv], {
+    cwd: worktreePath,
+    stdio: 'inherit'
+  });
+
+  return true;
+}