@blamejs/exceptd-skills 0.12.23 → 0.12.24

package/data/_indexes/_meta.json

@@ -1,10 +1,10 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-05-15T14:25:49.905Z",
+  "generated_at": "2026-05-15T18:45:49.423Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 50,
   "source_hashes": {
-    "manifest.json": "6fda2187c6d4dfbc333a711cea0991d59c459ded1ed5005126a8c555b9e77cf2",
+    "manifest.json": "557bf7b459de4fb6af3d0bbad86626bf76581f44e31c30e240682ca87dbb9f69",
     "data/atlas-ttps.json": "20339e0ae3cd89c06f1385be31c50f408f827edc2e8ab8aef026ade3bcf0a917",
     "data/attack-techniques.json": "6db08a8e8a4d03d9309b1d185112de7f3c9595d2cd3d24566b7ce0b3b8aa5d1a",
     "data/cve-catalog.json": "7936ba3c8f27156235bf327830e8f1a684658865e97f089aed98b2a7cdbb88ef",

package/data/playbooks/containers.json

@@ -257,7 +257,7 @@
         "monitor": 65,
         "close": 35
       },
-      "framework_lag_declaration": "NIST 800-190 + CIS K8s Benchmark + NIST 800-53 CM-7 + ISO A.8.9 + PCI Req.2.2 collectively cover container hardening but accept cluster-wide attestation as evidence. None require per-manifest analysis as a control. Manifest drift in GitOps repos can introduce privileged: true / hostPID / unscoped capabilities faster than any attestation cadence. EU CRA + NIST SSDF + SLSA cover supply-chain posture but most orgs are at SLSA L1-L2 without digest pinning. Gap = ~21 days between manifest drift and review cadence; per-CVE gap (e.g. Leaky Vessels) is hours from public PoC to weaponization vs. weeks of node-staging windows. UK CAF Principles B4 (System Security) and B5 (Resilient Networks & Systems) treat container-runtime hardening as an outcome assessable via attestation, without binding evidence to per-manifest privileged-flag or host-namespace exposure. AU Essential 8 ML2 Application Control (E8 M.1) + Configure Microsoft Office Macro Settings (E8 M.2 — by analogy, application-execution policy) plus ACSC ISM-1546 and ISM-1683 (workload isolation) cover application execution and workload separation, but Essential 8 has no maturity-level requirement that bans privileged + hostPID + hostNetwork in cluster manifests.",
+      "framework_lag_declaration": "NIST 800-190 + CIS K8s Benchmark + NIST 800-53 CM-7 + ISO A.8.9 + PCI Req.2.2 collectively cover container hardening but accept cluster-wide attestation as evidence. None require per-manifest analysis as a control. Manifest drift in GitOps repos can introduce privileged: true / hostPID / unscoped capabilities faster than any attestation cadence. EU CRA + NIST SSDF + SLSA cover supply-chain posture but most orgs are at SLSA L1-L2 without digest pinning. Gap = ~21 days between manifest drift and review cadence; per-CVE gap (e.g. Leaky Vessels) is hours from public PoC to weaponization vs. weeks of node-staging windows. UK CAF Principles B4 (System Security) and B5 (Resilient Networks & Systems) treat container-runtime hardening as an outcome assessable via attestation, without binding evidence to per-manifest privileged-flag or host-namespace exposure. AU Essential 8 Strategy 1 (Application Control, E8 M.1 ML2) covers execution allowlisting on workstations/servers but does not bind to Kubernetes admission-controller policy: privileged-pod denial via OPA/Kyverno or PodSecurity `restricted` admission is the operational analogue, and Essential 8 has no maturity-level requirement enforcing it. ACSC ISM-1546 and ISM-1683 (workload isolation) name workload separation but stop short of banning privileged + hostPID + hostNetwork in cluster manifests as an attested admission-time gate.",
       "skill_chain": [
         {
           "skill": "container-runtime-security",

package/data/playbooks/crypto-codebase.json

@@ -322,7 +322,7 @@
         "monitor": 45,
         "close": 25
       },
-      "framework_lag_declaration": "Frameworks structurally bind the OPERATING organization, not the library author. NIST 800-53 SC-13, ISO 27001:2022 A.8.24/A.8.28, PCI DSS 4.0 §3.6/§8.3.2 all push obligations downstream to consumers who inherit the shipped defaults. EU CRA Annex I §1 is the first framework with direct upstream obligations on manufacturers of products with digital elements, but its binding date for vulnerability-handling and SBOM provisions is 2026-09-11 (four months from now) with full compliance 2027-12-11. NIS2 Art.21(2)(g) exerts indirect pressure via essential-entity consumers. UK CAF C.5 + UK PSTI covers connected products only. ISO 27001:2022 A.8.28 'secure coding' is silent on PQC, KDF iteration minimums, RNG-source requirements, constant-time-implementation requirements — the longest structural laggard. NIST IR 8547 + OMB M-23-02 + CNSA 2.0 push federal-system PQC migration through 2030 but rely on procurement pressure to flow upstream. Gap = ~365 days from operational PQC readiness (2024-08-13 FIPS finalization) to binding library-author obligations (2026-09-11 EU CRA partial bind). Compensating controls (downstream-consumer adoption pressure, supply-chain auditing tools, voluntary SECURITY.md disclosure of cryptographic provenance) must close this gap pending EU CRA enforcement. AU Essential 8 ML2 Patch Applications (E8 M.2) plus ACSC ISM-1138 (cryptographic-algorithm transition), ISM-0467 (approved cryptographic algorithms), and ISM-0471 (cryptographic protocol selection) reference downstream consumer migration but place no obligation on upstream library authors to ship PQC-by-default, KDF iteration minima, or constant-time implementations — Essential 8 evidence flows from operating-org posture, not from library-publisher posture.",
+      "framework_lag_declaration": "Frameworks structurally bind the OPERATING organization, not the library author. NIST 800-53 SC-13, ISO 27001:2022 A.8.24/A.8.28, PCI DSS 4.0 §3.6/§8.3.2 all push obligations downstream to consumers who inherit the shipped defaults. EU CRA Annex I §1 is the first framework with direct upstream obligations on manufacturers of products with digital elements, but its binding date for vulnerability-handling and SBOM provisions is 2026-09-11 (four months from now) with full compliance 2027-12-11. NIS2 Art.21(2)(g) exerts indirect pressure via essential-entity consumers. UK CAF C.5 + UK PSTI covers connected products only. ISO 27001:2022 A.8.28 'secure coding' is silent on PQC, KDF iteration minimums, RNG-source requirements, constant-time-implementation requirements — the longest structural laggard. NIST IR 8547 + OMB M-23-02 + CNSA 2.0 push federal-system PQC migration through 2030 but rely on procurement pressure to flow upstream. Gap = ~365 days from operational PQC readiness (2024-08-13 FIPS finalization) to binding library-author obligations (2026-09-11 EU CRA partial bind). Compensating controls (downstream-consumer adoption pressure, supply-chain auditing tools, voluntary SECURITY.md disclosure of cryptographic provenance) must close this gap pending EU CRA enforcement. AU Essential 8 ML2 Patch Applications (E8 M.2) plus ACSC ISM-1138 (cryptographic-algorithm transition), ISM-0467 (approved cryptographic algorithms), and ISM-0471 (cryptographic protocol selection) reference downstream consumer migration but place no obligation on upstream library authors to ship PQC-by-default, KDF iteration minima, or constant-time implementations — Essential 8 evidence flows from operating-org posture, not from library-publisher posture. UK CAF Principle C.5 (System Security — outcome-tested cryptographic deployments) and UK PSTI together lag because CAF C.5 mandates outcome-tested cryptographic deployments at the operator but does not require library authors to ship PQC-by-default, constant-time implementations, or KDF iteration minima; PSTI scope is connected products only and excludes upstream library distribution entirely. The library-author surface therefore sits in a coverage seam between CAF (operator-side) and PSTI (finished-product-side) — neither binds the upstream publisher.",
       "skill_chain": [
         {
           "skill": "pqc-first",

package/data/playbooks/framework.json

@@ -320,7 +320,7 @@
         "monitor": 40,
         "close": 20
       },
-      "framework_lag_declaration": "All 20 frameworks listed in domain.frameworks_in_scope are structurally insufficient for at least one upstream-playbook threat class. ISO 27001:2022, SOC 2 TSC, and PCI DSS 4.0 are the longest-laggard for AI/MCP/PQC threats (no scheduled amendments). NIST 800-53, NIS2, DORA, EU AI Act, and EU CRA have publishing cadences but lag the threat tempo by 90-365 days. UK CAF (outcome-based) and AU Essential 8 are partially forward-compatible but inconsistent across regulators/sectors. SG MAS TRM, JP FISC, IN CERT-In, CA OSFI B-10 are sector- and jurisdiction-specific with tempo varying by sector. Compound effect: an org running all current threat-class exposures under a single audit opinion is the modal state in mid-2026, not an outlier.",
+      "framework_lag_declaration": "All 20 frameworks listed in domain.frameworks_in_scope are structurally insufficient for at least one upstream-playbook threat class. ISO 27001:2022, SOC 2 TSC, and PCI DSS 4.0 are the longest-laggard for AI/MCP/PQC threats (no scheduled amendments). NIST 800-53, NIS2, DORA, EU AI Act, and EU CRA have publishing cadences but lag the threat tempo by 90-365 days. UK CAF (outcome-based) and AU Essential 8 are partially forward-compatible but inconsistent across regulators/sectors. SG MAS TRM, JP FISC, IN CERT-In, CA OSFI B-10 are sector- and jurisdiction-specific with tempo varying by sector. Compound effect: an org running all current threat-class exposures under a single audit opinion is the modal state in mid-2026, not an outlier. Named per-framework lags: NIST 800-53 CA-7 (Continuous Monitoring) lags because it is designed for control-effectiveness assessment and does not require correlation across frameworks to surface paper-vs-actual evidence. EU NIS2 Art.21(2) lags because it enumerates 10 risk-management categories but does not require operators to correlate their asset inventory against EU AI Act risk classifications when AI systems are present. UK CAF Principle A (Governance) lags because it is designed to assess governance-of-cyber-resilience outcomes and does not require correlation of `outcome-test` failures across CAF outcomes to surface compliance-theater. AU Essential 8 Strategy 1 (Application Control, ML2) lags because it is designed for execution allowlisting on workstations/servers and does not reach AI-tool-and-MCP-server allowlisting as a sub-class of executable trust. ISO/IEC 27001:2022 A.5.1 (Policies for information security) lags because it requires top-level policy presence and does not require cross-framework gap analysis as part of policy maintenance.",
       "skill_chain": [
         {
           "skill": "framework-gap-analysis",

package/data/playbooks/hardening.json

@@ -226,7 +226,7 @@
         "monitor": 65,
         "close": 30
       },
-      "framework_lag_declaration": "NIST CM-6, ISO A.8.9, Essential 8 OS Hardening, CMMC CM.L2-3.4.1/2 all permit baseline + change-management evidence without requiring continuous attestation of the specific kernel hardening flags (kptr_restrict, unprivileged_userns_clone, unprivileged_bpf_disabled, yama.ptrace_scope, dmesg_restrict, kernel.lockdown, MAC enforcement mode) that determine whether a vulnerable kernel is actually exploitable. Gap = ~21 days at typical orgs between drift event and review. For environments using GitOps-deployed kernel parameters, drift can occur faster than monitoring catches. UK CAF Principles B4 (System Security) and B5 (Resilient Networks & Systems) treat OS hardening as a system-security outcome assessable via baseline-and-change-management evidence, without binding to continuous attestation of specific kernel hardening flags (kptr_restrict, unprivileged_userns_clone, unprivileged_bpf_disabled, yama.ptrace_scope, dmesg_restrict, kernel.lockdown, MAC enforcement) — CAF evidence passes against a host whose flags drifted hours after the last review. AU Essential 8 ML2 Patch Operating Systems (E8 M.2) + Restrict Admin Privileges (E8 M.5) and ACSC ISM-1144 / ISM-1493 (vulnerability management) reference OS-hardening posture but do not enumerate the per-sysctl flag set whose state determines whether a vulnerable kernel is actually exploitable.",
+      "framework_lag_declaration": "NIST CM-6, ISO A.8.9, Essential 8 OS Hardening, CMMC CM.L2-3.4.1/2 all permit baseline + change-management evidence without requiring continuous attestation of the specific kernel hardening flags (kptr_restrict, unprivileged_userns_clone, unprivileged_bpf_disabled, yama.ptrace_scope, dmesg_restrict, kernel.lockdown, MAC enforcement mode) that determine whether a vulnerable kernel is actually exploitable. Gap = ~21 days at typical orgs between drift event and review. For environments using GitOps-deployed kernel parameters, drift can occur faster than monitoring catches. UK CAF Principles B4 (System Security) and B5 (Resilient Networks & Systems) treat OS hardening as a system-security outcome assessable via baseline-and-change-management evidence, without binding to continuous attestation of specific kernel hardening flags (kptr_restrict, unprivileged_userns_clone, unprivileged_bpf_disabled, yama.ptrace_scope, dmesg_restrict, kernel.lockdown, MAC enforcement) — CAF evidence passes against a host whose flags drifted hours after the last review. AU Essential 8 ML2 Patch Operating Systems (E8 M.2) + Restrict Admin Privileges (E8 M.5) and ACSC ISM-1144 / ISM-1493 (vulnerability management) reference OS-hardening posture but do not enumerate the per-sysctl flag set whose state determines whether a vulnerable kernel is actually exploitable. EU NIS2 Art.21(2)(c) `secure development lifecycle` and DORA Art.9(4) `secure configuration` both reference hardening posture obligation but stop short of requiring per-flag kernel-hardening attestation; the gap is that operators can claim compliance with `vm.mmap_min_addr` defaulted-but-not-attested, because neither framework requires the per-sysctl evidence that distinguishes a hardened kernel from a default-shipped one.",
       "skill_chain": [
         {
           "skill": "kernel-lpe-triage",

package/data/playbooks/library-author.json

@@ -477,7 +477,7 @@
         "monitor": 50,
         "close": 30
       },
-      "framework_lag_declaration": "NIST 800-53 SR-3/4/5, NIST 800-218 SSDF PS.3.2 / PW.4 / RV.2, ISO 27001:2022 A.8.30 / A.5.20, SOC 2 CC8.1 / CC9.2, NIS2 Art.21(2)(d), DORA Art.28, UK CAF C1.b, AU Essential 8 E1, and CMMC SI.L2-3.4.4 all permit publisher posture that omits (a) OIDC-based publish, (b) Sigstore / Rekor transparency-log entries per release, (c) signed + distributed SBOM, (d) transitive completeness, (e) VEX feed for filed CVEs, (f) coordinated-disclosure intake at /.well-known/security.txt, (g) tag-protection on release refs, (h) reproducible builds, (i) skill / plugin signature verification gated in the install path. Operational tooling for (a)-(i) shipped 2023-2025; framework lag = ~540 days behind tooling and ~18 months ahead of EU CRA Art.10/13/14 binding (2027). Compensating controls MUST close (a)-(i) before SSDF-only compliance can be accepted as CRA-readiness.",
+      "framework_lag_declaration": "NIST 800-53 SR-3/4/5, NIST 800-218 SSDF PS.3.2 / PW.4 / RV.2, ISO 27001:2022 A.8.30 / A.5.20, SOC 2 CC8.1 / CC9.2, NIS2 Art.21(2)(d), DORA Art.28, and CMMC SI.L2-3.4.4 all permit publisher posture that omits (a) OIDC-based publish, (b) Sigstore / Rekor transparency-log entries per release, (c) signed + distributed SBOM, (d) transitive completeness, (e) VEX feed for filed CVEs, (f) coordinated-disclosure intake at /.well-known/security.txt, (g) tag-protection on release refs, (h) reproducible builds, (i) skill / plugin signature verification gated in the install path. Operational tooling for (a)-(i) shipped 2023-2025; framework lag = ~540 days behind tooling and ~18 months ahead of EU CRA Art.10/13/14 binding (2027). UK CAF C1.b (Identity and Access Management — Privileged user management) is designed to govern human privileged users and does not require SLSA L3+ provenance attestation on every release artifact; the gap is that a compromised publisher token (no human-MFA gate, no provenance attestation) yields an attacker-signed release that passes C1.b's evidence surface. AU Essential 8 Strategy 5 (Restrict Admin Privileges, E8 M.5) is designed for runtime admin-account scoping and does not reach build-time admin privileges on signing-key material: a CI runner holding the publish credential is a build-time admin that E8 M.5 evidence does not enumerate. Compensating controls MUST close (a)-(i) before SSDF-only compliance can be accepted as CRA-readiness.",
       "skill_chain": [
         {
           "skill": "supply-chain-integrity",

package/data/playbooks/secrets.json

@@ -224,6 +224,30 @@
             "control_id": "B3 — Data security",
             "designed_for": "NCSC CAF outcome that data important to the essential function is protected from compromise, including credential and key material.",
             "insufficient_because": "Outcome can be assessed against managed secret-store contents. Plaintext credentials leaked into source-code repositories, CI logs, IaC files, and AI assistant context windows do not register on the outcome's evidence surface."
+          },
+          {
+            "framework": "au-essential-8",
+            "control_id": "Strategy 4 — Multi-factor authentication (E8 M.4)",
+            "designed_for": "MFA on privileged + internet-facing accounts.",
+            "insufficient_because": "MFA defends the interactive auth flow; bearer tokens / API keys / OAuth refresh tokens committed to source artifacts bypass MFA entirely — scraper-bot exploitation against cloud-provider APIs uses the static credential and never reaches an interactive auth surface. Compliance-theater test: audit the last 90 days of admin actions and count those executed by service-account tokens vs human-MFA sessions; if service tokens dominate, Strategy 4 compliance is paper."
+          },
+          {
+            "framework": "au-essential-8",
+            "control_id": "Strategy 1 — Application Control (E8 M.1)",
+            "designed_for": "Execution allowlisting on workstations and servers.",
+            "insufficient_because": "Application Control governs runtime execution but does not constrain build agents reading from arbitrary secret stores or environment variables at build time — CI runners with broad env-var access defeat the intent. Compliance-theater test: inventory CI runner environment variables; any token-shaped string (regex /[A-Za-z0-9]{32,}/) means ML2 compliance leaks at build time."
+          },
+          {
+            "framework": "au-ism",
+            "control_id": "ISM-1546",
+            "designed_for": "Multi-factor authentication for privileged users and remote access.",
+            "insufficient_because": "ISM-1546 covers human authentication; CI/CD service identities (which now hold the actual privileges) are out of scope. Stolen GitHub Actions OIDC tokens grant identical blast radius without ever crossing the human-MFA gate. Compliance-theater test: list CI runner OIDC token TTLs and audience scopes; any token with TTL > 1h or wildcard audience defeats ISM-1546's intent."
+          },
+          {
+            "framework": "au-ism",
+            "control_id": "ISM-1559",
+            "designed_for": "Privileged account credential management.",
+            "insufficient_because": "ISM-1559 names key/credential storage but treats source-code-embedded credentials as a policy violation, not a detection control. Modern exfiltration reads credentials post-decryption from /proc, container layers, or build artifacts. Compliance-theater test: run a process listing inside one production container and grep env for tokens; any hit means storage encryption was bypassed at the runtime boundary."
           }
         ]
       },
@@ -241,7 +265,7 @@
         "monitor": 60,
         "close": 30
       },
-      "framework_lag_declaration": "GDPR Art.32, ISO A.8.24, PCI-DSS Req.3, SOC 2 CC6.1 collectively cover encryption + key management + access control in production storage backends. None of them name 'secret in source artifact' as a distinct exposure category, despite this being the dominant 2025-2026 cloud-compromise vector. NIS2 Art.21(2)(j) names cryptography but not development-workflow exposure. Gap = ~30 days between developer commit and framework's quarterly access-review cadence; in practice, scraper bots exploit faster than any framework cadence. UK CAF Principle B2 (Identity and Access Control) treats credential lifecycle as an outcome reviewable on cycle, not as a per-commit scanning obligation — secrets embedded in source artifacts do not register against B2 evidence. AU Essential 8 ML2 MFA (E8 M.4) + Restrict Admin Privileges (E8 M.5) and ISM-1546 cover MFA + admin-account hygiene but provide no signal on long-lived bearer-token exposure inside developer repositories.",
+      "framework_lag_declaration": "GDPR Art.32, ISO A.8.24, PCI-DSS Req.3, SOC 2 CC6.1 collectively cover encryption + key management + access control in production storage backends. None of them name 'secret in source artifact' as a distinct exposure category, despite this being the dominant 2025-2026 cloud-compromise vector. NIST 800-53 IA-5 (Authenticator Management) lags because it mandates authenticator protection in storage but does not require detection of authenticators committed to source repositories or build artifacts — IA-5 evidence is satisfied by a vault inventory while bearer tokens leak through `.env`, IaC tfvars, and CI logs unscanned. NIS2 Art.21(2)(j) names cryptography but not development-workflow exposure. Gap = ~30 days between developer commit and framework's quarterly access-review cadence; in practice, scraper bots exploit faster than any framework cadence. UK CAF Principle B2 (Identity and Access Control) treats credential lifecycle as an outcome reviewable on cycle, not as a per-commit scanning obligation — secrets embedded in source artifacts do not register against B2 evidence. AU Essential 8 Strategy 1 (Application Control, E8 M.1) is the relevant lever — restricting build agents from accessing arbitrary secret stores or environment variables at build time — but Essential 8 evidence does not enumerate CI-runner secret-store reachability as a sub-control; ISM-1546 covers MFA + admin-account hygiene but bearer tokens / API keys / OAuth refresh tokens in source artifacts bypass MFA entirely, never crossing the interactive auth surface ISM-1546 protects.",
       "skill_chain": [
         {
           "skill": "dlp-gap-analysis",

package/lib/auto-discovery.js

@@ -365,7 +365,16 @@ function discoverNewKev(ctx, cap = DEFAULT_CAP) {
 
 // --- RFC discovery -----------------------------------------------------
 
-async function fetchDatatracker(url) {
+async function fetchDatatracker(url, ctx) {
+  // Air-gap refusal — Datatracker is a live IETF service. When the operator
+  // (or the caller's ctx) declares air-gap, return a structured refusal so
+  // refresh-external can surface "discovery skipped" rather than logging a
+  // generic network error. Caller's signature already accepts a nullable
+  // return; the structured object is distinguishable from a successful
+  // payload by `ok:false`.
+  if ((ctx && ctx.airGap === true) || process.env.EXCEPTD_AIR_GAP === "1") {
+    return { ok: false, error: "air-gap-blocked", source: "datatracker" };
+  }
   const ac = new AbortController();
   const t = setTimeout(() => ac.abort(), TIMEOUT_MS);
   try {
@@ -532,7 +541,22 @@ async function discoverNewRfcs(ctx, opts = {}) {
       `https://datatracker.ietf.org/api/v1/doc/document/` +
       `?type=rfc&group__acronym=${encodeURIComponent(wg)}` +
       `&time__gt=${cutoff}&order_by=-time&limit=20&format=json`;
-    const payload = await fetchDatatracker(url);
+    const payload = await fetchDatatracker(url, ctx);
+    // Treat the air-gap structured refusal as a discovery skip — not an
+    // error. The existing `!payload || !Array.isArray(payload.objects)`
+    // path would have classed it as `errors++`, which misreports an
+    // operator-chosen offline posture as a fault. Short-circuit the whole
+    // WG loop on first air-gap refusal because every subsequent fetch will
+    // refuse identically.
+    if (payload && payload.ok === false && payload.error === "air-gap-blocked") {
+      return {
+        diffs: [],
+        errors: 0,
+        spilled: 0,
+        summary: "RFC discovery: skipped (air-gap mode)",
+        skipped: "air-gap",
+      };
+    }
     if (!payload || !Array.isArray(payload.objects)) {
       errors++;
       continue;

package/lib/exit-codes.js

@@ -0,0 +1,72 @@
+'use strict';
+
+/**
+ * Canonical exit-code constants for every CLI verb.
+ *
+ * Every `process.exitCode = N` / `process.exit(N)` site in `bin/exceptd.js`
+ * (and any library that wants to set an exit code via emit() ok:false bodies)
+ * should reference one of these constants rather than a bare number literal.
+ * The map is the source of truth for help text — `exceptd doctor --exit-codes`
+ * dumps it as JSON so operator-facing docs cannot drift from runtime.
+ *
+ * History: prior to v0.12.24 codes were bare magic numbers scattered across
+ * ~30 sites. Code 3 in particular meant both "session-id collision" (cmdRun)
+ * and "ran-but-no-evidence" (cmdCi) — two semantics, one code, no doc surface.
+ * v0.12.24 splits them and centralises so a new verb cannot regress by typo.
+ */
+
+const EXIT_CODES = Object.freeze({
+  SUCCESS: 0,
+  GENERIC_FAILURE: 1,
+  DETECTED_ESCALATE: 2,
+  RAN_NO_EVIDENCE: 3,
+  BLOCKED: 4,
+  JURISDICTION_CLOCK_STARTED: 5,
+  TAMPERED: 6,
+  SESSION_ID_COLLISION: 7,
+  LOCK_CONTENTION: 8,
+  STORAGE_EXHAUSTED: 9,
+});
+
+/**
+ * Human-readable + machine-stable description per code. Source for the
+ * `exceptd doctor --exit-codes` dump and for help-text rendering.
+ */
+const EXIT_CODE_DESCRIPTIONS = Object.freeze({
+  0: { name: 'SUCCESS', summary: 'Verb completed successfully.' },
+  1: { name: 'GENERIC_FAILURE', summary: 'Unhandled error or validation failure.' },
+  2: { name: 'DETECTED_ESCALATE', summary: 'CI gate: classification === detected, operator action required.' },
+  3: { name: 'RAN_NO_EVIDENCE', summary: 'CI gate: verb ran but produced no actionable evidence.' },
+  4: { name: 'BLOCKED', summary: 'CI gate: ok:false body — precondition refusal or hard error.' },
+  5: { name: 'JURISDICTION_CLOCK_STARTED', summary: 'Jurisdictional notification window opened (e.g. NIS2 24h, DORA 4h, GDPR 72h).' },
+  6: { name: 'TAMPERED', summary: 'Attestation sidecar verification failed (signed-but-invalid, corrupt, unsigned-substitution, algorithm-unsupported).' },
+  7: { name: 'SESSION_ID_COLLISION', summary: 'Persisting attestation would overwrite an existing session; pass --force-overwrite to replace or supply a fresh --session-id.' },
+  8: { name: 'LOCK_CONTENTION', summary: 'Concurrent invocation holds the per-playbook attestation lock; retry after the busy run releases.' },
+  9: { name: 'STORAGE_EXHAUSTED', summary: 'Disk full, quota exceeded, or read-only filesystem prevented attestation write (ENOSPC, EDQUOT, EROFS).' },
+});
+
+/**
+ * Return the human-readable name for a numeric exit code.
+ */
+function exitCodeName(code) {
+  const e = EXIT_CODE_DESCRIPTIONS[code];
+  return e ? e.name : 'UNKNOWN';
+}
+
+/**
+ * Return all exit codes as a stable-shape array suitable for JSON dump.
+ */
+function listExitCodes() {
+  return Object.entries(EXIT_CODE_DESCRIPTIONS).map(([code, info]) => ({
+    code: Number(code),
+    name: info.name,
+    summary: info.summary,
+  }));
+}
+
+module.exports = {
+  EXIT_CODES,
+  EXIT_CODE_DESCRIPTIONS,
+  exitCodeName,
+  listExitCodes,
+};

package/lib/flag-suggest.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * Levenshtein-distance flag-typo suggestions.
+ *
+ * Operator typos `--evidnce` / `--csaf-stats` / `--bundle-epohc` were silently
+ * absorbed by the argv parser, falling through as boolean true flags with no
+ * value, then producing cryptic downstream errors. This helper compares an
+ * unknown flag to a verb-scoped allowlist and returns the closest match at
+ * distance ≤ 2 AND ≤ floor(flag.length / 2).
+ *
+ * Per-verb allowlists are the canonical CLI surface. Adding a new flag to a
+ * verb means appending to the allowlist here AND updating the printPlaybookVerbHelp
+ * block; a test asserts the two sets agree.
+ */
+
+function editDistance(a, b) {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  const prev = new Array(b.length + 1);
+  const curr = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1] + 1,
+        prev[j] + 1,
+        prev[j - 1] + cost,
+      );
+    }
+    for (let j = 0; j <= b.length; j++) prev[j] = curr[j];
+  }
+  return prev[b.length];
+}
+
+/**
+ * Suggest the closest allowlisted flag to a given unknown flag.
+ *
+ * @param {string} flag - operator-supplied flag name without leading --
+ * @param {string[]} allowlist - known flag names for the active verb
+ * @returns {string|null} the suggested flag name or null when no close match
+ */
+function suggestFlag(flag, allowlist) {
+  if (typeof flag !== 'string' || flag.length === 0) return null;
+  if (!Array.isArray(allowlist) || allowlist.length === 0) return null;
+  const probe = flag.toLowerCase();
+  const cap = Math.min(2, Math.floor(flag.length / 2));
+  let bestDist = Infinity;
+  let best = null;
+  for (const candidate of allowlist) {
+    const d = editDistance(probe, candidate.toLowerCase());
+    if (d < bestDist && d <= cap) {
+      bestDist = d;
+      best = candidate;
+    }
+  }
+  return best;
+}
+
+/**
+ * Per-verb known-flag allowlist. Every operator-facing flag should appear
+ * exactly once per verb where it is consumed. Flags consumed by every verb
+ * (e.g. `pretty`, `json`, `help`) live under '_global'.
+ */
+const VERB_FLAG_ALLOWLIST = Object.freeze({
+  _global: ['help', 'pretty', 'json', 'verbose'],
+  run: [
+    'evidence', 'evidence-dir', 'session-id', 'force-overwrite', 'attestation-root',
+    'mode', 'air-gap', 'force-stale', 'operator', 'ack', 'csaf-status',
+    'publisher-namespace', 'vex', 'diff-from-latest', 'all', 'scope',
+    'strict-preconditions', 'ci', 'block-on-jurisdiction-clock', 'upstream-check',
+    'session-key', 'tlp', 'bundle-deterministic', 'bundle-epoch',
+  ],
+  ci: [
+    'evidence', 'evidence-dir', 'session-id', 'force-overwrite', 'attestation-root',
+    'mode', 'air-gap', 'force-stale', 'operator', 'ack', 'csaf-status',
+    'publisher-namespace', 'vex', 'all', 'scope', 'required', 'format',
+    'strict-preconditions', 'block-on-jurisdiction-clock', 'tlp',
+  ],
+  'run-all': [
+    'evidence', 'evidence-dir', 'session-id', 'force-overwrite', 'attestation-root',
+    'mode', 'air-gap', 'force-stale', 'operator', 'ack', 'csaf-status',
+    'publisher-namespace', 'vex', 'scope', 'strict-preconditions', 'tlp',
+  ],
+  'ai-run': [
+    'evidence', 'no-stream', 'session-id', 'force-overwrite', 'attestation-root',
+    'operator', 'ack', 'csaf-status', 'publisher-namespace', 'air-gap',
+    'mode', 'force-stale', 'tlp',
+  ],
+  ingest: [
+    'evidence', 'session-id', 'force-overwrite', 'attestation-root', 'operator',
+    'ack', 'csaf-status', 'publisher-namespace', 'air-gap', 'force-stale',
+    'strict-preconditions',
+  ],
+  brief: ['all', 'scope', 'directives', 'flat', 'phase'],
+  discover: ['scan-only', 'scope'],
+  ask: [],
+  attest: [
+    'against', 'playbook', 'since', 'latest', 'format', 'force', 'dry-run',
+    'all-older-than',
+  ],
+  reattest: [
+    'playbook', 'since', 'latest', 'force-replay', 'attestation-root',
+  ],
+  doctor: ['signatures', 'cves', 'rfcs', 'fix', 'registry-check', 'exit-codes'],
+  lint: ['evidence'],
+  refresh: [
+    'apply', 'dry-run', 'from-cache', 'from-fixture', 'network', 'source',
+    'advisory', 'force-stale', 'force-stale-acked', 'air-gap', 'swarm',
+  ],
+  prefetch: ['source', 'cache-dir', 'max-age', 'force', 'no-network', 'quiet'],
+});
+
+/**
+ * Return the allowlist for a verb (global flags always included).
+ */
+function flagsFor(verb) {
+  const verbFlags = VERB_FLAG_ALLOWLIST[verb] || [];
+  return [...VERB_FLAG_ALLOWLIST._global, ...verbFlags];
+}
+
+module.exports = {
+  editDistance,
+  suggestFlag,
+  flagsFor,
+  VERB_FLAG_ALLOWLIST,
+};

package/lib/id-validation.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Shared validation for path-component-shaped operator inputs.
+ *
+ * Six sites in `bin/exceptd.js` previously hand-rolled regexes of the form
+ * /^[A-Za-z0-9._-]{1,64}$/ for `--session-id`, `--playbook`, attestation
+ * filenames, and `--evidence-dir` filenames. Each regex was slightly
+ * different in character class ordering; each grew its own follow-on checks
+ * (all-dots refusal, length cap, leading-dot refusal) at different rates.
+ *
+ * This module is the single source of truth. Adding a new path-component
+ * input means calling `validateIdComponent(value, role)` and propagating
+ * the returned {ok, reason} pair to the caller's emit-error path.
+ *
+ * Three role types, three character classes:
+ *   - 'session'  — sessions live under `.exceptd/attestations/<sid>/`. Allow
+ *                  lower+upper alpha, digit, dot, underscore, hyphen, 1-64
+ *                  chars. Refuse all-dots.
+ *   - 'playbook' — playbook ids index `data/playbooks/<id>.json`. Stricter:
+ *                  lowercase-only, must start with a letter, no dots (all
+ *                  catalogued playbook ids match `/^[a-z][a-z0-9-]{0,63}$/`).
+ *   - 'filename' — attestation filename inside a session directory. Same
+ *                  charset as 'session' but length cap reflects filename
+ *                  policy (no path separators ever).
+ *
+ * The function never reads the filesystem; combine with realpathSync at
+ * the caller for full path-traversal defense.
+ */
+
+const SESSION_RE = /^[A-Za-z0-9._-]{1,64}$/;
+const PLAYBOOK_RE = /^[a-z][a-z0-9-]{0,63}$/;
+const FILENAME_RE = /^[A-Za-z0-9._-]{1,80}$/;
+const ALL_DOTS_RE = /^\.+$/;
+
+function validateIdComponent(value, role) {
+  if (typeof value !== 'string') {
+    return { ok: false, reason: `expected string, got ${typeof value}` };
+  }
+  if (value.length === 0) {
+    return { ok: false, reason: 'must not be empty' };
+  }
+  let re;
+  let constraint;
+  switch (role) {
+    case 'session':
+      re = SESSION_RE;
+      constraint = '^[A-Za-z0-9._-]{1,64}$';
+      break;
+    case 'playbook':
+      re = PLAYBOOK_RE;
+      constraint = '^[a-z][a-z0-9-]{0,63}$ (lowercase, starts with letter, no dots)';
+      break;
+    case 'filename':
+      re = FILENAME_RE;
+      constraint = '^[A-Za-z0-9._-]{1,80}$';
+      break;
+    default:
+      return { ok: false, reason: `unknown role: ${role}` };
+  }
+  if (!re.test(value)) {
+    return { ok: false, reason: `must match ${constraint}` };
+  }
+  // All-dots refusal applies after the character-class regex because the
+  // session/filename classes admit any string of dots (`.`, `..`, `...`),
+  // each of which path-resolves into or above the intended directory.
+  if (ALL_DOTS_RE.test(value)) {
+    return { ok: false, reason: 'must not consist entirely of dots' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Cheap typed-throw wrapper for callers that prefer exceptions over result
+ * objects (lib/playbook-runner.js uses this shape for loadPlaybook).
+ */
+function assertIdComponent(value, role) {
+  const r = validateIdComponent(value, role);
+  if (!r.ok) {
+    const err = new Error(`invalid ${role} id (${r.reason}): ${typeof value === 'string' ? value.slice(0, 80) : typeof value}`);
+    err.code = 'EXCEPTD_INVALID_ID';
+    err.role = role;
+    err.reason = r.reason;
+    throw err;
+  }
+  return value;
+}
+
+module.exports = {
+  validateIdComponent,
+  assertIdComponent,
+  SESSION_RE,
+  PLAYBOOK_RE,
+  FILENAME_RE,
+};

package/lib/lint-skills.js

@@ -655,6 +655,59 @@ function findOrphanSkillFiles(manifestSkills) {
   return orphans;
 }
 
+// Substrings that indicate an artifact `source` makes a network call. Used
+// by lintPlaybookAirGap() to flag artifacts that lack an air_gap_alternative.
+// Conservative-by-design — false positives are surfaced as `warn` (not
+// `error`) and a playbook author who has reviewed the source can suppress
+// by adding an air_gap_alternative even when the source itself is offline.
+const PLAYBOOK_NET_PATTERNS = [
+  'https://', 'http://', 'gh api', 'gh release', 'curl ', 'wget ', 'fetch ',
+];
+
+const PLAYBOOK_DIR = path.join(DATA_DIR, 'playbooks');
+
+/**
+ * Air-gap completeness lint for shipped playbooks. Walks every
+ * data/playbooks/*.json file, examines phases.look.artifacts[], and warns
+ * when an artifact's `source` contains a network-call substring without a
+ * sibling `air_gap_alternative`. The playbook schema's hard `if/then`
+ * conditional (added v0.12.24) catches this for playbooks marked
+ * `_meta.air_gap_mode: true`; this lint surfaces the gap for every
+ * playbook, on the principle that a non-air-gap playbook may still be
+ * invoked under `exceptd --air-gap` and operators deserve the warning.
+ *
+ * Returns an array of `{ playbook, artifact_id, source }` warning records.
+ */
+function lintPlaybookAirGap() {
+  const warnings = [];
+  if (!fs.existsSync(PLAYBOOK_DIR)) return warnings;
+  const files = fs.readdirSync(PLAYBOOK_DIR).filter(f => f.endsWith('.json') && !f.startsWith('_'));
+  for (const f of files) {
+    let playbook;
+    try {
+      playbook = readJson(path.join(PLAYBOOK_DIR, f));
+    } catch {
+      continue; // schema validator catches parse errors separately
+    }
+    const arts = playbook && playbook.phases && playbook.phases.look && playbook.phases.look.artifacts;
+    if (!Array.isArray(arts)) continue;
+    for (const a of arts) {
+      if (!a || typeof a !== 'object') continue;
+      const src = a.source;
+      if (typeof src !== 'string') continue;
+      const isNet = PLAYBOOK_NET_PATTERNS.some(p => src.includes(p));
+      if (isNet && !a.air_gap_alternative) {
+        warnings.push({
+          playbook: playbook._meta && playbook._meta.id ? playbook._meta.id : f.replace(/\.json$/, ''),
+          artifact_id: a.id || '<unknown>',
+          source: src,
+        });
+      }
+    }
+  }
+  return warnings;
+}
+
 function main() {
   const opts = parseArgs(process.argv);
   const manifest = readJson(MANIFEST_PATH);
@@ -700,6 +753,7 @@ function main() {
   // A targeted single-skill lint is for diagnosing one entry; running
   // the orphan walk there would surface unrelated findings.
   let orphans = [];
+  let airGapWarnings = [];
   if (!opts.skill) {
     orphans = findOrphanSkillFiles(manifest.skills);
     for (const o of orphans) {
@@ -707,14 +761,25 @@ function main() {
       console.log(`        - skill.md exists on disk but not in manifest: ${o}`);
       console.log(`          fix: re-run \`node lib/sign.js sign-all\` after adding it to manifest.json, OR delete the orphan directory`);
     }
+    // P4 — air-gap completeness lint over data/playbooks/*.json.
+    airGapWarnings = lintPlaybookAirGap();
+    for (const w of airGapWarnings) {
+      console.log(`WARN  playbook:${w.playbook}`);
+      console.log(`        - [warn] artifact "${w.artifact_id}" source contains a network call but has no air_gap_alternative`);
+      console.log(`                 source: ${w.source}`);
+      console.log(`                 fix: add an air_gap_alternative source (offline file path / packaged dataset / pre-staged artifact)`);
+    }
   }
 
   const total = results.length;
   const passed = total - failed - warned;
   const orphanSummary = orphans.length ? `, ${orphans.length} orphan skill.md file(s)` : '';
   const warnSummary = warned ? `, ${warned} with warnings` : '';
+  const airGapSummary = airGapWarnings && airGapWarnings.length
+    ? `, ${airGapWarnings.length} playbook artifact(s) missing air_gap_alternative`
+    : '';
   console.log(
-    `\n${passed}/${total} skills passed${warnSummary}${failed ? `, ${failed} failed` : ''}${orphanSummary}.`,
+    `\n${passed}/${total} skills passed${warnSummary}${failed ? `, ${failed} failed` : ''}${orphanSummary}${airGapSummary}.`,
   );
   process.exit(failed === 0 && orphans.length === 0 ? 0 : 1);
 }
@@ -727,6 +792,8 @@ module.exports = {
   unquote,
   findOrphanSkillFiles,
   findMissingSections,
+  lintPlaybookAirGap,
+  PLAYBOOK_NET_PATTERNS,
   REQUIRED_SECTIONS,
   COUNTERMEASURE_SECTION,
   COUNTERMEASURE_CUTOFF,