@jaimevalasek/aioson 1.30.2 → 1.36.0

package/src/commands/review-feature.js

@@ -0,0 +1,189 @@
+'use strict';
+
+/**
+ * aioson review:feature [path] [--feature=<slug>] [--scope=<target>]
+ *   [--skip-audit] [--out-dir=<dir>] [--tool=<tool>] [--json]
+ *
+ * One-shot "review an already-implemented feature" helper. It does NOT replace
+ * the workflow gates — it is the post-close / standalone path for re-running the
+ * adversarial + test passes against a feature:
+ *
+ *   1. runs the deterministic `security:audit` for the slug (writes/refreshes
+ *      security-findings-{slug}.json),
+ *   2. prepares the `@pentester` and `@tester` activation prompts (read-only,
+ *      headless — no runtime session, no state mutation),
+ *   3. prints a copy-pasteable plan (or saves the prompts to files / emits JSON).
+ *
+ * Slug resolution: explicit `--feature`/`--slug` wins; otherwise the active
+ * feature (pulse / unique in_progress). After `feature:close` there is no active
+ * feature, so the caller must pass `--feature` — the command says so explicitly.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+const { runSecurityAudit } = require('./security-audit');
+const { runAgentPrompt } = require('./agents');
+const { resolveActiveFeature } = require('./feature-current');
+
+function silentLogger() {
+  return { log() {}, error() {} };
+}
+
+// Build an agent activation prompt without side effects (headless skips workflow
+// routing, runtime bootstrap and telemetry). Returns the prompt string, or an
+// `{ error }` object when the prompt could not be built.
+async function buildAgentPromptText(agentName, targetDir, agentOptions, t) {
+  try {
+    const res = await runAgentPrompt({
+      args: [agentName, targetDir],
+      options: { ...agentOptions, headless: true },
+      logger: silentLogger(),
+      t
+    });
+    return res && res.ok && typeof res.prompt === 'string' ? res.prompt : { error: 'prompt_unavailable' };
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
+async function runReviewFeature({ args, options = {}, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args?.[0] || '.');
+  const tool = options.tool || 'claude';
+
+  // 1. Resolve the feature slug.
+  let slug = String(options.feature || options.slug || '').trim();
+  let slugSource = slug ? 'explicit' : null;
+  if (!slug) {
+    const active = await resolveActiveFeature(targetDir);
+    if (active.ambiguous) {
+      const msg = `review:feature: ${active.candidates.length} features are in_progress (${active.candidates.join(', ')}). Pass --feature=<slug>.`;
+      if (options.json) return { ok: false, reason: 'ambiguous_feature', candidates: active.candidates };
+      logger.error(msg);
+      return { ok: false, reason: 'ambiguous_feature' };
+    }
+    if (!active.slug) {
+      const msg = 'review:feature: no active feature found — pass --feature=<slug> (a closed feature is no longer the active one).';
+      if (options.json) return { ok: false, reason: 'missing_feature' };
+      logger.error(msg);
+      return { ok: false, reason: 'missing_feature' };
+    }
+    slug = active.slug;
+    slugSource = active.source;
+  }
+
+  // 2. Deterministic security audit (non-fatal — the review still produces the
+  //    agent prompts even when the audit cannot run, e.g. archived artifacts).
+  let audit = null;
+  const skipAudit = Boolean(options['skip-audit'] || options.skipAudit);
+  if (!skipAudit) {
+    // security:audit sets process.exitCode by finding severity. review:feature
+    // is a prep/report command — surfacing findings is its job, not a failure —
+    // so capture the audit's verdict in the result but do not let it set this
+    // command's exit code.
+    const prevExitCode = process.exitCode;
+    audit = await runSecurityAudit({
+      args: [targetDir],
+      options: { feature: slug, json: true, ...(options.now ? { now: options.now } : {}) },
+      logger: silentLogger()
+    });
+    process.exitCode = prevExitCode;
+  }
+
+  // 3. Prepare the @pentester + @tester prompts.
+  const scope = String(options.scope || '').trim();
+  const pentesterPrompt = await buildAgentPromptText('pentester', targetDir, {
+    tool,
+    feature: slug,
+    ...(scope ? { mode: 'app_target', scope } : {})
+  }, t);
+  const testerPrompt = await buildAgentPromptText('tester', targetDir, { tool, feature: slug }, t);
+
+  // optional: persist the prompts to files
+  const outDirOpt = options['out-dir'] || options.outDir;
+  const saved = {};
+  if (outDirOpt) {
+    const dir = path.resolve(targetDir, String(outDirOpt));
+    fs.mkdirSync(dir, { recursive: true });
+    if (typeof pentesterPrompt === 'string') {
+      const p = path.join(dir, `review-pentester-${slug}.prompt.md`);
+      fs.writeFileSync(p, pentesterPrompt, 'utf8');
+      saved.pentester = p;
+    }
+    if (typeof testerPrompt === 'string') {
+      const p = path.join(dir, `review-tester-${slug}.prompt.md`);
+      fs.writeFileSync(p, testerPrompt, 'utf8');
+      saved.tester = p;
+    }
+  }
+
+  const result = {
+    ok: true,
+    slug,
+    slug_source: slugSource,
+    audit: audit
+      ? {
+          ok: audit.ok,
+          exitCode: audit.exitCode,
+          classification: audit.classification || null,
+          summary: audit.summary || null,
+          findingsCount: audit.findingsCount ?? null,
+          artifactPath: audit.artifactPath || null,
+          reason: audit.reason || null
+        }
+      : null,
+    prompts: {
+      pentester: typeof pentesterPrompt === 'string' ? pentesterPrompt : null,
+      tester: typeof testerPrompt === 'string' ? testerPrompt : null
+    },
+    prompt_errors: {
+      pentester: pentesterPrompt && pentesterPrompt.error ? pentesterPrompt.error : null,
+      tester: testerPrompt && testerPrompt.error ? testerPrompt.error : null
+    },
+    saved,
+    commands: {
+      pentester: `aioson agent:prompt pentester . --tool=${tool} --mode=app_target --feature=${slug} --scope=<target>`,
+      tester: `aioson agent:prompt tester . --tool=${tool} --feature=${slug}`
+    }
+  };
+
+  if (options.json) return result;
+
+  // ── human output ──
+  const resolvedNote = slugSource && slugSource !== 'explicit' ? ` (resolved from ${slugSource})` : '';
+  logger.log(`Review plan — feature: ${slug}${resolvedNote}`);
+  logger.log('');
+
+  if (!skipAudit && audit) {
+    const s = audit.summary;
+    if (s) {
+      logger.log(`1. security:audit (deterministic) — ${audit.classification || '?'}: ${s.critical || 0} critical, ${s.high || 0} high, ${s.medium || 0} medium, ${s.low || 0} low, ${s.inconclusive || 0} inconclusive`);
+      if (audit.artifactPath) logger.log(`   findings → ${path.relative(targetDir, audit.artifactPath)}`);
+    } else {
+      logger.log(`1. security:audit — could not run (${audit.reason || 'unknown'}); proceeding with the agent prompts.`);
+    }
+  } else {
+    logger.log('1. security:audit — skipped (--skip-audit)');
+  }
+  logger.log('');
+
+  logger.log('2. @pentester — adversarial review (vulnerabilities, threat surface):');
+  if (saved.pentester) logger.log(`   saved → ${path.relative(targetDir, saved.pentester)}`);
+  if (!scope) logger.log('   tip: pass --scope=<target> for a precise app_target review contract');
+  logger.log('');
+  logger.log(typeof pentesterPrompt === 'string'
+    ? pentesterPrompt
+    : `   [could not build @pentester prompt: ${pentesterPrompt.error}]`);
+  logger.log('');
+
+  logger.log('3. @tester — engineering test pass (missing tests, regressions):');
+  if (saved.tester) logger.log(`   saved → ${path.relative(targetDir, saved.tester)}`);
+  logger.log('');
+  logger.log(typeof testerPrompt === 'string'
+    ? testerPrompt
+    : `   [could not build @tester prompt: ${testerPrompt.error}]`);
+
+  return result;
+}
+
+module.exports = { runReviewFeature };

package/src/commands/runtime.js

@@ -1171,6 +1171,12 @@ async function runRuntimeLog({ args, options = {}, logger, t }) {
  *
  * Intended to be called ONCE at the very end of an agent session, after delivering the main artifact.
  */
