@blamejs/exceptd-skills 0.9.4 → 0.10.0

package/bin/exceptd.js

@@ -24,6 +24,19 @@
  *   validate-rfcs [args]  Cross-check RFC catalog against Datatracker.
  *   watchlist [args]      Forward-watch aggregator.
  *   verify                Verify every skill's Ed25519 signature.
+ *
+ * Seven-phase playbook contract (govern → direct → look → detect →
+ * analyze → validate → close):
+ *
+ *   plan                  List playbooks + directives for session planning.
+ *   govern <playbook>     Phase 1: load GRC context.
+ *   direct <playbook>     Phase 2: scope the investigation.
+ *   look <playbook>       Phase 3: emit artifact-collection spec for agent.
+ *   run <playbook>        Phases 4-7 (detect/analyze/validate/close) from
+ *                         agent submission JSON.
+ *   ingest                Alias for `run` matching AGENTS.md terminology.
+ *   reattest <session>    Re-run a prior session and diff evidence_hash.
+ *
  *   help, --help, -h      This help.
  *   version, --version,
  *     -v                  Print the package version.
@@ -68,11 +81,27 @@ const COMMANDS = {
   "validate-cves": () => path.join(PKG_ROOT, "orchestrator", "index.js"),
   "validate-rfcs": () => path.join(PKG_ROOT, "orchestrator", "index.js"),
   watchlist:       () => path.join(PKG_ROOT, "orchestrator", "index.js"),
+  "framework-gap": () => path.join(PKG_ROOT, "orchestrator", "index.js"),
+  "framework-gap-analysis": () => path.join(PKG_ROOT, "orchestrator", "index.js"),
+  // Seven-phase playbook verbs — handled in-process via lib/playbook-runner.js.
+  plan:     null,
+  govern:   null,
+  direct:   null,
+  look:     null,
+  run:      null,
+  ingest:   null,
+  reattest: null,
 };
 
 const ORCHESTRATOR_PASSTHROUGH = new Set([
   "scan", "dispatch", "skill", "currency", "report",
   "validate-cves", "validate-rfcs", "watchlist",
+  "framework-gap", "framework-gap-analysis",
+]);
+
+// Seven-phase playbook verbs handled in-process (no subprocess dispatch).
+const PLAYBOOK_VERBS = new Set([
+  "plan", "govern", "direct", "look", "run", "ingest", "reattest",
 ]);
 
 function readPkgVersion() {
@@ -118,6 +147,31 @@ Analyst:
   validate-rfcs [args]       Cross-check RFC catalog vs IETF Datatracker.
   watchlist [args]           Forward-watch aggregator across skills.
 
+Playbook runner — seven-phase contract
+(govern → direct → look → detect → analyze → validate → close):
+  plan [--playbook id]...    List playbooks + directives (planning JSON).
+                             [--mode m] [--session-id id] [--pretty]
+  govern <playbook>          Phase 1: GRC context (jurisdictions, theater,
+                             framework gaps, skill_preload).
+                             [--directive id] [--mode m] [--air-gap]
+  direct <playbook>          Phase 2: scope (threat_context, rwep_threshold,
+                             skill_chain, token_budget).
+                             [--directive id]
+  look <playbook>            Phase 3: artifact-collection spec the host AI
+                             should execute.
+                             [--directive id] [--air-gap]
+  run <playbook>             Phases 4-7: detect → analyze → validate → close
+                             from an agent submission JSON.
+                             [--directive id] [--evidence file|-]
+                             [--session-id id] [--session-key hex]
+                             [--force-stale] [--air-gap]
+  ingest                     Alias for 'run' matching AGENTS.md terminology.
+                             [--domain id] [--directive id] [--evidence f|-]
+  reattest <session-id>      Re-run prior attestation, diff evidence_hash,
+                             report unchanged | drifted | resolved.
+
+Output flags (playbook verbs): default JSON one-line; --pretty for indented.
+
 Common:
   help                       This help.
   version                    Package version.
@@ -155,6 +209,13 @@ function main() {
     process.exit(0);
   }
 
+  // Seven-phase playbook verbs run in-process — they emit JSON to stdout
+  // rather than dispatch to a script.
+  if (PLAYBOOK_VERBS.has(cmd)) {
+    dispatchPlaybook(cmd, rest);
+    return;
+  }
+
   const resolver = COMMANDS[cmd];
   if (typeof resolver !== "function") {
     process.stderr.write(`exceptd: unknown command "${cmd}". Run \`exceptd help\` for the list.\n`);
@@ -178,6 +239,347 @@ function main() {
   process.exit(typeof res.status === "number" ? res.status : 1);
 }
 
+// ---------------------------------------------------------------------------
+// Seven-phase playbook dispatch (in-process)
+// ---------------------------------------------------------------------------
+
+/**
+ * Tiny POSIX-ish argv parser. Recognised forms:
+ *   --flag                       → boolean true
+ *   --key value                  → string
+ *   --key=value                  → string
+ *   --repeatable v1 --repeatable v2 → array (when listed in `multi`)
+ * Bare positional args land in `_`. Unknown flags fall through as booleans /
+ * strings using the same rules so the harness stays forgiving for future
+ * additions without forcing a schema bump here.
+ */
+function parseArgs(argv, opts) {
+  const knownBool = new Set(opts.bool || []);
+  const knownMulti = new Set(opts.multi || []);
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      const key = (eq === -1 ? a.slice(2) : a.slice(2, eq));
+      if (eq !== -1) {
+        const val = a.slice(eq + 1);
+        if (knownMulti.has(key)) { (out[key] = out[key] || []).push(val); }
+        else out[key] = val;
+        continue;
+      }
+      if (knownBool.has(key)) { out[key] = true; continue; }
+      // Look ahead for a value; if next token is another flag, treat as bool.
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        out[key] = true;
+      } else {
+        if (knownMulti.has(key)) { (out[key] = out[key] || []).push(next); }
+        else out[key] = next;
+        i++;
+      }
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+function emit(obj, pretty) {
+  const s = pretty ? JSON.stringify(obj, null, 2) : JSON.stringify(obj);
+  process.stdout.write(s + "\n");
+}
+
+function emitError(msg, extra, pretty) {
+  const body = Object.assign({ ok: false, error: msg }, extra || {});
+  const s = pretty ? JSON.stringify(body, null, 2) : JSON.stringify(body);
+  process.stderr.write(s + "\n");
+  process.exit(1);
+}
+
+function readEvidence(evidenceFlag) {
+  if (!evidenceFlag) return {};
+  if (evidenceFlag === "-") {
+    const buf = fs.readFileSync(0, "utf8"); // stdin
+    if (!buf.trim()) return {};
+    return JSON.parse(buf);
+  }
+  return JSON.parse(fs.readFileSync(evidenceFlag, "utf8"));
+}
+
+function loadRunner() {
+  return require(path.join(PKG_ROOT, "lib", "playbook-runner.js"));
+}
+
+function firstDirectiveId(runner, playbookId) {
+  const pb = runner.loadPlaybook(playbookId);
+  if (!pb.directives || !pb.directives.length) {
+    throw new Error(`Playbook ${playbookId} has no directives.`);
+  }
+  return pb.directives[0].id;
+}
+
+function dispatchPlaybook(cmd, argv) {
+  const args = parseArgs(argv, {
+    bool:  ["pretty", "air-gap", "force-stale"],
+    multi: ["playbook"],
+  });
+  const pretty = !!args.pretty;
+  const runOpts = {
+    airGap: !!args["air-gap"],
+    forceStale: !!args["force-stale"],
+  };
+  if (args["session-id"]) runOpts.session_id = args["session-id"];
+  if (args["session-key"]) runOpts.session_key = args["session-key"];
+  if (args.mode) runOpts.mode = args.mode;
+
+  let runner;
+  try {
+    runner = loadRunner();
+  } catch (e) {
+    emitError(`Failed to load lib/playbook-runner.js: ${e.message}`, null, pretty);
+    return;
+  }
+
+  try {
+    switch (cmd) {
+      case "plan":     return cmdPlan(runner, args, runOpts, pretty);
+      case "govern":   return cmdGovern(runner, args, runOpts, pretty);
+      case "direct":   return cmdDirect(runner, args, pretty);
+      case "look":     return cmdLook(runner, args, runOpts, pretty);
+      case "run":      return cmdRun(runner, args, runOpts, pretty);
+      case "ingest":   return cmdIngest(runner, args, runOpts, pretty);
+      case "reattest": return cmdReattest(runner, args, runOpts, pretty);
+    }
+  } catch (e) {
+    emitError(e.message, { verb: cmd }, pretty);
+  }
+}
+
+function cmdPlan(runner, args, runOpts, pretty) {
+  const playbookIds = args.playbook
+    ? (Array.isArray(args.playbook) ? args.playbook : [args.playbook])
+    : null;
+  const plan = runner.plan({
+    playbookIds: playbookIds || undefined,
+    mode: runOpts.mode,
+    session_id: runOpts.session_id,
+  });
+  emit(plan, pretty);
+}
+
+function cmdGovern(runner, args, runOpts, pretty) {
+  const playbookId = args._[0];
+  if (!playbookId) return emitError("govern: missing <playbookId> positional argument.", null, pretty);
+  const pb = runner.loadPlaybook(playbookId);
+  const directiveId = args.directive || (pb.directives[0] && pb.directives[0].id);
+  if (!directiveId) return emitError(`govern: playbook ${playbookId} has no directives.`, null, pretty);
+  emit(runner.govern(playbookId, directiveId, runOpts), pretty);
+}
+
+function cmdDirect(runner, args, pretty) {
+  const playbookId = args._[0];
+  if (!playbookId) return emitError("direct: missing <playbookId> positional argument.", null, pretty);
+  const pb = runner.loadPlaybook(playbookId);
+  const directiveId = args.directive || (pb.directives[0] && pb.directives[0].id);
+  if (!directiveId) return emitError(`direct: playbook ${playbookId} has no directives.`, null, pretty);
+  emit(runner.direct(playbookId, directiveId), pretty);
+}
+
+function cmdLook(runner, args, runOpts, pretty) {
+  const playbookId = args._[0];
+  if (!playbookId) return emitError("look: missing <playbookId> positional argument.", null, pretty);
+  const pb = runner.loadPlaybook(playbookId);
+  const directiveId = args.directive || (pb.directives[0] && pb.directives[0].id);
+  if (!directiveId) return emitError(`look: playbook ${playbookId} has no directives.`, null, pretty);
+  emit(runner.look(playbookId, directiveId, runOpts), pretty);
+}
+
+function cmdRun(runner, args, runOpts, pretty) {
+  const playbookId = args._[0];
+  if (!playbookId) return emitError("run: missing <playbookId> positional argument.", null, pretty);
+  const pb = runner.loadPlaybook(playbookId);
+  const directiveId = args.directive || (pb.directives[0] && pb.directives[0].id);
+  if (!directiveId) return emitError(`run: playbook ${playbookId} has no directives.`, null, pretty);
+
+  let submission = {};
+  if (args.evidence) {
+    try {
+      submission = readEvidence(args.evidence);
+    } catch (e) {
+      return emitError(`run: failed to read evidence: ${e.message}`, { evidence: args.evidence }, pretty);
+    }
+  }
+
+  // Lift precondition_checks out of the submission into runOpts so the agent
+  // can declare host-platform / tool-availability facts in one JSON blob.
+  if (submission.precondition_checks) {
+    runOpts.precondition_checks = submission.precondition_checks;
+  }
+
+  const result = runner.run(playbookId, directiveId, submission, runOpts);
+
+  // Persist attestation for reattest cycles when the run succeeded.
+  if (result && result.ok && result.session_id) {
+    try {
+      const dir = path.join(process.cwd(), ".exceptd", "attestations", result.session_id);
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(
+        path.join(dir, "attestation.json"),
+        JSON.stringify({
+          session_id: result.session_id,
+          playbook_id: result.playbook_id,
+          directive_id: result.directive_id,
+          evidence_hash: result.evidence_hash,
+          submission,
+          run_opts: { airGap: runOpts.airGap, forceStale: runOpts.forceStale, mode: runOpts.mode },
+          captured_at: new Date().toISOString(),
+        }, null, 2)
+      );
+    } catch { /* non-fatal — attestation persistence is best-effort */ }
+  }
+
+  if (result && result.ok === false) {
+    process.stderr.write((pretty ? JSON.stringify(result, null, 2) : JSON.stringify(result)) + "\n");
+    process.exit(1);
+  }
+  emit(result, pretty);
+}
+
+function cmdIngest(runner, args, runOpts, pretty) {
+  // `ingest` matches the AGENTS.md ingest contract. The submission JSON may
+  // carry playbook_id + directive_id; --domain/--directive flags override.
+  let submission = {};
+  if (args.evidence) {
+    try {
+      submission = readEvidence(args.evidence);
+    } catch (e) {
+      return emitError(`ingest: failed to read evidence: ${e.message}`, { evidence: args.evidence }, pretty);
+    }
+  }
+  const playbookId = args.domain || submission.playbook_id || submission.domain;
+  if (!playbookId) return emitError("ingest: no playbook resolved — pass --domain <id> or include playbook_id in evidence JSON.", null, pretty);
+  const pb = runner.loadPlaybook(playbookId);
+  const directiveId = args.directive
+    || submission.directive_id
+    || (pb.directives[0] && pb.directives[0].id);
+  if (!directiveId) return emitError(`ingest: playbook ${playbookId} has no directives.`, null, pretty);
+
+  // Strip the routing keys so the runner only sees the contract shape it expects.
+  const cleanedSubmission = {
+    artifacts: submission.artifacts || {},
+    signal_overrides: submission.signal_overrides || {},
+    signals: submission.signals || {},
+  };
+
+  if (submission.precondition_checks) {
+    runOpts.precondition_checks = submission.precondition_checks;
+  }
+
+  const result = runner.run(playbookId, directiveId, cleanedSubmission, runOpts);
+
+  if (result && result.ok && result.session_id) {
+    try {
+      const dir = path.join(process.cwd(), ".exceptd", "attestations", result.session_id);
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(
+        path.join(dir, "attestation.json"),
+        JSON.stringify({
+          session_id: result.session_id,
+          playbook_id: result.playbook_id,
+          directive_id: result.directive_id,
+          evidence_hash: result.evidence_hash,
+          submission: cleanedSubmission,
+          run_opts: { airGap: runOpts.airGap, forceStale: runOpts.forceStale, mode: runOpts.mode },
+          captured_at: new Date().toISOString(),
+        }, null, 2)
+      );
+    } catch { /* non-fatal */ }
+  }
+
+  if (result && result.ok === false) {
+    process.stderr.write((pretty ? JSON.stringify(result, null, 2) : JSON.stringify(result)) + "\n");
+    process.exit(1);
+  }
+  emit(result, pretty);
+}
+
+function cmdReattest(runner, args, runOpts, pretty) {
+  const sessionId = args._[0];
+  if (!sessionId) return emitError("reattest: missing <session-id> positional argument.", null, pretty);
+  const dir = path.join(process.cwd(), ".exceptd", "attestations", sessionId);
+  const attFile = path.join(dir, "attestation.json");
+  if (!fs.existsSync(attFile)) {
+    return emitError(`reattest: no attestation found at ${path.relative(process.cwd(), attFile)}`, { session_id: sessionId }, pretty);
+  }
+  let prior;
+  try {
+    prior = JSON.parse(fs.readFileSync(attFile, "utf8"));
+  } catch (e) {
+    return emitError(`reattest: failed to parse prior attestation: ${e.message}`, { session_id: sessionId }, pretty);
+  }
+
+  // Re-run with an empty submission against the same playbook/directive.
+  // Preserve only precondition_checks from the prior submission so the runner
+  // doesn't halt on host-environment guards (the reattest is about evidence
+  // drift, not re-verifying that the host is still Linux etc.).
+  const emptySubmission = { artifacts: {}, signal_overrides: {}, signals: {} };
+  const replayOpts = Object.assign({}, runOpts, {
+    airGap: !!(prior.run_opts && prior.run_opts.airGap) || runOpts.airGap,
+    forceStale: true, // bypass currency block on reattest — drift comparison is the point
+  });
+  if (prior.submission && prior.submission.precondition_checks) {
+    replayOpts.precondition_checks = prior.submission.precondition_checks;
+  } else {
+    // Fallback: synthesise pass-through preconditions from the playbook so the
+    // replay isn't blocked when the operator didn't originally pass them.
+    try {
+      const pb = runner.loadPlaybook(prior.playbook_id);
+      const synth = {};
+      for (const pc of (pb._meta && pb._meta.preconditions) || []) synth[pc.id] = true;
+      replayOpts.precondition_checks = synth;
+    } catch { /* ignore */ }
+  }
+  const replay = runner.run(prior.playbook_id, prior.directive_id, emptySubmission, replayOpts);
+
+  if (!replay || replay.ok === false) {
+    return emitError(`reattest: replay failed: ${replay && replay.reason || "unknown"}`, { replay }, pretty);
+  }
+
+  const priorHash = prior.evidence_hash;
+  const newHash = replay.evidence_hash;
+  let status;
+  if (priorHash === newHash) {
+    status = "unchanged";
+  } else {
+    // If the original was a detected finding and the replay no longer detects,
+    // call it "resolved"; otherwise "drifted".
+    const priorClassification = (prior.submission && prior.submission.signals
+      && prior.submission.signals.detection_classification) || null;
+    const newClassification = replay.phases && replay.phases.detect && replay.phases.detect.classification;
+    if (priorClassification === "detected" && newClassification !== "detected") {
+      status = "resolved";
+    } else {
+      status = "drifted";
+    }
+  }
+
+  emit({
+    ok: true,
+    verb: "reattest",
+    session_id: sessionId,
+    playbook_id: prior.playbook_id,
+    directive_id: prior.directive_id,
+    status,
+    prior_evidence_hash: priorHash,
+    replay_evidence_hash: newHash,
+    prior_captured_at: prior.captured_at,
+    replayed_at: new Date().toISOString(),
+    replay_classification: replay.phases && replay.phases.detect && replay.phases.detect.classification,
+    replay_rwep_adjusted: replay.phases && replay.phases.analyze && replay.phases.analyze.rwep && replay.phases.analyze.rwep.adjusted,
+  }, pretty);
+}
+
 if (require.main === module) main();
 
-module.exports = { COMMANDS, PKG_ROOT };
+module.exports = { COMMANDS, PKG_ROOT, PLAYBOOK_VERBS };

package/data/_indexes/_meta.json

@@ -1,10 +1,10 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-05-12T03:28:40.863Z",
+  "generated_at": "2026-05-12T05:54:24.968Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 49,
   "source_hashes": {
-    "manifest.json": "df707e6e95191a5b63e7223abadf716f01155477b113d5688092ed53bf4639b0",
+    "manifest.json": "d10eff5e3267bca05be76ef3146f0ccd995a4d5a2dd5c958430b251432dfadff",
     "data/atlas-ttps.json": "1500b5830dab070c4252496964a8c0948e1052a656e2c7c6e1efaf0350645e13",
     "data/cve-catalog.json": "a81d3e4b491b27ccc084596b063a6108ff10c9eb01d7776922fc393980b534fe",
     "data/cwe-catalog.json": "c3367d469b4b3d31e4c56397dd7a8305a0be338ecd85afa27804c0c9ce12157b",
@@ -78,7 +78,7 @@
     "jurisdiction_clocks": 29,
     "did_ladders": 8,
     "theater_fingerprints": 7,
-    "currency_action_required": 8,
+    "currency_action_required": 0,
     "frequency_fields": 7,
     "activity_feed_events": 49,
     "catalog_summaries": 10,