pan-wizard 3.12.5 → 3.14.0

package/pan-wizard-core/bin/lib/verify.cjs

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
-const { safeReadFile, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, toPosix, output, error } = require('./core.cjs');
+const { safeReadFile, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, toPosix, output, error, escapeRegex } = require('./core.cjs');
 const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
 const { writeStateMd, readStateSafe } = require('./state.cjs');
 const {
@@ -317,32 +317,22 @@ function cmdVerifyCommits(cwd, hashes, raw) {
  * @param {boolean} raw - If true, output raw value instead of JSON
  * @returns {void}
  */
-function cmdVerifyArtifacts(cwd, planFilePath, raw) {
-  if (!planFilePath) { error('plan file path required'); }
-  const fullPath = path.isAbsolute(planFilePath) ? planFilePath : path.join(cwd, planFilePath);
-  const content = safeReadFile(fullPath);
-  if (!content) { output({ error: 'File not found', path: planFilePath }, raw); return; }
-
-  const artifacts = parseMustHavesBlock(content, 'artifacts');
-  if (artifacts.length === 0) {
-    output({ error: 'No must_haves.artifacts found in frontmatter', path: planFilePath }, raw);
-    return;
-  }
-
+/**
+ * Pure substance check of must_haves.artifacts against disk — no output/exit,
+ * so `verify reconcile` can compose it. Returns {all_passed, passed, total, artifacts}.
+ */
+function checkArtifacts(cwd, planContent) {
+  const artifacts = parseMustHavesBlock(planContent, 'artifacts');
   const results = [];
   for (const artifact of artifacts) {
     if (typeof artifact === 'string') continue; // skip simple string items
     const artPath = artifact.path;
     if (!artPath) continue;
-
-    const artFullPath = path.join(cwd, artPath);
-    const fileContent = safeReadFile(artFullPath);
+    const fileContent = safeReadFile(path.join(cwd, artPath));
     const exists = fileContent !== null;
     const check = { path: artPath, exists, issues: [], passed: false };
-
     if (exists) {
       const lineCount = fileContent.split('\n').length;
-
       if (artifact.min_lines && lineCount < artifact.min_lines) {
         check.issues.push(`Only ${lineCount} lines, need ${artifact.min_lines}`);
       }
@@ -350,8 +340,8 @@ function cmdVerifyArtifacts(cwd, planFilePath, raw) {
         check.issues.push(`Missing pattern: ${artifact.contains}`);
       }
       if (artifact.exports) {
-        const exports = Array.isArray(artifact.exports) ? artifact.exports : [artifact.exports];
-        for (const exp of exports) {
+        const exps = Array.isArray(artifact.exports) ? artifact.exports : [artifact.exports];
+        for (const exp of exps) {
           if (!fileContent.includes(exp)) check.issues.push(`Missing export: ${exp}`);
         }
       }
@@ -359,43 +349,42 @@ function cmdVerifyArtifacts(cwd, planFilePath, raw) {
     } else {
       check.issues.push('File not found');
     }
-
     results.push(check);
   }
-
   const passed = results.filter(r => r.passed).length;
-  output({
-    all_passed: passed === results.length,
-    passed,
-    total: results.length,
-    artifacts: results,
-  }, raw, passed === results.length ? 'valid' : 'invalid');
+  return { all_passed: passed === results.length, passed, total: results.length, artifacts: results };
 }
 
-/**
- * Verify must_haves.key_links from a plan.md: source-to-target references and patterns.
- * @param {string} cwd - Working directory path
- * @param {string} planFilePath - Path to the plan.md file containing key link specs
- * @param {boolean} raw - If true, output raw value instead of JSON
- * @returns {void}
- */
-function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
+function cmdVerifyArtifacts(cwd, planFilePath, raw) {
   if (!planFilePath) { error('plan file path required'); }
   const fullPath = path.isAbsolute(planFilePath) ? planFilePath : path.join(cwd, planFilePath);
   const content = safeReadFile(fullPath);
   if (!content) { output({ error: 'File not found', path: planFilePath }, raw); return; }
-
-  const keyLinks = parseMustHavesBlock(content, 'key_links');
-  if (keyLinks.length === 0) {
-    output({ error: 'No must_haves.key_links found in frontmatter', path: planFilePath }, raw);
+  const r = checkArtifacts(cwd, content);
+  if (r.total === 0) {
+    output({ error: 'No must_haves.artifacts found in frontmatter', path: planFilePath }, raw);
     return;
   }
+  output(r, raw, r.all_passed ? 'valid' : 'invalid');
+}
 
+/**
+ * Verify must_haves.key_links from a plan.md: source-to-target references and patterns.
+ * @param {string} cwd - Working directory path
+ * @param {string} planFilePath - Path to the plan.md file containing key link specs
+ * @param {boolean} raw - If true, output raw value instead of JSON
+ * @returns {void}
+ */
+/**
+ * Pure wiring check of must_haves.key_links against disk — no output/exit.
+ * Returns {all_verified, verified, total, links}.
+ */
+function checkKeyLinks(cwd, planContent) {
+  const keyLinks = parseMustHavesBlock(planContent, 'key_links');
   const results = [];
   for (const link of keyLinks) {
     if (typeof link === 'string') continue;
     const check = { from: link.from, to: link.to, via: link.via || '', verified: false, detail: '' };
-
     const sourceContent = safeReadFile(path.join(cwd, link.from || ''));
     if (!sourceContent) {
       check.detail = 'Source file not found';
@@ -415,29 +404,142 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
           }
         }
       } catch {
-        // Regex compilation failed -- report the invalid pattern to the caller
         check.detail = `Invalid regex pattern: ${link.pattern}`;
       }
+    } else if (sourceContent.includes(link.to || '')) {
+      check.verified = true;
+      check.detail = 'Target referenced in source';
     } else {
-      // No pattern: just check source references target
-      if (sourceContent.includes(link.to || '')) {
-        check.verified = true;
-        check.detail = 'Target referenced in source';
-      } else {
-        check.detail = 'Target not referenced in source';
-      }
+      check.detail = 'Target not referenced in source';
     }
-
     results.push(check);
   }
-
   const verified = results.filter(r => r.verified).length;
-  output({
-    all_verified: verified === results.length,
-    verified,
-    total: results.length,
-    links: results,
-  }, raw, verified === results.length ? 'valid' : 'invalid');
+  return { all_verified: verified === results.length, verified, total: results.length, links: results };
+}
+
+function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
+  if (!planFilePath) { error('plan file path required'); }
+  const fullPath = path.isAbsolute(planFilePath) ? planFilePath : path.join(cwd, planFilePath);
+  const content = safeReadFile(fullPath);
+  if (!content) { output({ error: 'File not found', path: planFilePath }, raw); return; }
+  const r = checkKeyLinks(cwd, content);
+  if (r.total === 0) {
+    output({ error: 'No must_haves.key_links found in frontmatter', path: planFilePath }, raw);
+    return;
+  }
+  output(r, raw, r.all_verified ? 'valid' : 'invalid');
+}
+
+// ─── Reconcile: cross-check a written verification verdict against the
+// mechanical signals (ADR-0036 review — closes the rubber-stamp gap). ─────────
+
+function findPhaseDir(cwd, phaseNum) {
+  const base = phasesPath(cwd);
+  let entries;
+  try { entries = fs.readdirSync(base, { withFileTypes: true }); } catch { return null; }
+  const re = new RegExp('^0*' + String(phaseNum).replace(/[^0-9A-Za-z.]/g, '') + '-');
+  for (const e of entries) {
+    if (e.isDirectory() && re.test(e.name)) return path.join(base, e.name);
+  }
+  return null;
+}
+
+/**
+ * Re-derive the mechanical signals for a phase and check them against the
+ * verdict written in its -verification.md. A verification that CLAIMS a pass
+ * while artifacts fail substance checks or key-links are unwired is a
+ * contradiction (a rubber stamp) — reported deterministically, never trusted.
+ * When no must_haves are declared there are no mechanical signals to reconcile,
+ * so the verdict is passed through (reconciled: true, with a note).
+ */
+function reconcilePhase(cwd, phaseNum) {
+  const base = { phase: String(phaseNum), found: false, reconciled: true, contradictions: [] };
+  const dir = findPhaseDir(cwd, phaseNum);
+  if (!dir) return { ...base, note: 'phase directory not found' };
+  let files;
+  try { files = fs.readdirSync(dir); } catch { return { ...base, note: 'phase directory unreadable' }; }
+  const verFile = files.find(f => isVerificationFile(f));
+  if (!verFile) return { ...base, note: 'no verification.md — absence is covered by the verification gate, not reconcile' };
+  const verRaw = safeReadFile(path.join(dir, verFile)) || '';
+  const sm = verRaw.match(/^status:\s*([A-Za-z_-]+)/m);
+  const status = sm ? sm[1].toLowerCase() : 'unknown';
+  const claimsPass = /^(pass|passed|verified|complete|verified_pass)$/.test(status);
+  const planFile = files.find(f => isPlanFile(f));
+  const planContent = planFile ? (safeReadFile(path.join(dir, planFile)) || '') : '';
+  const artifacts = checkArtifacts(cwd, planContent);
+  const keyLinks = checkKeyLinks(cwd, planContent);
+  const signals = artifacts.total + keyLinks.total;
+  const contradictions = [];
+  if (claimsPass) {
+    if (artifacts.total > 0 && !artifacts.all_passed) {
+      contradictions.push(`verification status "${status}" but ${artifacts.total - artifacts.passed}/${artifacts.total} artifact substance check(s) FAIL`);
+    }
+    if (keyLinks.total > 0 && !keyLinks.all_verified) {
+      contradictions.push(`verification status "${status}" but ${keyLinks.total - keyLinks.verified}/${keyLinks.total} key-link(s) UNWIRED`);
+    }
+  }
+  return {
+    phase: String(phaseNum), found: true, verification_status: status, claims_pass: claimsPass,
+    mechanical_signals: signals, artifacts, key_links: keyLinks, contradictions,
+    reconciled: contradictions.length === 0,
+    note: signals === 0 ? 'no must_haves declared — mechanical reconciliation unavailable; verdict trusted' : undefined,
+  };
+}
+
+function cmdVerifyReconcile(cwd, phaseNum, raw) {
+  if (!phaseNum) { error('Usage: verify reconcile <phase>'); }
+  const r = reconcilePhase(cwd, phaseNum);
+  output(r, raw, r.reconciled ? 'valid' : 'invalid');
+  process.exit(r.reconciled ? 0 : 1);
+}
+
+// ─── Stub / fake-return scanner (ADR-0036 review — closes the hardcoded
+// "return {ok:true}" / "not implemented" gap the old anti-pattern grep missed,
+// which only blocked the literal `return {}` and `placeholder`/`coming soon`). ─
+const STUB_PATTERNS = [
+  { re: /\bnot[\s_-]?implemented\b/i, marker: 'not-implemented', severity: 'high' },
+  { re: /\bNotImplemented(Error)?\b/, marker: 'NotImplemented', severity: 'high' },
+  { re: /throw\s+new\s+\w*Error\s*\(\s*['"`][^'"`]*\b(unimplemented|not\s+implemented|stub|todo)\b/i, marker: 'throw-stub', severity: 'high' },
+  { re: /\bres(ponse)?\.status\(\s*501\s*\)/, marker: 'http-501', severity: 'high' },
+  { re: /\b(coming\s+soon|placeholder)\b/i, marker: 'placeholder', severity: 'medium' },
+  { re: /return\s*(\{\s*\}|\[\s*\])\s*;?\s*(\/\/.*)?$/, marker: 'empty-return', severity: 'medium' },
+  { re: /return\s*\{\s*ok\s*:\s*true\s*\}\s*;?\s*(\/\/.*)?$/, marker: 'fake-ok-return', severity: 'medium' },
+  { re: /\b(TODO|FIXME|XXX|HACK)\b/, marker: 'todo-marker', severity: 'low' },
+];
+const STUB_CODE_EXT = /\.(js|cjs|mjs|jsx|ts|tsx|py|go|rb|java|php|rs|c|cc|cpp|h|hpp|cs|kt|swift|scala)$/i;
+
+/**
+ * Scan source files for stub / fake-implementation markers. Defaults to the
+ * git-changed files (so it gates a handoff), or a caller-supplied file list.
+ * `high`-severity markers are the blocking set; TODO markers are informational.
+ * @returns {{scanned, findings: Array, blocking: number, total: number}}
+ */
+function scanStubs(cwd, opts = {}) {
+  let files = Array.isArray(opts.files) ? opts.files : getChangedFiles(cwd);
+  files = (files || []).filter(f => STUB_CODE_EXT.test(f));
+  const findings = [];
+  for (const rel of files) {
+    const content = safeReadFile(path.join(cwd, rel));
+    if (content === null) continue;
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      for (const { re, marker, severity } of STUB_PATTERNS) {
+        if (re.test(lines[i])) {
+          findings.push({ file: toPosix(rel), line: i + 1, marker, severity, text: lines[i].trim().slice(0, 160) });
+          break; // one finding per line
+        }
+      }
+    }
+  }
+  const blocking = findings.filter(f => f.severity === 'high').length;
+  return { scanned: files.length, findings, blocking, total: findings.length };
+}
+
+function cmdVerifyStubs(cwd, opts = {}, raw) {
+  const r = scanStubs(cwd, opts);
+  output(r, raw, r.blocking === 0 ? 'valid' : 'invalid');
+  if (opts.gate) process.exit(r.blocking > 0 ? 1 : 0);
 }
 
 /**
@@ -995,12 +1097,12 @@ function syncRequirementCheckboxes(cwd) {
   let fixed = 0;
   for (const phaseNum of completedPhases) {
     const reqMatch = roadmapContent.match(
-      new RegExp(`Phase\\s+${phaseNum.replace(/\./g, '\\.')}[\\s\\S]*?\\*\\*Requirements:\\*\\*\\s*([^\\n]+)`, 'i')
+      new RegExp(`Phase\\s+${escapeRegex(phaseNum)}[\\s\\S]*?\\*\\*Requirements:\\*\\*\\s*([^\\n]+)`, 'i')
     );
     if (!reqMatch) continue;
     const reqIds = reqMatch[1].replace(/[\[\]]/g, '').split(/[,\s]+/).map(id => id.trim()).filter(Boolean);
     for (const reqId of reqIds) {
-      const escaped = reqId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const escaped = escapeRegex(reqId);
       const re = new RegExp(`(- \\[) (\\]\\s*\\*\\*${escaped}\\*\\*)`, 'gi');
       const before = reqContent;
       reqContent = reqContent.replace(re, '$1x$2');
@@ -1186,6 +1288,7 @@ function cmdValidateHealth(cwd, options, raw) {
   // Check 10 (optional): full validation — run tests and build
   let testStatus;
   let buildStatus;
+  let memoryBudget;
   if (options.full) {
     testStatus = runFullTestCheck(cwd);
     buildStatus = runFullBuildCheck(cwd);
@@ -1195,6 +1298,14 @@ function cmdValidateHealth(cwd, options, raw) {
     if (buildStatus.pass === false) {
       addIssue('error', 'BUILD_FAIL', `Build failed (exit code ${buildStatus.exitCode})`, 'Fix build errors');
     }
+    // Memory-load budget (ADR-0036 acceptance signal): keep per-agent memory
+    // injection bounded as logs grow. Read-only, non-blocking.
+    memoryBudget = require('./memory.cjs').memoryLoadBudget(cwd);
+    if (memoryBudget.status === 'critical') {
+      addIssue('warning', 'MEM_BUDGET', memoryBudget.advisory, "Run 'pan-tools memory compact <agent>' or scope injection with 'memory select'");
+    } else if (memoryBudget.status === 'warning') {
+      addIssue('info', 'MEM_BUDGET', memoryBudget.advisory, "Run 'pan-tools memory compact <agent>' or scope injection with 'memory select'");
+    }
   }
 
   // Determine overall status from error/warning counts
@@ -1252,6 +1363,7 @@ function cmdValidateHealth(cwd, options, raw) {
   if (options.full) {
     result.test_status = testStatus;
     result.build_status = buildStatus;
+    result.memory_budget = memoryBudget;
   }
   if (options.drift) {
     result.drift_status = driftResult;
@@ -1274,8 +1386,11 @@ function runFullTestCheck(cwd) {
       stdio: ['pipe', 'pipe', 'pipe'],
       encoding: 'utf-8',
     });
-    const testMatch = result.match(/# tests (\d+)/);
-    const passMatch = result.match(/# pass (\d+)/);
+    // Match both TAP ("# tests N") and spec-reporter ("ℹ tests N") summaries —
+    // modern node --test defaults to the spec reporter, which the old "# "-only
+    // regex silently missed (returning tests: null).
+    const testMatch = result.match(/[#ℹ]\s*tests\s+(\d+)/);
+    const passMatch = result.match(/[#ℹ]\s*pass\s+(\d+)/);
     return {
       pass: true,
       exitCode: 0,
@@ -1334,6 +1449,12 @@ module.exports = {
   cmdVerifyCommits,
   cmdVerifyArtifacts,
   cmdVerifyKeyLinks,
+  checkArtifacts,
+  checkKeyLinks,
+  reconcilePhase,
+  cmdVerifyReconcile,
+  scanStubs,
+  cmdVerifyStubs,
   cmdValidateConsistency,
   cmdValidateHealth,
   cmdPreflight,

package/pan-wizard-core/bin/pan-tools.cjs

@@ -205,6 +205,8 @@ const cost = require('./lib/cost.cjs');
 const preview = require('./lib/preview.cjs');
 const reviewDeep = require('./lib/review-deep.cjs');
 const knowledge = require('./lib/knowledge.cjs');
+const skillAlign = require('./lib/skill-align.cjs');
+const hygiene = require('./lib/hygiene.cjs');
 const whatif = require('./lib/whatif.cjs');
 const bridge = require('./lib/bridge.cjs');
 const optimize = require('./lib/optimize.cjs');
@@ -522,6 +524,10 @@ async function main() {
         verify.cmdVerifyArtifacts(cwd, args[2], raw);
       } else if (subcommand === 'key-links') {
         verify.cmdVerifyKeyLinks(cwd, args[2], raw);
+      } else if (subcommand === 'reconcile') {
+        verify.cmdVerifyReconcile(cwd, args[2], raw);
+      } else if (subcommand === 'stubs') {
+        verify.cmdVerifyStubs(cwd, { gate: args.includes('--gate') }, raw);
       } else {
         error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links');
       }
@@ -910,8 +916,16 @@ async function main() {
         memory.cmdMemoryList(cwd, raw);
       } else if (subcommand === 'compact') {
         memory.cmdMemoryCompact(cwd, args[2], args[3], raw);
+      } else if (subcommand === 'select') {
+        memory.cmdMemorySelect(cwd, args[2], {
+          cue: getArgValue(args, '--cue'),
+          tokenBudget: getArgValue(args, '--token-budget'),
+          recencyFloor: getArgValue(args, '--recency-floor'),
+        }, raw);
+      } else if (subcommand === 'budget') {
+        memory.cmdMemoryBudget(cwd, raw);
       } else {
-        error('Unknown memory subcommand. Available: read, append, list, compact');
+        error('Unknown memory subcommand. Available: read, append, list, compact, select, budget');
       }
       break;
     }
@@ -970,6 +984,7 @@ async function main() {
         const maxSources = getArgValue(args, '--max-sources');
         knowledge.cmdKnowledgeAsk(cwd, question, {
           max_sources: maxSources ? Number(maxSources) : undefined,
+          recall_cue: getArgValue(args, '--recall-cue'),
         }, raw);
       } else if (subcommand === 'discuss') {
         const phaseNum = args[2];
@@ -989,6 +1004,41 @@ async function main() {
       break;
     }
 
+    case 'skills': {
+      const subcommand = args[1];
+      const skillRoot = getArgValue(args, '--source-root') || skillAlign.resolveSkillRoot();
+      if (subcommand === 'index') {
+        skillAlign.cmdSkillsIndex(skillRoot, raw);
+      } else if (subcommand === 'align') {
+        skillAlign.cmdSkillsAlign(skillRoot, {
+          draft: getArgValue(args, '--draft'),
+          draftFile: getArgValue(args, '--draft-file'),
+          topK: getArgValue(args, '--top'),
+          minScore: getArgValue(args, '--min-score'),
+          tokenBudget: getArgValue(args, '--token-budget'),
+        }, raw);
+      } else {
+        error('Unknown skills subcommand. Available: index, align');
+      }
+      break;
+    }
+
+    case 'hygiene': {
+      const subcommand = args[1];
+      const hygieneOpts = {
+        traceAgeDays: getArgValue(args, '--trace-age-days'),
+        apply: args.includes('--apply'),
+      };
+      if (subcommand === 'scan') {
+        hygiene.cmdHygieneScan(cwd, hygieneOpts, raw);
+      } else if (subcommand === 'clean') {
+        hygiene.cmdHygieneClean(cwd, hygieneOpts, raw);
+      } else {
+        error('Unknown hygiene subcommand. Available: scan, clean [--apply] [--trace-age-days N]');
+      }
+      break;
+    }
+
     case 'review-deep': {
       const subcommand = args[1];
       const phaseNum = args[2];
@@ -1257,6 +1307,12 @@ async function main() {
         docLint.cmdDocLintCounts(cwd, dir, { raw, exclude });
         break;
       }
+      if (subcommand === 'flags') {
+        const docDirs = [];
+        for (let k = 0; k < args.length; k++) if (args[k] === '--doc-dir') docDirs.push(args[k + 1]);
+        docLint.cmdDocLintFlags(cwd, { docDirs: docDirs.length ? docDirs : undefined }, raw);
+        break;
+      }
       // Default: lint a directory
       const dir = args[1];
       if (!dir || dir.startsWith('--')) { error('doc-lint <dir> required (or doc-lint schema-check <path>, doc-lint counts <dir>)'); }