+function logVerifyArtifactLine(logger, va) {
+  if (!va) return;
+  const marker = va.skipped ? 'hint' : va.ok ? 'ok' : 'advisory';
+  logger.log(`agent:done — verify:artifact (${va.kind}): ${marker}${va.reason ? ` — ${va.reason}` : ''}`);
+}
+
 async function runAgentDone({ args, options = {}, logger, t }) {
   const targetDir = resolveTargetDir(args);
   const agentName = String(options.agent || '').trim();
@@ -1187,6 +1193,13 @@ async function runAgentDone({ args, options = {}, logger, t }) {
     ? String(options.artifacts).split(',').map((p) => p.trim()).filter(Boolean)
     : [];
 
+  // Build-free artifact done-gate (advisory): for the peripheral agents that
+  // produce a non-code artifact, prove it is complete/well-formed at the same
+  // session-end call they always make, instead of relying on each agent to run
+  // its `## Done gate` line. Resolved once here; surfaced on every return path.
+  const { verifyAgentArtifact } = require('../artifact-kinds');
+  const verifyArtifact = await verifyAgentArtifact({ targetDir, agent: normalizedAgent, options });
+
   const { db, dbPath, runtimeDir } = await openRuntimeDb(targetDir);
 
   try {
@@ -1224,7 +1237,7 @@ async function runAgentDone({ args, options = {}, logger, t }) {
       }
 
       // F2 (workflow-handoff-integrity v1.9.5) — best-effort auto-advance workflow pointer
-      const autoAdvance = await maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options, logger, t });
+      const autoAdvance = await maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options, logger, t });
 
       if (isDocCreatingAgent(normalizedAgent)) {
         backupAiosonDocs(targetDir).catch(() => {});
@@ -1252,7 +1265,8 @@ async function runAgentDone({ args, options = {}, logger, t }) {
         });
       } catch { /* ignore — never blocks agent_done */ }
 
