@pcoliveira90/pdd 0.5.1 → 0.6.0

package/package.json

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

package/src/cli/index.js

@@ -13,7 +13,11 @@ import {
   formatRiskSummary,
   enforceStructuralRiskAck
 } from '../core/structural-risk-guard.js';
-import { runAutomaticGapCheck, formatGapCheckSummary } from '../core/gap-checker.js';
+import {
+  runAutomaticGapCheck,
+  formatGapCheckSummary,
+  formatBestPracticesSummary
+} from '../core/gap-checker.js';
 import { maybeAutoRelocateToWorktree } from '../core/worktree-guard.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -112,6 +116,7 @@ export async function runCli(argv = process.argv.slice(2)) {
       minCoverage
     });
     console.log(formatGapCheckSummary(gapCheck));
+    console.log(formatBestPracticesSummary(gapCheck));
 
     try {
       await enforceStructuralRiskAck({

package/src/core/gap-checker.js

@@ -17,6 +17,74 @@ function mapTasks(issue, riskAssessment) {
   return tasks;
 }
 
+function runBestPracticesSuggestions({ normalizedIssue, riskAssessment, minCoverage }) {
+  const suggestions = [];
+
+  const hasRollback = hasAny(normalizedIssue, [
+    /\brollback\b/i,
+    /\broll back\b/i,
+    /\bplano de volta\b/i,
+    /\bconting[eê]ncia\b/i
+  ]);
+  if (!hasRollback) {
+    suggestions.push({
+      id: 'bp-rollback-plan',
+      title: 'Define rollback plan before implementation',
+      proposal: 'Add a short rollback/contingency plan and get user approval before applying changes.',
+      requiresApproval: true
+    });
+  }
+
+  const hasMonitoring = hasAny(normalizedIssue, [
+    /\bmonitor(a[cç][aã]o|ing)\b/i,
+    /\bobservability\b/i,
+    /\blog(s)?\b/i,
+    /\bmetric(s)?\b/i,
+    /\btelemetry\b/i
+  ]);
+  if (!hasMonitoring) {
+    suggestions.push({
+      id: 'bp-observability',
+      title: 'Add observability checks',
+      proposal: 'Propose minimal logs/metrics verification for post-change validation and ask user approval.',
+      requiresApproval: true
+    });
+  }
+
+  if (riskAssessment?.hasHighRisk) {
+    const hasGradualRollout = hasAny(normalizedIssue, [
+      /\bfeature flag\b/i,
+      /\bcanary\b/i,
+      /\bgradual\b/i,
+      /\bstaged\b/i
+    ]);
+    if (!hasGradualRollout) {
+      suggestions.push({
+        id: 'bp-gradual-rollout',
+        title: 'Consider gradual rollout for structural-risk changes',
+        proposal: 'Propose feature-flag/canary rollout strategy and wait for explicit user agreement.',
+        requiresApproval: true
+      });
+    }
+  }
+
+  const hasCoverageTarget = hasAny(normalizedIssue, [
+    /\bcoverage\b/i,
+    /\bcobertura\b/i,
+    new RegExp(String(minCoverage))
+  ]);
+  if (!hasCoverageTarget) {
+    suggestions.push({
+      id: 'bp-coverage-target',
+      title: 'Set explicit coverage target in proposal',
+      proposal: `Propose explicit coverage target (minimum ${minCoverage}%) and confirm with user before implementation.`,
+      requiresApproval: true
+    });
+  }
+
+  return suggestions;
+}
+
 export function runAutomaticGapCheck({ issue = '', riskAssessment = null, minCoverage = 80 }) {
   const normalized = String(issue || '').toLowerCase();
   const mappedTasks = mapTasks(normalized, riskAssessment);
@@ -106,10 +174,23 @@ export function runAutomaticGapCheck({ issue = '', riskAssessment = null, minCov
 
   const criticalCount = gaps.filter(gap => gap.severity === 'critical').length;
   const highCount = gaps.filter(gap => gap.severity === 'high').length;
+  const bestPracticeSuggestions = runBestPracticesSuggestions({
+    normalizedIssue: normalized,
+    riskAssessment,
+    minCoverage
+  });
 
   return {
     mappedTasks,
     gaps,
+    bestPractices: {
+      mode: 'suggestion-only',
+      requiresApproval: true,
+      suggestions: bestPracticeSuggestions,
+      summary: {
+        total: bestPracticeSuggestions.length
+      }
+    },
     summary: {
       total: gaps.length,
       critical: criticalCount,
@@ -126,3 +207,20 @@ export function formatGapCheckSummary(gapCheck) {
 
   return `Automatic gap check: ${gapCheck.summary.total} gap(s) detected (${gapCheck.summary.critical} critical, ${gapCheck.summary.high} high).`;
 }
+
+export function formatBestPracticesSummary(gapCheck) {
+  const bestPractices = gapCheck?.bestPractices;
+  if (!bestPractices) {
+    return 'Best-practices check: unavailable.';
+  }
+
+  const count = bestPractices.summary?.total || 0;
+  if (count === 0) {
+    return 'Best-practices check (suggestion-only): no additional suggestions.';
+  }
+
+  return [
+    `Best-practices check (suggestion-only): ${count} suggestion(s).`,
+    'No suggestion should be applied automatically without explicit user approval.'
+  ].join('\n');
+}

package/src/core/patch-generator.js

@@ -49,6 +49,34 @@ function renderGapCheckSection(gapCheck) {
   return lines.join('\n');
 }
 
+function renderBestPracticesSection(gapCheck) {
+  const bestPractices = gapCheck?.bestPractices;
+  if (!bestPractices) {
+    return '- status: unavailable';
+  }
+
+  const suggestions = Array.isArray(bestPractices.suggestions)
+    ? bestPractices.suggestions
+    : [];
+
+  if (suggestions.length === 0) {
+    return '- mode: suggestion-only\n- suggestions: none';
+  }
+
+  const lines = [
+    '- mode: suggestion-only',
+    `- total suggestions: ${suggestions.length}`,
+    '- policy: do not apply any suggestion without explicit user approval'
+  ];
+
+  for (const item of suggestions) {
+    lines.push(`- ${item.title} (${item.id})`);
+    lines.push(`  proposal: ${item.proposal}`);
+  }
+
+  return lines.join('\n');
+}
+
 function renderMappedTasksSection(gapCheck) {
   if (!gapCheck || !Array.isArray(gapCheck.mappedTasks) || gapCheck.mappedTasks.length === 0) {
     return '- not available';
@@ -184,6 +212,9 @@ ${renderStructuralRiskSection(riskAssessment)}
 ## Automatic Gap Check
 ${renderGapCheckSection(gapCheck)}
 
+## Best-Practices Suggestions (Approval Required)
+${renderBestPracticesSection(gapCheck)}
+
 ## Minimal Safe Delta
 
 ## Alternatives Considered
@@ -226,6 +257,9 @@ ${renderStructuralRiskSection(riskAssessment)}
 ## Automatic Gap Check
 ${renderGapCheckSection(gapCheck)}
 
+## Best-Practices Suggestions (Approval Required)
+${renderBestPracticesSection(gapCheck)}
+
 ## Rollback Strategy
 `
   );
@@ -276,6 +310,9 @@ ${renderMappedTasksSection(gapCheck)}
 ## Automatic Gap Check Summary
 ${renderGapCheckSection(gapCheck)}
 
+## Best-Practices Suggestions (Approval Required)
+${renderBestPracticesSection(gapCheck)}
+
 ## Reviewer Decision
 - approved: yes | no
 - notes:

package/src/core/template-registry.js

@@ -68,6 +68,11 @@ bugfix | feature | refactor-safe | hotfix
 - API/event contract compatibility impact
 - rollout/rollback complexity impact
 
+## Best-Practices Suggestions (Approval Required)
+- suggestion-only mode
+- proposal first
+- explicit user approval required before applying
+
 ## Minimal Safe Delta
 
 ## Alternatives Considered
@@ -102,6 +107,11 @@ bugfix | feature | refactor-safe | hotfix
 - API/event contract compatibility impact
 - rollout/rollback complexity impact
 
+## Best-Practices Suggestions (Approval Required)
+- suggestion-only mode
+- proposal first
+- explicit user approval required before applying
+
 ## Rollback Strategy
 `,
   '.pdd/templates/verification-report.md': `# Verification Report
@@ -136,6 +146,11 @@ approved | needs-review | partial
 
 ## Automatic Gap Check Summary
 
+## Best-Practices Suggestions (Approval Required)
+- suggestion-only mode
+- proposals:
+- approved to apply: yes | no
+
 ## Gaps by Severity
 - critical:
 - high:
@@ -384,9 +399,10 @@ $ARGUMENTS
 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.
+6. Run best-practices check in suggestion-only mode.
+7. Present concise proposal (including selected suggestions) and ask the user to edit if needed.
+8. Ask explicit approval before any file edits or suggestions application.
+9. After approval, implement and validate.
 
 ## Output
 
@@ -398,7 +414,8 @@ Use this exact structure:
 5) Concise proposal (editable by user)
 6) Verification plan
 7) Automatic gap check
-8) Pending approval (explicit question)
+8) Best-practices suggestions (proposal-only)
+9) Pending approval (explicit question)
 `,
     '.cursor/commands/pdd-recon.md': `---
 description: "PDD — recon (explore before editing)"
@@ -450,16 +467,17 @@ $ARGUMENTS
 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.
+9. Run best-practices check in suggestion-only mode.
+10. Present concise proposal and allow user edits.
+11. Ask explicit approval before editing files or applying suggestions.
 
 ### Phase 2 — Plan (no edits)
-11. Propose minimal safe delta and alternatives considered.
-12. Define verification plan (tests + manual checks + rollback).
+12. Propose minimal safe delta and alternatives considered.
+13. Define verification plan (tests + manual checks + rollback).
 
 ### Phase 3 — Execution (after approval)
-13. Implement approved minimal change.
-14. Validate and report residual risks.
+14. Implement approved minimal change.
+15. Validate and report residual risks.
 
 ## Output
 
@@ -472,12 +490,13 @@ Use this exact structure:
 6) Concise proposal (editable by user)
 7) Verification + coverage plan
 8) Automatic gap check
-9) Pending approval (explicit question)
+9) Best-practices suggestions (proposal-only)
+10) Pending approval (explicit question)
 
 After approval:
-10) Files changed
-11) Validation results
-12) Residual risks
+11) Files changed
+12) Validation results
+13) Residual risks
 `,
     '.cursor/commands/pdd-feature.md': `---
 description: "PDD — feature (safe extension)"
@@ -503,16 +522,17 @@ $ARGUMENTS
 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.
+8. Run best-practices check in suggestion-only mode.
+9. Present concise proposal and allow user edits.
+10. Ask explicit approval before editing files or applying suggestions.
 
 ### Phase 2 — Plan (no edits)
-10. Define smallest safe extension and non-goals.
-11. Propose verification and rollback strategy.
+11. Define smallest safe extension and non-goals.
+12. Propose verification and rollback strategy.
 
 ### Phase 3 — Execution (after approval)
-12. Implement approved scope.
-13. Validate compatibility and report residual risks.
+13. Implement approved scope.
+14. Validate compatibility and report residual risks.
 
 ## Output
 
@@ -524,12 +544,13 @@ Use this exact structure:
 5) Concise proposal (editable by user)
 6) Verification + coverage + rollback plan
 7) Automatic gap check
-8) Pending approval (explicit question)
+8) Best-practices suggestions (proposal-only)
+9) Pending approval (explicit question)
 
 After approval:
-9) Files changed
-10) Validation results
-11) Residual risks
+10) Files changed
+11) Validation results
+12) Residual risks
 `,
     '.cursor/commands/pdd-verify.md': `---
 description: "PDD — verify (validation checklist)"