@blamejs/exceptd-skills 0.19.33 → 0.19.35

package/lib/lint-skills.js

@@ -1,38 +1,7 @@
 #!/usr/bin/env node
 /*
- * lib/lint-skills.js — exceptd skill pre-ship linter.
- *
- * Enforces AGENTS.md rules that are otherwise informal:
- *   Rule #10 — No placeholder data. Skill bodies and frontmatter must not
- *              contain TODO / TBD / coming soon / placeholder / fixme / XXX
- *              / to be determined.
- *   Rule #11 — No-MVP ban. Every skill ships with complete frontmatter,
- *              all 7 required body sections, all data deps existing, and
- *              all referenced TTPs / framework controls resolving.
- *
- * For every skill registered in manifest.json this linter checks:
- *   - skill.md exists at the manifest path
- *   - frontmatter contains every required field per AGENTS.md spec
- *   - frontmatter values conform to lib/schemas/skill-frontmatter.schema.json
- *     (the subset relevant for this codebase — no external validator dep)
- *   - body contains all 7 required H2/H3 sections (case-insensitive):
- *     Threat Context, Framework Lag Declaration, TTP Mapping,
- *     Exploit Availability Matrix, Analysis Procedure, Output Format,
- *     Compliance Theater Check
- *   - body and frontmatter free of placeholder language
- *   - every data_deps filename resolves to data/<filename>
- *   - every atlas_refs ID exists as a top-level key in data/atlas-ttps.json
- *   - every framework_gaps ID exists as a top-level key in
- *     data/framework-control-gaps.json
- *
- * Usage:
- *   node lib/lint-skills.js              lint every skill
- *   node lib/lint-skills.js --skill foo  lint only the named skill
- *   node lib/lint-skills.js --quiet      only print failures and final summary
- *
- * Exit code: 0 if every linted skill passes, 1 otherwise.
- *
- * No external dependencies. Node 24 stdlib only.
+ * Pre-ship linter for the skills registered in manifest.json. Exit 0 when every
+ * linted skill passes, 1 otherwise.
  */
 
 'use strict';
@@ -69,12 +38,9 @@ const REQUIRED_FRONTMATTER_FIELDS = [
   'last_threat_review',
 ];
 