-      return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'live_event', runKey: session.runKey, auto_advance: autoAdvance };
+      if (!options.json) logVerifyArtifactLine(logger, verifyArtifact);
+      return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'live_event', runKey: session.runKey, auto_advance: autoAdvance, verify_artifact: verifyArtifact };
     }
 
     // No active session — create a standalone task+run and immediately complete it.
@@ -1297,7 +1311,7 @@ async function runAgentDone({ args, options = {}, logger, t }) {
     }
 
     // F2 (workflow-handoff-integrity v1.9.5) — best-effort auto-advance workflow pointer
-    const autoAdvance = await maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options, logger, t });
+    const autoAdvance = await maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options, logger, t });
 
     if (isDocCreatingAgent(normalizedAgent)) {
       backupAiosonDocs(targetDir).catch(() => {});
@@ -1325,7 +1339,8 @@ async function runAgentDone({ args, options = {}, logger, t }) {
       });
     } catch { /* ignore — never blocks agent_done */ }
 
-    return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'standalone', runKey, taskKey, auto_advance: autoAdvance };
+    if (!options.json) logVerifyArtifactLine(logger, verifyArtifact);
+    return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'standalone', runKey, taskKey, auto_advance: autoAdvance, verify_artifact: verifyArtifact };
   } finally {
     db.close();
   }
