@clear-capabilities/agentic-security-scanner 0.74.0

package/src/posture/pre-incident-archaeology.js

@@ -0,0 +1,110 @@
+// FR-UX-11 — Pre-incident archaeology.
+//
+// Given a finding or a CWE, walk the git history of the affected file to
+// answer "when did this codebase first become vulnerable to this CWE?"
+// Outputs a structured timeline:
+//
+//   {
+//     finding: { stableId, file, line, vuln },
+//     firstVulnerableCommit: { sha, author, ts, message } | null,
+//     vulnerableForDays: 145,
+//     concurrentSafeShapes: [{ sha, ts, snippet }],   // earlier commits where the same file did NOT contain the bug
+//     introducingCommit: { sha, author, ts, message } | null,
+//   }
+//
+// We invoke `git log` and `git show` via the shell. If the project is not a
+// git repository (no `.git` at root), we return `{ available: false }`.
+//
+// This is intentionally light: we do not re-run the SAST detector on every
+// historical revision. We use a simple substring-presence probe — does the
+// finding's sink snippet appear in the historical version of the file?
+// Sufficient for the common case and dramatically cheaper than full
+// re-scanning. Customers who want forensic-grade archaeology can re-run the
+// scanner against `git checkout`-ed historical revisions.
+
+import { execSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+function isGitRepo(root) {
+  try {
+    return fs.existsSync(path.join(root, '.git'));
+  } catch { return false; }
+}
+
+function gitLogForFile(root, file, limit = 50) {
+  try {
+    const out = execSync(
+      `git log --pretty=format:%H%x1f%an%x1f%aI%x1f%s --max-count=${limit} -- "${file}"`,
+      { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+    );
+    return out.split(/\n/).filter(Boolean).map(line => {
+      const [sha, author, ts, message] = line.split('\x1f');
+      return { sha, author, ts, message };
+    });
+  } catch { return []; }
+}
+
+function gitShow(root, sha, file) {
+  try {
+    return execSync(`git show ${sha}:"${file}"`, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch { return null; }
+}
+
+function probeSnippet(content, snippet) {
+  if (!content || !snippet) return false;
+  // Strip whitespace for a coarse match — historical reformatting shouldn't
+  // hide the presence of the same vulnerable expression.
+  const normContent = content.replace(/\s+/g, ' ');
+  const normSnippet = snippet.replace(/\s+/g, ' ').slice(0, 120);
+  return normContent.includes(normSnippet);
+}
+
+export function archaeologyForFinding(finding, scanRoot) {
+  const root = scanRoot || process.cwd();
+  if (!isGitRepo(root)) return { available: false, reason: 'not-a-git-repo' };
+  if (!finding || !finding.file) return { available: false, reason: 'no-file' };
+
+  const snippet = finding.sink?.snippet || finding.snippet || '';
+  if (!snippet) return { available: false, reason: 'no-snippet' };
+
+  const log = gitLogForFile(root, finding.file, 50);
+  if (!log.length) return { available: false, reason: 'no-history' };
+
+  // Walk oldest-first; find the first commit where the snippet is present.
+  const ordered = log.slice().reverse();
+  let firstVulnerable = null;
+  let lastSafe = null;
+  for (const c of ordered) {
+    const content = gitShow(root, c.sha, finding.file);
+    if (content === null) continue;
+    const present = probeSnippet(content, snippet);
+    if (present && !firstVulnerable) firstVulnerable = c;
+    if (!present) lastSafe = c;
+  }
+
+  // If snippet isn't present in any commit, treat as no archaeology available.
+  if (!firstVulnerable) return { available: false, reason: 'snippet-never-seen' };
+
+  // The "introducing commit" is firstVulnerable; if lastSafe is just before it,
+  // we have a clean delta. Otherwise the snippet may have been introduced,
+  // removed, reintroduced — present a partial answer.
+  const tsFirst = Date.parse(firstVulnerable.ts);
+  const tsNow = Date.now();
+  const vulnerableForDays = Number.isFinite(tsFirst) ? Math.floor((tsNow - tsFirst) / 86_400_000) : null;
+
+  return {
+    available: true,
+    finding: {
+      stableId: finding.stableId || null,
+      file: finding.file,
+      line: finding.line || 0,
+      vuln: finding.vuln || null,
+    },
+    firstVulnerableCommit: firstVulnerable,
+    introducingCommit: firstVulnerable,
+    lastSafeCommit: lastSafe,
+    vulnerableForDays,
+    historyLength: log.length,
+  };
+}

package/src/posture/profile.js

@@ -0,0 +1,93 @@
+// Persona profile: vibecoder | pro
+// Loaded from .agentic-security/profile.yml. Used everywhere a default differs
+// by audience (rendering verbosity, confidence threshold, command visibility,
+// suppression schema, integration set, etc.).
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'js-yaml';
+
+export const PROFILES = ['vibecoder', 'pro'];
+
+export const DEFAULTS = {
+  vibecoder: {
+    profile: 'vibecoder',
+    confidenceMin: 0.9,         // hide low-confidence findings
+    showTaxonomy: false,         // no CWE/CVSS/STRIDE/OWASP/MITRE in default output
+    severityFloor: 'high',       // by default only show high+critical
+    commandTier: 'primary',      // /help shows ~5 commands
+    suppression: 'soft',         // accepted.json, 30-day, no reviewer required
+    machineOutput: false,        // don't write SARIF/JSON unless asked
+    onboardingPrompts: true,
+    showAttribution: true,
+  },
+  pro: {
+    profile: 'pro',
+    confidenceMin: 0.3,          // show all but the lowest-signal findings
+    showTaxonomy: true,           // CWE/CVSS/STRIDE/OWASP/MITRE visible by default
+    severityFloor: 'low',         // show everything down to info
+    commandTier: 'all',           // /help shows all commands
+    suppression: 'audit',         // suppressions.yml, requires reason+reviewer+expiry
+    machineOutput: true,          // SARIF + JSON every scan
+    onboardingPrompts: false,
+    showAttribution: true,
+  },
+};
+
+function _profilePath(scanRoot) {
+  return path.join(scanRoot || process.cwd(), '.agentic-security', 'profile.yml');
+}
+
+export function loadProfile(scanRoot) {
+  const fp = _profilePath(scanRoot);
+  let parsed = {};
+  try {
+    if (fs.existsSync(fp)) {
+      parsed = yaml.load(fs.readFileSync(fp, 'utf8')) || {};
+    }
+  } catch (_) { /* fall through */ }
+  const name = PROFILES.includes(parsed.profile) ? parsed.profile : 'vibecoder';
+  return { ...DEFAULTS[name], ...parsed, profile: name };
+}
+
+export function saveProfile(scanRoot, updates) {
+  const fp = _profilePath(scanRoot);
+  fs.mkdirSync(path.dirname(fp), { recursive: true });
+  const current = loadProfile(scanRoot);
+  const next = { ...current, ...updates };
+  // Strip values equal to defaults so the file stays minimal.
+  const defaults = DEFAULTS[next.profile];
+  const out = {};
+  for (const k of Object.keys(next)) {
+    if (defaults[k] === next[k]) continue;
+    out[k] = next[k];
+  }
+  if (!('profile' in out)) out.profile = next.profile;
+  fs.writeFileSync(fp, yaml.dump(out));
+  return next;
+}
+
+// Detect profile heuristically from project state when no profile.yml exists.
+// Returns 'pro' if the repo has signals indicating professional security work,
+// otherwise 'vibecoder'. Run only on first scan.
+export function detectProfile(scanRoot) {
+  const root = scanRoot || process.cwd();
+  const signals = ['SECURITY.md', '.github/workflows/security.yml', '.semgrep.yml',
+                   '.snyk', 'codeql-config.yml', 'compliance/', 'docs/threat-model.md'];
+  for (const s of signals) {
+    if (fs.existsSync(path.join(root, s))) return 'pro';
+  }
+  // Repos with `security` or `compliance` in package.json description → pro.
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    if (/security|compliance|appsec|pentest/i.test(pkg.description || '')) return 'pro';
+  } catch (_) { /* no pkg or unreadable */ }
+  return 'vibecoder';
+}
+
+export const ATTRIBUTION = 'agentic-security · created by ClearCapabilities.Com';
+export const ATTRIBUTION_URL = 'https://clearcapabilities.com';
+
+export function renderAttributionLine() {
+  return `🛡  ${ATTRIBUTION}  ·  ${ATTRIBUTION_URL}`;
+}

package/src/posture/reachability-filter.js

@@ -0,0 +1,42 @@
+// Reachability filter (FR-PREC-2).
+//
+// annotateReachability() in engine.js already sets f.reachable to true|false
+// based on whether the finding sits in code reachable from an HTTP route. This
+// module turns that signal into a precision lever: findings marked reachable=
+// false are demoted to severity 'info' with f.unreachable = true.
+//
+// Disabled when scanRoot/--include-unreachable signals are present, or when
+// AGENTIC_SECURITY_INCLUDE_UNREACHABLE=1 is set.
+
+const SEVERITY_DEMOTE = {
+  critical: 'medium',
+  high: 'low',
+  medium: 'low',
+  low: 'info',
+};
+
+export function demoteUnreachable(findings, opts = {}) {
+  if (!Array.isArray(findings)) return;
+  if (opts.includeUnreachable || process.env.AGENTIC_SECURITY_INCLUDE_UNREACHABLE === '1') return;
+  // The reachability signal is only informative when the project HAS route
+  // handlers. A fixture file scanned in isolation has every finding marked
+  // reachable=false by annotateReachability(); demoting all of them would
+  // hide real bugs the user is trying to verify.
+  const haveRoutes = Array.isArray(opts.routes) ? opts.routes.length > 0 : false;
+  if (!haveRoutes) return;
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    if (f.reachable !== false) continue;
+    if (f.type === 'vulnerable_dep') continue;
+    if (f.unreachable) continue;
+    // Source has an explicit HTTP/DOM/Form/URL category → engine is confident
+    // it's a user-input source even though no route was linked. Don't demote.
+    if (f.source && f.source.category && /HTTP|DOM|Form|URL|Query/i.test(f.source.category)) continue;
+    const before = f.severity;
+    const after = SEVERITY_DEMOTE[before];
+    if (!after || before === after) continue;
+    f.severity = after;
+    f.unreachable = true;
+    f._reachabilityDemoted = before;
+  }
+}

package/src/posture/regression-test-gen.js

@@ -0,0 +1,200 @@
+// Regression-test generator (FR-VER-3).
+//
+// For each finding that has a PoC (from P1.1 / poc-generator), emit a
+// framework-idiomatic test file that:
+//   - Fails on the vulnerable code state (asserts the exploit succeeds)
+//   - Passes after the fix is applied (assert flips to "did not succeed")
+//
+// We piggy-back on the existing PoC template — the test wraps the same
+// HTTP call but uses the framework's test runner (Jest / pytest / JUnit)
+// for assertion + reporting.
+//
+// Output: `f.regression_test = { lang, framework, code, runHint, filename }`.
+//
+// Harness-engineering note (post-derived): generated code is parsed before
+// emit. A test that doesn't even compile is worse than no test — it gives
+// the agent the illusion of progress while shipping a broken artifact.
+// JS/TS: @babel/parser. Python: heuristic indentation + paren-balance check
+// (we can't run python3 from inside Node deterministically).
+
+import { parse as babelParse } from '@babel/parser';
+
+const FRAMEWORK_FOR_LANG = Object.freeze({
+  node: 'jest',
+  python: 'pytest',
+  java: 'junit',
+});
+
+function _validateJs(code) {
+  try {
+    babelParse(code, { sourceType: 'module', allowAwaitOutsideFunction: false, errorRecovery: false });
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: `parse-failed: ${e.message}` };
+  }
+}
+
+function _validatePython(code) {
+  // Best-effort balance check without a Python parser.
+  // Catches the common breakage: an unescaped quote in the PoC payload
+  // bleeding into the test source and unbalancing the assertion string.
+  let parens = 0, brackets = 0, braces = 0;
+  let inStr = false, q = '';
+  for (let i = 0; i < code.length; i++) {
+    const c = code[i];
+    if (inStr) {
+      if (c === '\\') { i++; continue; }
+      if (c === q) inStr = false;
+      continue;
+    }
+    if (c === '"' || c === "'") { inStr = true; q = c; continue; }
+    if (c === '(') parens++;
+    else if (c === ')') parens--;
+    else if (c === '[') brackets++;
+    else if (c === ']') brackets--;
+    else if (c === '{') braces++;
+    else if (c === '}') braces--;
+  }
+  if (parens || brackets || braces) {
+    return { ok: false, reason: `parse-failed: unbalanced delimiters (parens=${parens} brackets=${brackets} braces=${braces})` };
+  }
+  if (inStr) {
+    return { ok: false, reason: 'parse-failed: unterminated string literal' };
+  }
+  return { ok: true };
+}
+
+function _filenameFor(finding, lang) {
+  const slug = (finding.stableId || finding.id || 'finding')
+    .replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 40);
+  if (lang === 'python') return `test_security_${slug}.py`;
+  if (lang === 'java')   return `SecurityRegression_${slug}.java`;
+  return `security_${slug}.test.mjs`;
+}
+
+function _renderJest(finding, poc) {
+  // Wrap the PoC's HTTP call in a Jest test. The PoC's `process.exit(0)`
+  // becomes `expect(...).toBe(true)`; exit(1) becomes `expect(...).toBe(false)`.
+  const url = _extractUrl(poc.code) || 'http://localhost:3000';
+  const method = _extractMethod(poc.code) || 'POST';
+  const payloadLine = _extractPayloadLine(poc.code);
+  return `// Regression test for ${finding.vuln} (${finding.cwe || 'unknown CWE'}).
+// Auto-generated from P1.1 PoC; fails on vulnerable code, passes after the fix.
+
+import { test, expect } from '@jest/globals';
+
+test('${finding.vuln.replace(/'/g, "\\'")}', async () => {
+  const URL_ = ${JSON.stringify(url)};
+  const METHOD = ${JSON.stringify(method)};
+  ${payloadLine}
+  const body = METHOD === 'GET' ? null : JSON.stringify({ input: PAYLOAD });
+  const reqUrl = METHOD === 'GET'
+    ? URL_ + (URL_.includes('?') ? '&' : '?') + 'input=' + encodeURIComponent(PAYLOAD)
+    : URL_;
+  const r = await fetch(reqUrl, { method: METHOD, headers: { 'Content-Type': 'application/json' }, body });
+  const text = await r.text();
+  // The assertion below is the "exploit demonstrated" signal — when this
+  // test PASSES, the vuln is still present. After the fix, this assertion
+  // SHOULD fail. Inverse the assertion in a green build.
+  const demonstrated = text.includes('PoC') || /syntax error/i.test(text) || text.includes('<script>');
+  expect(demonstrated).toBe(false);
+});
+`;
+}
+
+function _renderPytest(finding, poc) {
+  return `# Regression test for ${finding.vuln} (${finding.cwe || 'unknown CWE'}).
+# Auto-generated from P1.1 PoC.
+
+import requests
+
+
+def test_${(finding.stableId || finding.id || 'finding').replace(/[^a-zA-Z0-9_]/g, '_').slice(0, 40)}():
+    url = 'http://localhost:3000'
+    r = requests.post(url, json={'input': "' UNION SELECT username, password FROM users--"})
+    # After the fix, the response should not contain SQL-syntax-error evidence.
+    text = r.text
+    demonstrated = 'syntax error' in text.lower() or '<script>' in text
+    assert not demonstrated, f'Vulnerability still present: {text[:200]}'
+`;
+}
+
+function _extractUrl(code) {
+  const m = String(code || '').match(/URL_ = (['"])([^'"]+)\1/);
+  return m ? m[2] : null;
+}
+function _extractMethod(code) {
+  const m = String(code || '').match(/METHOD = (['"])([A-Z]+)\1/);
+  return m ? m[2] : null;
+}
+function _extractPayloadLine(code) {
+  const m = String(code || '').match(/PAYLOAD = `([^`]+)`/);
+  if (m) return `const PAYLOAD = ${JSON.stringify(m[1])};`;
+  return `const PAYLOAD = 'PoC';`;
+}
+
+/**
+ * Public API. Annotates findings with f.regression_test = {...} when a PoC
+ * is available.
+ */
+export function annotateRegressionTests(findings) {
+  if (!Array.isArray(findings)) return;
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    if (!f.poc) { f.regression_test = null; continue; }
+    // Harness-engineering note (post-derived): refuse to emit a runnable
+    // regression test when the underlying PoC's parameter key was inferred
+    // with low confidence. A test that posts to the wrong handler key
+    // ALWAYS passes (because the exploit never demonstrates), giving the
+    // illusion of "fix verified" — exactly the silent-failure mode the
+    // post warns against. Surface the skip instead.
+    if (f.poc.paramKeyConfidence === 'low') {
+      f.regression_test = {
+        lang: f.poc.lang,
+        framework: null,
+        filename: null,
+        runHint: null,
+        code: null,
+        _skipped: 'poc-param-key-unverified',
+        _explain: 'PoC param key inference was low-confidence (no `req.body.X` / `req.query.X` / form-key match found in the handler window). A regression test against the wrong key would always pass and would falsely suggest the fix landed.',
+      };
+      continue;
+    }
+    const lang = f.poc.lang;
+    const framework = FRAMEWORK_FOR_LANG[lang];
+    if (!framework) { f.regression_test = null; continue; }
+    let code;
+    try {
+      code = framework === 'jest' ? _renderJest(f, f.poc)
+           : framework === 'pytest' ? _renderPytest(f, f.poc)
+           : null;
+    } catch { code = null; }
+    if (!code) { f.regression_test = null; continue; }
+    // Parse the generated source before claiming it's a runnable test.
+    const validation = framework === 'jest' ? _validateJs(code)
+                     : framework === 'pytest' ? _validatePython(code)
+                     : { ok: true };
+    if (!validation.ok) {
+      f.regression_test = {
+        lang,
+        framework,
+        filename: _filenameFor(f, lang),
+        runHint: null,
+        code: null,
+        _skipped: validation.reason,
+        _explain: 'Generated test source did not parse cleanly. The test would have shipped as a broken artifact; reporting unverified instead.',
+        _attemptedCode: code.length <= 4000 ? code : null,
+      };
+      continue;
+    }
+    f.regression_test = {
+      lang,
+      framework,
+      filename: _filenameFor(f, lang),
+      runHint: framework === 'jest' ? 'npx jest' : framework === 'pytest' ? 'pytest -q' : 'mvn test',
+      code,
+    };
+  }
+}
+
+export const _internals = { FRAMEWORK_FOR_LANG };

package/src/posture/reverse-blast-radius.js

@@ -0,0 +1,110 @@
+// FR-ADV-5 — Reverse blast-radius for dependencies.
+//
+// "If `lodash` is RCE'd tomorrow, what's our exposure?" — pre-compute a
+// reverse-reachability map for every direct dependency. The map keys on
+// package name and lists the source files that import the package, the
+// API surfaces they expose (HTTP routes that ultimately call into the dep),
+// and the data classes those routes touch.
+//
+// Composes with:
+//   - SCA pipeline: when a KEV-listed CVE matches a dep, the reverse map
+//     gives an instant impact summary without a re-scan.
+//   - crown-jewels.js: routes scored as crown-jewel that pull in the dep
+//     elevate the dep's risk score.
+//
+// Output shape:
+//   {
+//     [pkgName]: {
+//       directImporters: [{ file, count, exampleSymbols: [...] }],
+//       routeExposure: [{ route, file }],
+//       crownJewelTouch: 0..1,
+//     }
+//   }
+
+import { mapCrownJewels } from './crown-jewels.js';
+
+const IMPORT_RES = [
+  /(?:^|\n)\s*import\s+(?:[\w*${},\s]+\s+from\s+)?["']([^"'.][^"']+)["']/g,
+  /\brequire\(\s*["']([^"'.][^"']+)["']\s*\)/g,
+];
+
+const ROUTE_RES = [
+  /app\.(?:get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/g,
+  /router\.(?:get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/g,
+];
+
+function packageNameFromSpec(spec) {
+  if (spec.startsWith('node:') || spec.startsWith('bun:')) return null;
+  return spec.startsWith('@') ? spec.split('/').slice(0, 2).join('/') : spec.split('/')[0];
+}
+
+function extractImports(text) {
+  const pkgs = new Map();
+  if (!text || typeof text !== 'string') return pkgs;
+  for (const re of IMPORT_RES) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(text))) {
+      const pkg = packageNameFromSpec(m[1]);
+      if (!pkg) continue;
+      pkgs.set(pkg, (pkgs.get(pkg) || 0) + 1);
+    }
+  }
+  return pkgs;
+}
+
+function extractRoutesInFile(text) {
+  const out = [];
+  if (!text || typeof text !== 'string') return out;
+  for (const re of ROUTE_RES) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(text))) out.push(m[1]);
+  }
+  return out;
+}
+
+export function buildReverseBlastRadius(fileContents) {
+  const map = {};
+  if (!fileContents || typeof fileContents !== 'object') return map;
+  const crownMap = mapCrownJewels(fileContents);
+  for (const [fp, text] of Object.entries(fileContents)) {
+    const pkgs = extractImports(text);
+    if (!pkgs.size) continue;
+    const routes = extractRoutesInFile(text);
+    const crownScore = crownMap[fp]?.score || 0;
+    for (const [pkg, count] of pkgs) {
+      if (!map[pkg]) map[pkg] = { directImporters: [], routeExposure: [], crownJewelTouch: 0 };
+      map[pkg].directImporters.push({ file: fp, count });
+      for (const route of routes) map[pkg].routeExposure.push({ route, file: fp });
+      if (crownScore > map[pkg].crownJewelTouch) map[pkg].crownJewelTouch = crownScore;
+    }
+  }
+  // Compact: cap each list at 25 entries for SARIF embedding.
+  for (const pkg of Object.keys(map)) {
+    map[pkg].directImporters = map[pkg].directImporters.slice(0, 25);
+    map[pkg].routeExposure = map[pkg].routeExposure.slice(0, 25);
+  }
+  return map;
+}
+
+// Annotate SCA findings with reverse-blast context — when a CVE finding's
+// `package` matches a known dep, the SCA finding gets `reverseExposure`.
+export function annotateScaReverseBlast(findings, fileContents) {
+  if (!Array.isArray(findings)) return findings;
+  const map = buildReverseBlastRadius(fileContents || {});
+  if (!Object.keys(map).length) return findings;
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    const pkg = f.package || f.dependency || f.pkg;
+    if (!pkg || !map[pkg]) continue;
+    f.reverseExposure = {
+      importerCount: map[pkg].directImporters.length,
+      routeCount: map[pkg].routeExposure.length,
+      crownJewelTouch: Number(map[pkg].crownJewelTouch.toFixed(2)),
+      sampleImporters: map[pkg].directImporters.slice(0, 5).map(i => i.file),
+      sampleRoutes: map[pkg].routeExposure.slice(0, 5).map(r => r.route),
+    };
+  }
+  return findings;
+}

package/src/posture/router.js

@@ -0,0 +1,109 @@
+// Smart router — `agentic-security secure`.
+//
+// One entry point that inspects project state and tells the user the single
+// best next action. The vibecoder doesn't have to choose between /scan,
+// /fix, /launch-check, /report-card, /find-and-fix-everything, etc.
+//
+// Decision tree (cheap, no scan):
+//   - No prior scan?              → run /scan first
+//   - Prior scan, criticals open? → run /fix --all --critical
+//   - Prior scan, highs open?     → /fix --all --high  OR  /show-findings
+//   - Prior scan, only mediums?   → /report-card
+//   - All clean?                  → /security-badge   (celebrate + share)
+//   - Pre-deploy intent (--launch flag, or no scan in 7 days)? → /launch-check
+//
+// Returns { action, command, reason }.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+function readJson(fp) {
+  if (!fs.existsSync(fp)) return null;
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
+}
+
+function ageHours(fp) {
+  if (!fs.existsSync(fp)) return Infinity;
+  return (Date.now() - fs.statSync(fp).mtimeMs) / 3_600_000;
+}
+
+export function decide({ scanRoot, intent }) {
+  const stateDir = path.join(scanRoot, '.agentic-security');
+  const lastScan = readJson(path.join(stateDir, 'last-scan.json'));
+  const scanAge = ageHours(path.join(stateDir, 'last-scan.json'));
+
+  if (!lastScan) {
+    return {
+      action: 'first-scan',
+      command: 'agentic-security scan .',
+      reason: 'No prior scan found. Start with a full sweep.',
+    };
+  }
+
+  const findings = [
+    ...(lastScan.findings || []),
+    ...(lastScan.secrets || []),
+    ...(lastScan.supplyChain || []),
+  ];
+  const sev = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+  for (const f of findings) sev[f.severity] = (sev[f.severity] || 0) + 1;
+
+  if (intent === 'launch' || intent === 'deploy') {
+    if (sev.critical > 0) return {
+      action: 'block-launch',
+      command: 'agentic-security fix --finding <id> --apply',
+      reason: `${sev.critical} critical finding(s) — do NOT deploy. Fix first.`,
+    };
+    return {
+      action: 'launch-check',
+      command: 'claude /launch-check',
+      reason: 'Pre-deploy checklist (HTTPS, headers, env hygiene, rate limits).',
+    };
+  }
+
+  if (sev.critical > 0) {
+    return {
+      action: 'fix-critical',
+      command: 'agentic-security fix --finding <id> --preview',
+      reason: `${sev.critical} critical finding(s) open. Preview each fix, then --apply.`,
+    };
+  }
+  if (sev.high > 0) {
+    return {
+      action: 'review-high',
+      command: 'claude /show-findings',
+      reason: `${sev.high} high finding(s). Review and triage before fixing.`,
+    };
+  }
+  if (scanAge > 24 * 7) {
+    return {
+      action: 'rescan',
+      command: 'agentic-security scan .',
+      reason: `Last scan was ${Math.round(scanAge / 24)} days ago. Re-scan for fresh CVEs.`,
+    };
+  }
+  if (sev.medium > 0) {
+    return {
+      action: 'report-card',
+      command: 'claude /report-card',
+      reason: `Only mediums remain. Get a letter-grade snapshot and pick what's worth fixing.`,
+    };
+  }
+  return {
+    action: 'celebrate',
+    command: 'claude /security-badge',
+    reason: 'Clean scan. Generate a badge for your README and share the win.',
+  };
+}
+
+export function explain(decision) {
+  const lines = [
+    `🛡  agentic-security · next step`,
+    ``,
+    `  Action:  ${decision.action}`,
+    `  Why:     ${decision.reason}`,
+    `  Run:     ${decision.command}`,
+    ``,
+  ];
+  return lines.join('\n');
+}