-// v0.13.2: `discovery_mode` documents how the skill is reached by operators.
-// Default (omitted) means the skill is referenced by at least one playbook's
-// direct.skill_chain. `standalone` means the skill is reached via
-// `exceptd brief <name>` or `exceptd ask` routing and is NOT chained — this
-// closes the v0.12 audit gap that 16 skills had no playbook chain pointing
-// at them. Operator intent now explicit; not a sign of orphan-skill drift.
+// `discovery_mode` records how operators reach the skill: omitted means a
+// playbook's direct.skill_chain references it; `standalone` means it is reached
+// through `exceptd brief <name>` or `ask` routing, so no chain is deliberate.
 const OPTIONAL_FRONTMATTER_FIELDS = ['forward_watch', 'rfc_refs', 'cwe_refs', 'd3fend_refs', 'dlp_refs', 'discovery_mode'];
 
 const ALL_KNOWN_FIELDS = new Set([
@@ -92,15 +58,12 @@ const REQUIRED_SECTIONS = [
   'Compliance Theater Check',
 ];
 
-// L3 — Defensive Countermeasure Mapping became a required section for skills
-// reviewed on or after this cutoff (documented in AGENTS.md). Pre-cutoff
-// skills remain exempt to preserve patch-class compatibility.
+// Required only for skills whose last_threat_review is on or after the cutoff.
 const COUNTERMEASURE_SECTION = 'Defensive Countermeasure Mapping';
 const COUNTERMEASURE_CUTOFF = '2026-05-11';
 
-// L1 — Minimum number of words of body text between a section heading and the
-// next heading (or EOF) for the section to count as populated. Header-only
-// sections surface as warnings; promoted to failures under --strict.
+// Words of body text between a section heading and the next (or EOF) for the
+// section to count as populated. Below it is a warning, an error under --strict.
 const MIN_SECTION_BODY_WORDS = 20;
 
 const PLACEHOLDER_PATTERNS = [
@@ -119,12 +82,9 @@ const SEMVER_RE = /^\d+\.\d+\.\d+$/;
 const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 
 /*
- * Strict ISO calendar-date check. ISO_DATE_RE only proves the SHAPE
- * (YYYY-MM-DD); Date.parse() silently rolls non-calendar dates over —
- * 2026-02-30 becomes 2026-03-02, 2026-04-31 becomes 2026-05-01 — so a
- * malformed review date would pass the staleness gate against a date that
- * never existed. Round-trip through Date.UTC and require every component to
- * survive unchanged, which rejects the rollovers while accepting real dates.
+ * ISO_DATE_RE proves only the shape, and Date.parse silently rolls a
+ * non-calendar date over (2026-02-30 → 2026-03-02), measuring the staleness
+ * gate against a day that never existed.
  */
 function isStrictIsoCalendarDate(s) {
   if (typeof s !== 'string' || !ISO_DATE_RE.test(s)) return false;
@@ -140,8 +100,20 @@ function isStrictIsoCalendarDate(s) {
 const KEBAB_RE = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/;
 const JSON_FILENAME_RE = /^[A-Za-z0-9._-]+\.json$/;
 
+// `helpExitCode` is null unless the run is over before linting starts: 0 after
+// --help, 2 after an unknown argument. parseArgs never terminates the process —
+// it returns the code and the caller must honour it and stop.
+//
+// The invariant this keeps: every exit in this file goes through safeExit(), so
+// no path here can write to stdout and then terminate synchronously. That is the
+// `process-exit-after-stdout-write` shape, and it is a convention held file-wide
+// rather than a repair of an observed truncation: Node writes pipe stdout
+// synchronously on Windows and Linux (asynchronously on macOS), and the help
+// block is a few hundred bytes, so process.exit() did not in fact truncate it
+// here. Holding the invariant means a future help block that grows, or a run on
+// a platform with async pipe writes, cannot reintroduce the class.
 function parseArgs(argv) {
-  const opts = { skill: null, quiet: false, strict: false };
+  const opts = { skill: null, quiet: false, strict: false, helpExitCode: null };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--skill') {
@@ -151,17 +123,17 @@ function parseArgs(argv) {
     } else if (a === '--quiet' || a === '-q') {
       opts.quiet = true;
     } else if (a === '--strict') {
-      // Promote warnings (header-only sections, unresolved draft refs,
-      // playbook air-gap gaps) to release-blocking failures. Used by the
-      // predeploy gate so a warned regression cannot scroll past.
+      // The predeploy gate runs --strict, so a warned regression cannot scroll past.
       opts.strict = true;
     } else if (a === '--help' || a === '-h') {
       printHelp();
-      process.exit(0);
+      opts.helpExitCode = 0;
+      return opts;
     } else {
       console.error(`Unknown argument: ${a}`);
       printHelp();
-      process.exit(2);
+      opts.helpExitCode = 2;
+      return opts;
     }
   }
   return opts;
@@ -183,30 +155,16 @@ function readJson(p) {
 }
 
 /*
- * Minimal YAML frontmatter parser. Supports the subset actually used in this
- * repo:
- *   key: "quoted string"
- *   key: bare-string
- *   key: []                          (empty list)
- *   key:
- *     - item one
- *     - "item two"
- * Anything outside this shape produces a parse error so we don't silently
- * accept malformed frontmatter.
+ * Minimal YAML frontmatter parser: quoted or bare scalars, `[]`, and indented
+ * `- ` item lists. Anything outside that shape throws.
  */
 function parseFrontmatter(text) {
-  // Strip a trailing CR per line: split(/\r?\n/) consumes interior CRLFs, but a
-  // dangling `\r` survives on the final frontmatter line (the close marker
-  // consumed the `\n`, not the `\r`). `.` does not match `\r`, so that line's
-  // value would fail the per-line regex with a misleading "Could not parse
-  // frontmatter line N" on an otherwise valid CRLF skill.md.
+  // A dangling `\r` survives on the final frontmatter line (the close marker took
+  // the `\n`), and `.` does not match `\r`, so the per-line regex would fail.
   const lines = text.split(/\r?\n/).map((l) => l.replace(/\r$/, ''));
   const result = {};
-  // Track every top-level key we've already assigned. YAML's last-wins
-  // semantics would let a tampered skill set name twice
-  // ("name: real-skill\nname: evil-skill") and silently take the second
-  // value — a skill-identity spoofing primitive. Refuse duplicates
-  // outright; an honest skill never has them.
+  // YAML's last-wins semantics would let "name: real\nname: evil" take the
+  // second value — a skill-identity spoof — so a duplicate key is refused.
   const seenKeys = new Set();
   let i = 0;
   while (i < lines.length) {
@@ -261,11 +219,8 @@ function unquote(s) {
     if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
       return s.slice(1, -1);
     }
-    // Quoted scalar followed by an inline comment, e.g.
-    //   "standalone"  # why this skill is standalone
-    // The value is the quoted content; everything after the closing quote is a
-    // YAML comment. Only applied when the trailing segment is whitespace + `#`
-    // so a mid-string `#` inside an unquoted value is never mistaken for one.
+    // A quoted scalar trailed by an inline comment (`"standalone"  # why`). Only
+    // when the tail is whitespace + `#`, so a `#` inside a value is not a comment.
     if (first === '"' || first === "'") {
       const close = s.indexOf(first, 1);
       if (close > 0) {
@@ -294,18 +249,12 @@ function extractFrontmatterBlock(content) {
   return { frontmatter: raw.replace(/^\r?\n/, ''), body: bodyStart, frontmatterRaw: raw };
 }
 
-// Array-item pattern constraints already enforced above by dedicated regexes
-// (ATLAS_ID_RE / ATTACK_ID_RE / JSON_FILENAME_RE) with their own error wording.
-// The schema-driven pass below skips these so a field is never reported twice.
+// Fields with a dedicated regex and error wording above; the schema-driven pass
+// skips them so a field is never reported twice.
 const SCHEMA_PATTERN_HANDLED_ELSEWHERE = new Set(['atlas_refs', 'attack_refs', 'data_deps']);
 
 /* Enforce the enum and array-item pattern constraints declared in
- * lib/schemas/skill-frontmatter.schema.json, so the shipped schema is the
- * source of truth rather than a decorative artifact. Covers the schema's
- * `enum` constraints (e.g. discovery_mode) and the `items.pattern` format
- * checks on ref arrays (cwe_refs / d3fend_refs / dlp_refs / rfc_refs) that the
- * hand-coded checks did not apply. Returns errors in the existing
- * `frontmatter.<field> ...` voice. */
+ * lib/schemas/skill-frontmatter.schema.json. */
 function schemaConstraintErrors(fm, schema) {
   const errors = [];
   const props = (schema && schema.properties) || {};
@@ -313,11 +262,8 @@ function schemaConstraintErrors(fm, schema) {
     if (!(field in fm)) continue;
     const value = fm[field];
 
-    // An enum constraint must reject a wrong-typed value, not skip it. The
-    // earlier `typeof value === 'string'` guard silently passed any non-string
-    // (e.g. `discovery_mode: [standalone]` parsed as an array, or a number),
-    // letting a malformed field bypass validation entirely. Flag the type
-    // mismatch first; only run the membership check on an actual string.
+    // Type first, membership only on a string: guarding on `typeof value ===
+    // 'string'` would let `discovery_mode: [standalone]` through unvalidated.
     if (Array.isArray(spec.enum)) {
       if (typeof value !== 'string') {
         errors.push(
@@ -350,13 +296,10 @@ function schemaConstraintErrors(fm, schema) {
   return errors;
 }
 
-/* Validate frontmatter object against the codified schema rules. */
+/* Returns { errors, warnings } — the review-staleness soft cap warns without
+ * failing, so callers must read both arrays. */
 function validateFrontmatter(fm, skillName) {
   const errors = [];
-  // v0.13.0: validateFrontmatter now ALSO surfaces warnings (e.g. the
-  // last_threat_review 180-day soft cap). Return signature changes from
-  // `string[]` to `{ errors: string[], warnings: string[] }` — callers
-  // updated accordingly.
   const warnings = [];
 
   for (const key of Object.keys(fm)) {
@@ -467,10 +410,6 @@ function validateFrontmatter(fm, skillName) {
         `frontmatter.last_threat_review "${fm.last_threat_review}" is not a valid ISO date (YYYY-MM-DD). A structurally ISO but non-calendar value (e.g. 2026-13-99 or a rollover like 2026-02-30) is rejected so a malformed date cannot slip past the staleness gate.`,
       );
     } else {
-      // v0.13.0: Hard Rule #8 forcing function — refuse skills whose
-      // last_threat_review is older than the staleness threshold.
-      // 180-day soft cap (warn), 365-day hard cap (fail). Operators on
-      // older releases who don't refresh fall off the supported window.
       const days = Math.floor((Date.now() - Date.parse(fm.last_threat_review + 'T00:00:00Z')) / (24 * 60 * 60 * 1000));
       if (days > 365) {
         errors.push(
@@ -484,30 +423,19 @@ function validateFrontmatter(fm, skillName) {
     }
   }
 
-  // Drive enum + ref-pattern enforcement from the published schema so the
-  // shipped artifact and this gate cannot diverge.
   errors.push(...schemaConstraintErrors(fm, FRONTMATTER_SCHEMA));
 
   return { errors, warnings };
 }
 
-/* L1 — Heading-anchored section detection.
- *
- * Returns { missing, headerOnly }:
- *   - missing[]    — sections with no `^## <Section Name>` heading anywhere
- *                    in the body (case-insensitive). Hard failure.
- *   - headerOnly[] — sections whose heading exists but whose body between
- *                    that heading and the next heading is shorter than
- *                    MIN_SECTION_BODY_WORDS words. A warning by default;
- *                    promoted to an error under --strict. */
+/* Returns { missing, headerOnly }: sections with no heading in the body, and
+ * sections whose heading exists but whose text runs shorter than
+ * MIN_SECTION_BODY_WORDS. */
 function findMissingSections(body, requiredSections) {
   const sections = requiredSections || REQUIRED_SECTIONS;
   const lines = body.split(/\r?\n/);
-  // Index heading lines so we know where each section ends. Skip lines inside
-  // fenced code blocks: a heading inside a ```markdown example block is
-  // documentation, not a real section, and must not satisfy a required-section
-  // check (otherwise a skill whose required sections appear only inside a fence
-  // passes the gate vacuously).
+  // Headings inside a fenced block are documentation: counting them lets a skill
+  // whose sections appear only inside a fence pass the gate vacuously.
   const headings = [];
   let inFence = false;
   for (let i = 0; i < lines.length; i++) {
@@ -518,17 +446,13 @@ function findMissingSections(body, requiredSections) {
       headings.push({ line: i, depth: m[1].length, title: m[2].trim() });
     }
   }
-  // Heading match is case-insensitive and tolerates trailing context
-  // qualifiers (e.g. "## Threat Context (mid-2026)" or
-  // "## TTP Mapping (MITRE ATT&CK Enterprise, mid-2026)"). The required
-  // section name must appear as a leading token followed by end-of-string
-  // or a non-alphanumeric character (paren, dash, colon).
+  // Case-insensitive, and tolerant of a trailing qualifier ("## Threat Context
+  // (mid-2026)"): the name must lead, then end-of-string or a non-alphanumeric.
   const findHeading = (title) => {
     const t = title.toLowerCase();
     return headings.find((h) => {
-      // Required sections are top-level (H1/H2). A deeper heading — e.g. the H3
-      // "### Compliance Theater Check Result" inside Output Format — must NOT
-      // satisfy the standalone "## Compliance Theater Check" requirement.
+      // Required sections are H1/H2: a nested H3 "### Compliance Theater Check
+      // Result" must not satisfy the standalone "## Compliance Theater Check".
       if (h.depth > 2) return false;
       const lower = h.title.toLowerCase();
       if (lower === t) return true;
@@ -549,7 +473,6 @@ function findMissingSections(body, requiredSections) {
       missing.push(section);
       continue;
     }
-    // Find the next heading at the same or shallower depth, or EOF.
     const idx = headings.indexOf(h);
     let endLine = lines.length;
     for (let j = idx + 1; j < headings.length; j++) {
@@ -676,11 +599,8 @@ function lintSkill(entry, ctx) {
     }
   }
 
-  // L2 — attack_refs cross-catalog resolution. Surface as warnings by
-  // default (preserving patch-class compatibility); promoted to hard
-  // failures under --strict (the predeploy gate). If
-  // data/attack-techniques.json is missing entirely the ctx.attackKeys set
-  // is null — skip the check (the gate degrades gracefully).
+  // Unresolved attack_refs warn, and fail under --strict. ctx.attackKeys is
+  // null when data/attack-techniques.json is absent, and the check is skipped.
   if (Array.isArray(fm.attack_refs) && ctx.attackKeys) {
     for (const ref of fm.attack_refs) {
       if (!ctx.attackKeys.has(ref)) {
@@ -691,22 +611,9 @@ function lintSkill(entry, ctx) {
     }
   }
 
-  // Hard Rule #1 enforcement at the skill-body layer. Every CVE-* /
-  // MAL-* mentioned in skill prose MUST resolve to an entry in
-  // data/cve-catalog.json. Hard Rule #1 ("no stale threat intel") is
-  // enforced for catalog ENTRIES by lib/validate-cve-catalog.js — and
-  // this body-scan extends it to the skill prose layer.
-  //
-  // v0.13.2 introduced this as a warning while the 2 pre-existing
-  // violations (ransomware-response cited CVE-2024-21762,
-  // cloud-iam-incident cited CVE-2026-21370) were triaged. v0.13.3
-  // flips to hard error now that both have been resolved (the
-  // Fortinet CVE landed in the catalog; the placeholder CVE was
-  // removed from the cloud-iam-incident body).
-  //
-  // Draft references stay as warnings — operators promote drafts
-  // on their own cadence and the catalog frequently carries
-  // auto-imported drafts that skills can legitimately cite.
+  // Hard Rule #1 at the prose layer: every CVE-* / MAL-* cited in a skill body
+  // must resolve in data/cve-catalog.json. A `_draft: true` entry warns rather
+  // than failing — operators promote drafts on their own cadence.
   if (ctx.cveCatalog && body && typeof body === 'string') {
     const cveRefRe = /\b(CVE-\d{4}-\d{4,7}|MAL-\d{4}-[A-Z0-9-]+)\b/g;
     const seen = new Set();
@@ -728,18 +635,11 @@ function lintSkill(entry, ctx) {
     }
   }
 
-  // L3 — Defensive Countermeasure Mapping is required for skills reviewed
-  // on or after COUNTERMEASURE_CUTOFF. Pre-cutoff skills are exempt. The
-  // section's absence on a post-cutoff skill is a warning by default so
-  // existing skills can add the section gradually; promoted to a hard
-  // failure under --strict.
   const { missing, headerOnly } = findMissingSections(body, REQUIRED_SECTIONS);
   for (const s of missing) {
     skillErrors.push(`body: missing required section "${s}"`);
   }
   for (const ho of headerOnly) {
-    // L1 — Header-only sections are warnings by default; promoted to a
-    // failure under --strict.
     skillWarnings.push(
       `body: section "${ho.section}" has only ${ho.wordCount} words of body text (need >= ${MIN_SECTION_BODY_WORDS}); an error under --strict`,
     );
@@ -776,7 +676,6 @@ function loadContext() {
   const frameworks = readJson(FRAMEWORK_GAPS_PATH);
   const atlasKeys = new Set(Object.keys(atlas).filter((k) => !k.startsWith('_')));
   const frameworkKeys = new Set(Object.keys(frameworks).filter((k) => !k.startsWith('_')));
-  // Optional catalogs — load if present, otherwise treat as empty.
   function loadKeys(p) {
     const s = new Set();
     if (fs.existsSync(p)) {
@@ -785,20 +684,15 @@ function loadContext() {
     }
     return s;
   }
-  // L2 — attack-techniques.json may not exist in older trees. When absent,
-  // ctx.attackKeys is null and the L2 check is skipped.
+  // Null when data/attack-techniques.json is absent; the attack_refs check skips.
   let attackKeys = null;
   if (fs.existsSync(ATTACK_REFS_PATH)) {
     attackKeys = new Set();
     const j = readJson(ATTACK_REFS_PATH);
     for (const k of Object.keys(j)) if (!k.startsWith('_')) attackKeys.add(k);
   }
-  // v0.13.2: load the CVE catalog into context so the Hard Rule #1
-  // body-scan can resolve CVE-* / MAL-* references in skill prose
-  // against the source-of-truth catalog. Loaded as a full object (not
-  // just keys) so the body-scan can also surface `_draft: true` matches
-  // as warnings rather than errors — operators promote drafts on their
-  // own cadence.
+  // Loaded whole rather than as a key set, so the body scan can tell a missing
+  // CVE from a `_draft: true` one.
   const cveCatalog = fs.existsSync(CVE_CATALOG_PATH) ? readJson(CVE_CATALOG_PATH) : {};
 
   return {
@@ -814,25 +708,13 @@ function loadContext() {
 }
 
 /*
- * S6 — orphan skill.md detector.
- *
- * Walk every subdirectory of skills/ and assert each skill.md file is
- * referenced by exactly one manifest entry. Catches the v0.12.8
- * stash-restore class: a directory left behind on disk that nobody
- * signs because nobody listed it in the manifest, then the next
- * `npm pack` ships an unsigned skill (or worse, conflicts with a
- * future manifest entry of the same name).
- *
- * @param {Array<{path: string}>} manifestSkills
- * @returns {string[]} list of orphan filesystem paths (relative)
+ * Every skill.md under skills/ must be referenced by a manifest entry: a
+ * directory nobody listed is signed by nobody. Returns repo-relative paths.
  */
 function findOrphanSkillFiles(manifestSkills) {
   if (!fs.existsSync(SKILLS_DIR)) return [];
-  // F19 — manifest paths are stored as forward-slash strings by contract
-  // (lib/verify.js validateSkillPath() rejects backslashes). The previous
-  // path.sep split was a no-op on Linux and incorrect on Windows when
-  // mixed separators arrived through other ingest paths; the cleaner
-  // contract is to normalise the comparison key directly.
+  // Manifest paths are forward-slash by contract (lib/verify.js validateSkillPath
+  // rejects backslashes), so normalise rather than splitting on path.sep.
   const referenced = new Set(
     manifestSkills.map((s) => String(s.path).replace(/\\/g, '/')),
   );
@@ -848,17 +730,9 @@ function findOrphanSkillFiles(manifestSkills) {
   return orphans;
 }
 
-// Manifest cover arrays that must resolve to a real catalog entry, paired
-// with the loadContext() key-set they resolve against. The manifest is an
-// enriched superset of frontmatter (it may carry curated refs absent from
-// any skill body), and those manifest-only refs are what build-indexes'
-// reverse-ref surface and refresh-reverse-refs read — yet the per-skill
-// frontmatter ref-resolution above never sees them. Without this pass a
-// typo'd or stale manifest-only ref (e.g. a hand-edit, or one re-signed
-// into manifest_signature) becomes an orphaned control reference in the
-// signed manifest + every derived surface, the exact "no orphaned controls"
-// failure (AGENTS.md Hard Rule #4) the frontmatter resolution prevents —
-// applied to the manifest-only delta the frontmatter pass is blind to.
+// Manifest cover arrays that must resolve to a real catalog entry, paired with
+// the loadContext() key set. These manifest-only refs feed build-indexes'
+// reverse-ref surface and refresh-reverse-refs; the frontmatter pass never sees them.
 const MANIFEST_COVER_RESOLUTION = [
   { field: 'atlas_refs', ctxKey: 'atlasKeys', catalog: 'data/atlas-ttps.json' },
   { field: 'attack_refs', ctxKey: 'attackKeys', catalog: 'data/attack-techniques.json' },
@@ -870,18 +744,9 @@ const MANIFEST_COVER_RESOLUTION = [
 ];
 
 /*
- * Manifest cover-array ref resolution. For every manifest skill entry,
- * assert each ref in its cross-reference cover arrays resolves to a
- * top-level non-underscore key in the matching catalog. This extends the
- * per-skill frontmatter ref-resolution (which reads only skill bodies) to
- * the MANIFEST cover arrays — the signed, index-feeding source of truth
- * that build-indexes' reverse-ref surface and refresh-reverse-refs read.
- *
- * A ctxKey set that is null (the optional attack-techniques.json catalog is
- * absent in older trees) skips that field, mirroring loadContext()'s
- * graceful-degradation contract for ctx.attackKeys.
- *
- * @returns {string[]} `<skill>.<field>: <ref> not present in <catalog>` lines
+ * Assert every ref in each manifest entry's cover arrays resolves in the
+ * matching catalog. A null ctx key set — an absent optional catalog — skips
+ * that field.
  */
 function findUnresolvedManifestCoverRefs(manifestSkills, ctx) {
   const errors = [];
@@ -901,11 +766,8 @@ function findUnresolvedManifestCoverRefs(manifestSkills, ctx) {
   return errors;
 }
 
-// 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.
+// Substrings that mark an artifact `source` as a network call. Deliberately
+// broad: a hit only warns, and an air_gap_alternative silences it.
 const PLAYBOOK_NET_PATTERNS = [
   'https://', 'http://', 'gh api', 'gh release', 'curl ', 'wget ', 'fetch ',
 ];
@@ -913,16 +775,10 @@ const PLAYBOOK_NET_PATTERNS = [
 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.
+ * Warn on any data/playbooks/*.json look artifact whose `source` makes a network
+ * call without a sibling `air_gap_alternative`. The schema enforces that only for
+ * `_meta.air_gap_mode: true`, but any playbook can run under `--air-gap`. Returns
+ * `{ playbook, artifact_id, source }` records.
  */
 function lintPlaybookAirGap() {
   const warnings = [];
@@ -956,6 +812,10 @@ function lintPlaybookAirGap() {
 
 function main() {
   const opts = parseArgs(process.argv);
+  if (opts.helpExitCode !== null) {
+    safeExit(opts.helpExitCode);
+    return;
+  }
   const manifest = readJson(MANIFEST_PATH);
 
   let skills = manifest.skills;
@@ -963,7 +823,8 @@ function main() {
     skills = skills.filter((s) => s.name === opts.skill);
     if (skills.length === 0) {
       console.error(`No skill named "${opts.skill}" in manifest.json`);
-      process.exit(2);
+      safeExit(2);
+      return;
     }
   }
 
@@ -995,9 +856,7 @@ function main() {
     }
   }
 
-  // S6 — orphan check runs only on a full lint pass (no --skill filter).
-  // A targeted single-skill lint is for diagnosing one entry; running
-  // the orphan walk there would surface unrelated findings.
+  // These passes run only on a full lint; a --skill run would show unrelated noise.
   let orphans = [];
   let manifestRefErrors = [];
   let airGapWarnings = [];
@@ -1008,19 +867,14 @@ function main() {
       console.log(`        - skill.md exists on disk but not in manifest: ${o}`);
       console.log(`          fix: re-run sign-all (\`node $(exceptd path)/lib/sign.js sign-all\` from a contributor checkout) after adding it to manifest.json, OR delete the orphan directory`);
     }
-    // Manifest cover-array ref resolution (Hard Rule #4 — no orphaned
-    // controls). The per-skill pass above resolves frontmatter refs; this
-    // resolves the manifest cover arrays the reverse-ref surface reads, so a
-    // typo'd/stale manifest-only ref can't ship as an orphaned control. A
-    // hard failure (not a --strict warning): an unresolved control ref is
-    // unconditionally wrong, matching the frontmatter ref-resolution voice.
+    // Hard Rule #4, no orphaned controls: an unresolved control ref is
+    // unconditionally wrong, so this fails rather than warning under --strict.
     manifestRefErrors = findUnresolvedManifestCoverRefs(manifest.skills, ctx);
     for (const e of manifestRefErrors) {
       console.log(`FAIL  <manifest-cover-ref>`);
       console.log(`        - ${e}`);
       console.log(`          fix: correct the typo'd/stale ref in manifest.json (or add the entry to the catalog), then re-run sign-all + refresh-reverse-refs + build-indexes`);
     }
-    // P4 — air-gap completeness lint over data/playbooks/*.json.
     airGapWarnings = lintPlaybookAirGap();
     for (const w of airGapWarnings) {
       console.log(`WARN  playbook:${w.playbook}`);
@@ -1043,8 +897,6 @@ function main() {
   console.log(
     `\n${passed}/${total} skills passed${warnSummary}${failed ? `, ${failed} failed` : ''}${orphanSummary}${manifestRefSummary}${airGapSummary}.`,
   );
-  // --strict treats any warning (per-skill or playbook air-gap) as a
-  // release-blocking failure so a warned regression cannot ship silently.
   const strictFail = opts.strict && (warned > 0 || (airGapWarnings && airGapWarnings.length > 0));
   if (strictFail) {
     console.log(`[lint-skills] --strict: ${warned + (airGapWarnings ? airGapWarnings.length : 0)} warning(s) treated as failures.`);
@@ -1053,9 +905,9 @@ function main() {
   return;
 }
 
-// Export the minimal frontmatter parser for downstream consumers
-// (e.g., orchestrator `watchlist` command) so they don't reinvent it.
+// The frontmatter parser is exported so `watchlist` does not grow a second one.
 module.exports = {
+  parseArgs,
   parseFrontmatter,
   extractFrontmatterBlock,
   unquote,