@@ -2026,9 +2041,9 @@ function parseDurationMs(value, defaultHours = 24) {
  *
  * Sources checked:
  *   1. Session files in .aioson/.sessions/ with finished=false older than threshold.
- *   2. agent_runs rows with status='running'/'queued' older than threshold
- *      that have no corresponding live session file (orphaned DB records).
- *   3. workflow tasks/runs left running after a workflow finished or was abandoned.
+ *   2. agent_runs rows with status='running'/'queued' older than threshold
+ *      that have no corresponding live session file (orphaned DB records).
+ *   3. workflow tasks/runs left running after a workflow finished or was abandoned.
  *
  * --older-than  Duration threshold. Accepts: 24h (default), 8h, 30m, 7d.
  * --dry-run     Report what would be recovered without making any changes.
@@ -2109,31 +2124,31 @@ async function runAgentRecover({ args, options = {}, logger }) {
       recovered.push({ source: 'session_file', agent: agentName, runKey, taskKey, startedAt: session.startedAt });
     }
 
-    // ── 2. Scan DB for orphaned running runs (no session file) ────────────────
-    const orphanedRuns = db.prepare(`
-      SELECT run_key, task_key, agent_name, source, started_at
-      FROM agent_runs
-      WHERE status IN ('running', 'queued')
-        AND COALESCE(started_at, updated_at, '') < ?
-    `).all(cutoffIso);
-
-    for (const run of orphanedRuns) {
-      // Skip if already recovered via session file
-      if (recovered.some((r) => r.runKey === run.run_key)) continue;
-      const source = run.source === 'workflow' ? 'workflow_run' : 'orphaned_run';
-      const summary = source === 'workflow_run'
-        ? 'Recovered: stale workflow run left running'
-        : 'Recovered: orphaned run with no session file';
-
-      if (!dryRun) {
-        db.prepare(`
-          UPDATE agent_runs
-          SET status = 'abandoned', summary = ?, updated_at = ?, finished_at = ?
-          WHERE run_key = ?
-        `).run(summary, now, now, run.run_key);
-
-        if (run.task_key) {
-          const taskRow = db.prepare('SELECT task_key, status FROM tasks WHERE task_key = ?').get(run.task_key);
+    // ── 2. Scan DB for orphaned running runs (no session file) ────────────────
+    const orphanedRuns = db.prepare(`
+      SELECT run_key, task_key, agent_name, source, started_at
+      FROM agent_runs
+      WHERE status IN ('running', 'queued')
+        AND COALESCE(started_at, updated_at, '') < ?
+    `).all(cutoffIso);
+
+    for (const run of orphanedRuns) {
+      // Skip if already recovered via session file
+      if (recovered.some((r) => r.runKey === run.run_key)) continue;
+      const source = run.source === 'workflow' ? 'workflow_run' : 'orphaned_run';
+      const summary = source === 'workflow_run'
+        ? 'Recovered: stale workflow run left running'
+        : 'Recovered: orphaned run with no session file';
+
+      if (!dryRun) {
+        db.prepare(`
+          UPDATE agent_runs
+          SET status = 'abandoned', summary = ?, updated_at = ?, finished_at = ?
+          WHERE run_key = ?
+        `).run(summary, now, now, run.run_key);
+
+        if (run.task_key) {
+          const taskRow = db.prepare('SELECT task_key, status FROM tasks WHERE task_key = ?').get(run.task_key);
           if (taskRow && (taskRow.status === 'running' || taskRow.status === 'queued')) {
             db.prepare(`
               UPDATE tasks
@@ -2141,40 +2156,40 @@ async function runAgentRecover({ args, options = {}, logger }) {
               WHERE task_key = ?
             `).run(now, now, run.task_key);
           }
-        }
-      }
-
-      recovered.push({ source, agent: run.agent_name, runKey: run.run_key, taskKey: run.task_key, startedAt: run.started_at });
-    }
-
-    // ── 3. Scan DB for stale workflow tasks without a recovered run ───────────
-    const staleWorkflowTasks = db.prepare(`
-      SELECT task_key, title, created_by, session_key, created_at, updated_at
-      FROM tasks
-      WHERE status IN ('running', 'queued')
-        AND (created_by = '@workflow' OR session_key LIKE 'workflow:%')
-        AND COALESCE(updated_at, created_at, '') < ?
-    `).all(cutoffIso);
-
-    for (const task of staleWorkflowTasks) {
-      if (recovered.some((r) => r.taskKey === task.task_key)) continue;
-
-      if (!dryRun) {
-        db.prepare(`
-          UPDATE tasks
-          SET status = 'abandoned', updated_at = ?, finished_at = ?
-          WHERE task_key = ?
-        `).run(now, now, task.task_key);
-      }
-
-      recovered.push({
-        source: 'workflow_task',
-        agent: task.created_by || '@workflow',
-        runKey: null,
-        taskKey: task.task_key,
-        startedAt: task.updated_at || task.created_at
-      });
-    }
+        }
+      }
+
+      recovered.push({ source, agent: run.agent_name, runKey: run.run_key, taskKey: run.task_key, startedAt: run.started_at });
+    }
+
+    // ── 3. Scan DB for stale workflow tasks without a recovered run ───────────
+    const staleWorkflowTasks = db.prepare(`
+      SELECT task_key, title, created_by, session_key, created_at, updated_at
+      FROM tasks
+      WHERE status IN ('running', 'queued')
+        AND (created_by = '@workflow' OR session_key LIKE 'workflow:%')
+        AND COALESCE(updated_at, created_at, '') < ?
+    `).all(cutoffIso);
+
+    for (const task of staleWorkflowTasks) {
+      if (recovered.some((r) => r.taskKey === task.task_key)) continue;
+
+      if (!dryRun) {
+        db.prepare(`
+          UPDATE tasks
+          SET status = 'abandoned', updated_at = ?, finished_at = ?
+          WHERE task_key = ?
+        `).run(now, now, task.task_key);
+      }
+
+      recovered.push({
+        source: 'workflow_task',
+        agent: task.created_by || '@workflow',
+        runKey: null,
+        taskKey: task.task_key,
+        startedAt: task.updated_at || task.created_at
+      });
+    }
 
     // ── Output ────────────────────────────────────────────────────────────────
     const olderThanLabel = options['older-than'] || options.olderThan || '24h';

package/src/commands/sync-agents-copy.js

@@ -0,0 +1,115 @@
+'use strict';
+
+// Cross-platform replacement for the legacy `rsync -av template/ ./` step in the
+// `sync:agents` npm script. rsync is not available on Windows, which silently
+// left the workspace un-synced. This mirrors template/ into the repo root using
+// Node's fs, replicating the original rsync excludes:
+//   --exclude='config.md' --exclude='runtime/' --exclude='backups/' --exclude='mcp/servers.local.json'
+// rsync matched those names at any depth; we replicate that (basename / dir
+// segment / path suffix).
+//
+// We also exclude the live project-state files (project-pulse.md, project-map.md,
+// learning-loop.json, git-guard.json): the dogfooding workspace owns its own
+// evolving state, so a template sync must never overwrite it with the template
+// seeds. External project installs (`aioson update`) are a separate code path and
+// still receive the seeds.
+//
+// Gateway-pointer files (CLAUDE.md / AGENTS.md / OPENCODE.md) carry an AIOSON
+// managed block (<!-- AIOSON:BEGIN --> … <!-- AIOSON:END -->) when a project was
+// installed/updated. A blind copy of the raw template body STRIPS that block (and
+// any project content around it). So when the destination already has a managed
+// block, we refresh it in place via mergeGatewayPointer (same path the installer
+// uses) instead of clobbering it. When the destination has no block we keep the
+// plain copy — that leaves the framework repo's own raw CLAUDE.md untouched.
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const {
+  isGatewayPointerPath,
+  findBlockRange,
+  mergeGatewayPointer
+} = require('../gateway-pointer-merge');
+
+const EXCLUDE_BASENAMES = new Set([
+  'config.md',
+  // live project-state — owned by the workspace, never clobbered by template seeds
+  'project-pulse.md',
+  'project-map.md',
+  'learning-loop.json',
+  'git-guard.json'
+]);
+const EXCLUDE_DIR_NAMES = new Set(['runtime', 'backups']);
+const EXCLUDE_SUFFIXES = [path.join('mcp', 'servers.local.json')];
+
+// `relPath` is relative to template/ and uses the OS separator.
+function isExcluded(relPath) {
+  const segments = relPath.split(path.sep).filter(Boolean);
+  const base = segments[segments.length - 1];
+  if (EXCLUDE_BASENAMES.has(base)) return true;
+  // a directory named runtime/ or backups/ anywhere in the path (or the dir itself)
+  if (segments.some((seg) => EXCLUDE_DIR_NAMES.has(seg))) return true;
+  if (EXCLUDE_SUFFIXES.some((suf) => relPath === suf || relPath.endsWith(path.sep + suf))) return true;
+  return false;
+}
+
+// Refresh an AIOSON-managed block in place when the destination already has one;
+// otherwise fall back to a plain copy. Keeps markers + any project-authored
+// content around the block intact (the blind copy would have stripped them).
+async function copyGatewayPointer(srcChild, destChild) {
+  await fs.mkdir(path.dirname(destChild), { recursive: true });
+  let hasBlock = false;
+  try {
+    const existing = await fs.readFile(destChild, 'utf8');
+    hasBlock = findBlockRange(existing) !== null;
+  } catch {
+    hasBlock = false; // destination missing/unreadable → plain copy
+  }
+  if (hasBlock) {
+    await mergeGatewayPointer({ templatePath: srcChild, targetPath: destChild });
+  } else {
+    await fs.copyFile(srcChild, destChild);
+  }
+}
+
+async function copyTree(srcRoot, destRoot, relPath = '') {
+  const entries = await fs.readdir(path.join(srcRoot, relPath), { withFileTypes: true });
+  let copied = 0;
+  for (const entry of entries) {
+    const childRel = path.join(relPath, entry.name);
+    if (isExcluded(childRel)) continue;
+    const srcChild = path.join(srcRoot, childRel);
+    const destChild = path.join(destRoot, childRel);
+    if (entry.isDirectory()) {
+      await fs.mkdir(destChild, { recursive: true });
+      copied += await copyTree(srcRoot, destRoot, childRel);
+    } else if (entry.isFile()) {
+      if (isGatewayPointerPath(childRel)) {
+        await copyGatewayPointer(srcChild, destChild);
+      } else {
+        await fs.mkdir(path.dirname(destChild), { recursive: true });
+        await fs.copyFile(srcChild, destChild);
+      }
+      copied += 1;
+    }
+  }
+  return copied;
+}
+
+async function syncAgentsCopy(rootDir = process.cwd()) {
+  const templateDir = path.join(rootDir, 'template');
+  const copied = await copyTree(templateDir, rootDir);
+  return { copied };
+}
+
+module.exports = { syncAgentsCopy, isExcluded };
+
+if (require.main === module) {
+  syncAgentsCopy(process.cwd())
+    .then(({ copied }) => {
+      console.log(`[sync:agents] mirrored template/ -> ./ (${copied} files, cross-platform copy; rsync not required)`);
+    })
+    .catch((err) => {
+      console.error(`[sync:agents] copy failed: ${err.message}`);
+      process.exitCode = 1;
+    });
+}

package/src/commands/verification-plan.js

@@ -0,0 +1,116 @@
+'use strict';
+
+// `aioson verification:plan` — deterministic bridge between verification.json and
+// the agents. Given a slug + trigger + run context, it resolves WHICH verification
+// sub-agents should run, on WHICH host/model, and the phase-loop settings — so
+// @dev (per-phase) and the post-dev cycle (end-of-feature) follow a computed plan
+// instead of re-interpreting the config in prose. Read-only; never mutates state.
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const {
+  readVerificationConfig,
+  resolveHost,
+  getAgentDispatch,
+  shouldRunForTrigger,
+  resolveAgentReportPath,
+  getCrossCheck,
+  getBudget,
+  getPhaseLoop,
+  VERIFICATION_AGENTS,
+  TRIGGERS
+} = require('../verification-policy');
+
+const BAR = '─'.repeat(60);
+const CLASSIFICATIONS = ['MICRO', 'SMALL', 'MEDIUM'];
+
+async function readFileSafe(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// Best-effort classification: prd-{slug}.md frontmatter wins, then project.context.md.
+async function detectClassification(targetDir, slug) {
+  const dir = path.join(targetDir, '.aioson', 'context');
+  const candidates = [];
+  if (slug) candidates.push(path.join(dir, `prd-${slug}.md`));
+  candidates.push(path.join(dir, 'project.context.md'));
+  for (const file of candidates) {
+    const text = await readFileSafe(file);
+    if (!text) continue;
+    const m = text.match(/^\s*classification:\s*["']?([A-Za-z]+)["']?\s*$/m);
+    if (m && CLASSIFICATIONS.includes(m[1].toUpperCase())) return m[1].toUpperCase();
+  }
+  return null;
+}
+
+async function runVerificationPlan({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const slug = (options.feature || options.slug || '').toString().trim() || null;
+
+  const triggerRaw = (options.trigger || 'per-phase').toString().trim().toLowerCase();
+  const trigger = TRIGGERS.includes(triggerRaw) ? triggerRaw : 'per-phase';
+
+  const config = await readVerificationConfig(targetDir);
+  const host = resolveHost(config, options.host);
+
+  let classification = (options.classification || '').toString().trim().toUpperCase();
+  if (!CLASSIFICATIONS.includes(classification)) {
+    classification = (await detectClassification(targetDir, slug)) || 'SMALL';
+  }
+  const sensitiveSurface = Boolean(options.sensitive);
+
+  const context = { trigger, classification, sensitiveSurface };
+  const agents = [];
+  for (const agentId of VERIFICATION_AGENTS) {
+    const dispatch = getAgentDispatch(config, agentId, host);
+    const entry = {
+      agent: agentId,
+      run: shouldRunForTrigger(config, agentId, context),
+      mode: dispatch ? dispatch.mode : 'native',
+      model: dispatch ? dispatch.model : 'configured-default',
+      report: resolveAgentReportPath(config, agentId, slug || '{slug}')
+    };
+    if (agentId === 'validator') {
+      const cc = getCrossCheck(config, agentId);
+      if (cc) entry.cross_check = cc;
+    }
+    agents.push(entry);
+  }
+
+  const result = {
+    ok: true,
+    feature_slug: slug,
+    host,
+    trigger,
+    classification,
+    sensitive_surface: sensitiveSurface,
+    agents,
+    phase_loop: getPhaseLoop(config),
+    budget: getBudget(config)
+  };
+
+  if (options.json) return result;
+
+  logger.log('');
+  logger.log(`Verification plan${slug ? ` — ${slug}` : ''}`);
+  logger.log(BAR);
+  logger.log(`Host: ${host}   Trigger: ${trigger}   Class: ${classification}${sensitiveSurface ? '   [sensitive]' : ''}`);
+  logger.log(BAR);
+  for (const a of agents) {
+    const mark = a.run ? 'RUN ' : 'skip';
+    const cc = a.cross_check && a.cross_check.enabled ? `  + cross_check(${a.cross_check.tool}/${a.cross_check.model})` : '';
+    logger.log(`  [${mark}] ${a.agent.padEnd(10)} ${a.mode}/${a.model}${a.run ? `  → ${a.report}` : ''}${cc}`);
+  }
+  logger.log(BAR);
+  const pl = result.phase_loop;
+  logger.log(`Phase loop: auto_continue=${pl.auto_continue}  compact_between_phases=${pl.compact_between_phases}  max_fix_retries=${pl.max_fix_retries_per_phase}`);
+  logger.log('');
+
+  return result;
+}
+
+module.exports = { runVerificationPlan };