canary-test-cli 7.1.0 → 7.2.0

package/agents/skills/lib/parse-args.mjs

@@ -0,0 +1,214 @@
+// Shared skill-CLI argument parser (#479).
+//
+// Skill CLIs are deliberately self-contained -- they import no engine code, so
+// the runner can exec them anywhere node runs. That constraint is why five of
+// them hand-rolled the same `parseArgs` loop, and why the same bug class came
+// back three consecutive rounds: the pattern was copy-paste, so each new skill
+// inherited whichever version its author happened to copy.
+//
+// This module is the one implementation of the four invariants that loop has to
+// honour. It stays dependency-free ESM under `agents/skills/lib/`, which keeps
+// the self-contained property intact -- a skill importing a sibling file in the
+// same shipped tree is still a skill that needs nothing installed.
+//
+//   1. null-prototype flag lookup   -- an inherited key must never resolve
+//   2. empty-value rejection        -- `--flag=` and `--flag ''` alike
+//   3. arity checking               -- `argument <flag>: expected one argument`
+//   4. `--flag=value`               -- accepted everywhere, not per-skill
+//
+// `test/skill-cli-conformance.test.ts` discovers every SKILL.md declaring
+// `cli:` and asserts the module exports the `CLI_SPEC` it passed here, so a
+// sixth hand-rolled copy fails CI instead of quietly starting the cycle again.
+
+/** Exit code argparse reserves for usage errors; the whole family follows it. */
+export const EXIT_USAGE = 2;
+
+/** Well-formed integer, sign allowed -- no floats, no exponents, no 0x. */
+const INT_RE = /^[+-]?\d+$/;
+
+/**
+ * argparse prints `prog: error: message` for usage errors. The family's
+ * comments have claimed argparse parity throughout while shipping two formats
+ * under that banner; this is the one that makes the claim true. Runtime
+ * failures (exit 1) keep the plainer `prog: message` -- argparse never owned
+ * those, so there is nothing to be faithful to.
+ */
+export function formatUsageError(prog, message) {
+  return `${prog}: error: ${message}`;
+}
+
+/** Inherited keys must not resolve, so every lookup map is null-prototype. */
+function nullProtoMap(entries) {
+  return Object.assign(Object.create(null), entries);
+}
+
+/**
+ * Build a parser from a declarative spec.
+ *
+ * @param {object} spec
+ * @param {string} spec.prog          program name used in error output
+ * @param {Record<string,string>} [spec.booleans]  '--json' -> 'json'
+ * @param {Record<string,{key:string,type?:'string'|'int'}>} [spec.values]
+ * @param {Record<string,unknown>} [spec.defaults] initial option values
+ * @param {string[]} [spec.required]  value flags that must be supplied
+ * @param {{key:string,defaults?:string[]}} [spec.positionals]
+ *        declaring positionals also enables the `--` end-of-options terminator
+ *        and a lone `-`; a CLI that takes no paths gets neither, since there is
+ *        nothing for them to protect.
+ * @returns {(argv: string[]) => {opts: Record<string,unknown>, positionals: string[], help: boolean, error: string|null}}
+ */
+export function createParser(spec) {
+  const {
+    prog,
+    booleans = {},
+    values = {},
+    defaults = {},
+    required = [],
+    positionals = null,
+  } = spec ?? {};
+
+  if (!prog) throw new Error('createParser: spec.prog is required');
+
+  const BOOLEANS = nullProtoMap(booleans);
+  const VALUES = nullProtoMap(values);
+
+  // Fail loudly at construction on a spec that cannot be satisfied -- a rename
+  // that leaves a stale default or a required flag behind is otherwise silent.
+  const declaredKeys = new Set([
+    ...Object.values(booleans),
+    ...Object.values(values).map((v) => v.key),
+  ]);
+  for (const key of Object.keys(defaults)) {
+    if (!declaredKeys.has(key)) {
+      throw new Error(`createParser: defaults names unknown key '${key}'`);
+    }
+  }
+  for (const flag of required) {
+    if (VALUES[flag] === undefined) {
+      throw new Error(`createParser: required names undeclared flag '${flag}'`);
+    }
+  }
+
+  return function parse(argv = []) {
+    const opts = Object.create(null);
+    for (const key of Object.values(booleans)) opts[key] = false;
+    for (const { key } of Object.values(values)) {
+      opts[key] = key in defaults ? defaults[key] : null;
+    }
+    Object.assign(opts, defaults);
+
+    const found = [];
+    const result = { opts, positionals: found, help: false, error: null };
+    const fail = (message) => {
+      result.error = message;
+      return result;
+    };
+
+    let endOfOptions = false;
+
+    for (let i = 0; i < argv.length; i += 1) {
+      const arg = argv[i];
+
+      if (endOfOptions) {
+        found.push(arg);
+        continue;
+      }
+
+      // Help short-circuits everything, including the required-flag check
+      // below -- otherwise `--help` reports the arguments it is being asked to
+      // explain as missing.
+      if (arg === '-h' || arg === '--help') {
+        result.help = true;
+        return result;
+      }
+
+      if (arg === '--') {
+        if (!positionals) return fail('unrecognized arguments: --');
+        endOfOptions = true;
+        continue;
+      }
+
+      // Split `--flag=value` once, up front, so both spellings share one path.
+      const eq = arg.startsWith('--') ? arg.indexOf('=') : -1;
+      const flag = eq === -1 ? arg : arg.slice(0, eq);
+      const inline = eq === -1 ? null : arg.slice(eq + 1);
+
+      if (BOOLEANS[flag] !== undefined && inline === null) {
+        opts[BOOLEANS[flag]] = true;
+        continue;
+      }
+
+      const def = VALUES[flag];
+      if (def !== undefined) {
+        let raw;
+        if (inline !== null) {
+          raw = inline;
+        } else {
+          const next = argv[i + 1];
+          // A leading '-' normally means "the next flag, not my value" -- but a
+          // well-formed integer is a legitimate value for an int flag, so
+          // `--seed -5` and `--seed=-5` stay the same command.
+          const looksLikeFlag =
+            next !== undefined &&
+            next.startsWith('-') &&
+            !(def.type === 'int' && INT_RE.test(next));
+          if (next === undefined || looksLikeFlag) {
+            return fail(`argument ${flag}: expected one argument`);
+          }
+          raw = next;
+          i += 1;
+        }
+        // Empty is the missing-value case wearing a disguise. `--repo=` is
+        // typed by nobody, but `--repo "$UNSET_VAR"` expands to `--repo ''` in
+        // any shell, and an accepted empty path silently retargets writes at
+        // the process CWD.
+        if (raw === '') return fail(`argument ${flag}: expected one argument`);
+        if (def.type === 'int') {
+          // Validate the VALUE, not just its presence: a flag whose purpose is
+          // determinism must not decay to a default when its value is junk.
+          if (!INT_RE.test(raw)) {
+            return fail(`argument ${flag}: invalid int value: '${raw}'`);
+          }
+          // Syntactically an integer is not enough: Number() silently rounds
+          // past 2^53-1, so `--seed 9007199254740993` would RUN with ...992 --
+          // the value used differing from the value asked for, which is the
+          // exact class of lie a determinism flag must not tell.
+          const parsed = Number(raw);
+          if (!Number.isSafeInteger(parsed)) {
+            return fail(
+              `argument ${flag}: integer out of safe range: '${raw}'`,
+            );
+          }
+          opts[def.key] = parsed;
+        } else {
+          opts[def.key] = raw;
+        }
+        continue;
+      }
+
+      // A lone `-` is a positional, as argparse treats it.
+      if (positionals && (arg === '-' || !arg.startsWith('-'))) {
+        found.push(arg);
+        continue;
+      }
+
+      return fail(`unrecognized arguments: ${arg}`);
+    }
+
+    const missing = required.filter((flag) => {
+      const value = opts[VALUES[flag].key];
+      return value === null || value === undefined;
+    });
+    if (missing.length) {
+      return fail(
+        `the following arguments are required: ${missing.join(', ')}`,
+      );
+    }
+
+    if (positionals && !found.length && positionals.defaults) {
+      found.push(...positionals.defaults);
+    }
+
+    return result;
+  };
+}

package/dist/engine/cli-commands.js

@@ -10,7 +10,7 @@
  * strips on a non-TTY sink so plain text is byte-exact), and output glyphs as
  * `\u{...}` escapes emitted verbatim.
  */
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, } from 'node:fs';
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, extname, join, resolve } from 'node:path';
 import pc from 'picocolors';
 import { CliExitError, jsonIndent2 } from './cli-common.js';
@@ -22,7 +22,8 @@ import { ckInitCmd } from './company-knowledge-cli.js';
 import { extractFrameworkHint } from './core/classifier.js';
 import { VALID_CATEGORIES, buildFeedback } from './core/feedback.js';
 import { OverlayNotFound, listOverlays, resolveOverlay, } from './core/overlays.js';
-import { JS_TEST_EXTENSIONS, frameworkForPath } from './core/static-linter.js';
+import { frameworkForPath } from './core/static-linter.js';
+import { SCANNABLE_DESC, collectTestFiles, isDir } from './core/test-files.js';
 import { RunSummary } from './core/ticket-updater.js';
 import { renderBanner } from './ui/banner.js';
 import { ARROW, CHECK, CHECK_MARK, CROSS, EM_DASH, HAMMER, NEXT, REDX, ROCKET, WARN, WRENCH, } from './main-deps.js';
@@ -42,67 +43,6 @@ function isFile(p) {
         return false;
     }
 }
-function isDir(p) {
-    try {
-        return statSync(p).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Directories never worth walking. A dependency's own test suite is not the
- * consumer's to fix: before #566, `node_modules` accounted for 254 of 256
- * findings in one downstream run, and the only `critical` sat inside vendored
- * code. `pattern-matcher.ts` has carried this set since the Python port; this
- * walk was the copy that never got it.
- */
-const IGNORED_DIRS = new Set([
-    'node_modules',
-    '.git',
-    '__pycache__',
-    '.venv',
-    'venv',
-    'dist',
-    'build',
-    '.next',
-    '.nuxt',
-]);
-function walkFiles(dir) {
-    const out = [];
-    let entries;
-    try {
-        entries = readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return out;
-    }
-    for (const e of entries) {
-        const full = join(dir, e.name);
-        if (e.isDirectory()) {
-            if (!IGNORED_DIRS.has(e.name))
-                out.push(...walkFiles(full));
-        }
-        else if (e.isFile())
-            out.push(full);
-    }
-    return out;
-}
-/**
- * `test_*.py` plus `*.test.*` / `*.spec.*` over every extension the scanners
- * can actually read -- `.mjs` and `.cjs` included, which is the half of #566
- * that made a directory of ESM tests collect zero files.
- */
-const JS_TEST_FILE_RE = new RegExp(`\\.(test|spec)\\.(${JS_TEST_EXTENSIONS.map((e) => e.slice(1)).join('|')})$`);
-/** Recursive test-file glob matching Python's `rglob` union, sorted by path. */
-function collectTestFiles(dir) {
-    return walkFiles(dir)
-        .filter((p) => {
-        const b = basename(p);
-        return ((b.startsWith('test_') && b.endsWith('.py')) || JS_TEST_FILE_RE.test(b));
-    })
-        .sort();
-}
 export function recommendFrameworkCmd(promptText, opts, deps) {
     const classifier = deps.makeClassifier();
     const recommender = deps.makeRecommender();
@@ -453,8 +393,6 @@ function findingPayload(f) {
         suggestion: f.suggestion,
     };
 }
-/** Human-readable list of what the collectors look for, for remedy text. */
-const SCANNABLE_DESC = `test_*.py, *.test|spec.{${JS_TEST_EXTENSIONS.map((e) => e.slice(1)).join(',')}}`;
 /** Emit the abstention notice in the caller's output mode, then exit 3. */
 function abstain(remedy, deps, json, skipped = []) {
     const result = { checked: 0, findings: [] };

package/dist/engine/core/quality-scorer.js

@@ -19,10 +19,23 @@ const ASSERTIONS = {
     // nothing. (`\bassert\b` alone does NOT match `assert_valid`: `_` is a word
     // char, so the `\b` after `assert` fails there.)
     pytest: /\bassert\b|\bpytest\.raises\b|\bself\.assert\w+\b|\bassert\w*\s*\(/g,
-    playwright: /\bexpect\s*\(|\btoBeVisible\b|\btoHaveText\b|\btoHaveTitle\b|\btoHaveURL\b|\btoBeEnabled\b|\btoBeDisabled\b|\btoBeChecked\b|\btoHaveValue\b|\btoHaveCount\b/g,
+    // `\bexpect\w*\s*\(` is the JS/TS half of that same rationale (#738). The
+    // naming convention for a custom assertion helper is `expect*` here, not
+    // `assert*`, and it is the pattern Playwright's own docs recommend: a suite
+    // that routes its checks through `expectRouteTestId(page, id)` so the
+    // assertion semantics live in one documented place had EVERY added test
+    // flagged `added test asserts nothing`. `\w*` is zero-width-matchable, so
+    // plain `expect(` still matches and the change is purely additive.
+    //
+    // The precision cost is the mirror image of the accepted pytest one: a
+    // non-asserting function whose name happens to start with `expect` now
+    // counts. That is the right side to err on for an advisory finding that
+    // never gates — a false "asserts nothing" on a correct test is what teaches
+    // a reader to ignore the finding.
+    playwright: /\bexpect\w*\s*\(|\btoBeVisible\b|\btoHaveText\b|\btoHaveTitle\b|\btoHaveURL\b|\btoBeEnabled\b|\btoBeDisabled\b|\btoBeChecked\b|\btoHaveValue\b|\btoHaveCount\b/g,
     // Plus non-`expect` assertion styles common in JS/TS: node:assert / vitest
     // `assert(...)` / `assert.equal(...)`, and chai BDD `x.should.equal`.
-    vitest: /\bexpect\s*\(|\btoBe\s*\(|\btoEqual\s*\(|\btoThrow\b|\btoContain\s*\(|\btoBeNull\b|\btoBeUndefined\b|\btoMatchObject\b|\bassert\s*\(|\bassert\.\w+|\.should\b/g,
+    vitest: /\bexpect\w*\s*\(|\btoBe\s*\(|\btoEqual\s*\(|\btoThrow\b|\btoContain\s*\(|\btoBeNull\b|\btoBeUndefined\b|\btoMatchObject\b|\bassert\s*\(|\bassert\.\w+|\.should\b/g,
     k6: /\bcheck\s*\(|'[^']+'\s*:\s*\([^)]*\)\s*=>/g,
 };
 const NEGATIVE_KW = /\b(error|invalid|empty|null|undefined|throws|raises|exception|fail|missing|negative|reject|4\d{2}|5\d{2}|boundary|edge)\b/i;

package/dist/engine/core/skill-dispatch.js

@@ -0,0 +1,115 @@
+/**
+ * Tier 2 of `canary skills run`: the dispatcher (#756).
+ *
+ * Canary shipped tier 1 (a skill declaring `cli:`/`entry:` is spawned) and
+ * tier 3 (a prose skill is unreachable), and nothing between. 14 of canary's 21
+ * skills carry no `cli:`, so no orchestrator, CI step, or sibling skill could
+ * invoke them at all -- a have/have-not split that costs far more here than the
+ * same split costs harness, where the dispatcher runs the CLI-less majority.
+ *
+ * ## What "running a prose skill" means here, honestly
+ *
+ * Canary is a CLI. It has no agent runtime, and it is not going to grow one to
+ * close this gap. So the dispatcher does the one thing a CLI can do faithfully:
+ * it RESOLVES the skill and hands back its executable contract -- identity,
+ * declared runtime requirements, and the workflow text an agent is to apply --
+ * with the tier and the determinism stated on the payload. The caller gets a
+ * resolved, machine-readable handle to a real skill instead of exit 2.
+ *
+ * What it deliberately does NOT do is apply the workflow and present the result
+ * as canary's. That would be canary claiming an answer it did not compute.
+ *
+ * ## Determinism labelling (issue design question 2)
+ *
+ * Every dispatch is stamped `determinism: 'agent-applied'`, against
+ * `'deterministic'` for a `cli:` skill. A consumer merging findings across
+ * skills must be able to tell a scanner's output from an agent's reading of a
+ * ruleset; without the label the two look interchangeable, which is exactly the
+ * confusion #755 documents about cassandra.
+ *
+ * ## Why no `--allow-executable-skills` equivalent (design question 3)
+ *
+ * That flag exists because a freshly cloned overlay can carry a `cli:` script,
+ * and invoking it runs someone else's code on the next CI run. Dispatch runs
+ * nothing: it reads a markdown file the registry already read at discovery and
+ * prints it. There is no new execution to gate, so gating it would be
+ * ceremony -- and ceremony that would keep the 14 skills unreachable in exactly
+ * the non-interactive contexts the issue is about. The trust boundary moves to
+ * whatever the caller does with the returned text, which is the caller's gate
+ * to own, and the payload labels itself so the caller can see what it holds.
+ *
+ * ## Failure mode (design question 4)
+ *
+ * A skill that could not be dispatched raises {@link SkillDispatchError}. An
+ * unreadable or bodyless SKILL.md is a failure, never an empty success -- a
+ * dispatcher that returned "nothing to do" for a skill it could not read would
+ * be indistinguishable from one that ran and found nothing.
+ */
+import { readFileSync } from 'node:fs';
+import { errnoCode } from './gate-result.js';
+// Written as an escape so this source stays ASCII, matching gate-result.ts.
+const EMDASH = '\u{2014}';
+/** A dispatch that could not be completed. Never degrades to an empty result. */
+export class SkillDispatchError extends Error {
+    skill;
+    constructor(skill, message) {
+        super(message);
+        this.name = 'SkillDispatchError';
+        this.skill = skill;
+    }
+}
+/**
+ * Strip a leading `---` frontmatter block, leaving the workflow prose.
+ *
+ * Mirrors the delimiter handling in `SkillRegistry.parseFrontmatter`: an
+ * unterminated block means the whole file was frontmatter, and there is no
+ * body to hand back.
+ */
+export function skillBody(text) {
+    if (!text.startsWith('---'))
+        return text.trim();
+    const rest = text.split('\n').slice(1);
+    const end = rest.findIndex((l) => l.trim() === '---');
+    return end === -1
+        ? ''
+        : rest
+            .slice(end + 1)
+            .join('\n')
+            .trim();
+}
+/**
+ * Resolve a prose skill into its dispatch payload.
+ *
+ * @throws {SkillDispatchError} when SKILL.md cannot be read, or holds no body.
+ */
+export function dispatchProseSkill(skill, args) {
+    let text;
+    try {
+        text = readFileSync(skill.path, 'utf-8');
+    }
+    catch (exc) {
+        const code = errnoCode(exc);
+        if (code === null)
+            throw exc;
+        throw new SkillDispatchError(skill.name, `cannot read ${skill.path} (${code}) ${EMDASH} the skill was ` +
+            'discovered but its workflow could not be loaded.');
+    }
+    const instructions = skillBody(text);
+    if (!instructions) {
+        throw new SkillDispatchError(skill.name, `${skill.path} carries frontmatter but no workflow body ${EMDASH} ` +
+            'there is nothing to dispatch. Reporting this as an empty run would ' +
+            'be indistinguishable from a skill that ran and found nothing.');
+    }
+    return {
+        skill: skill.name,
+        path: skill.path,
+        tier: 'dispatcher',
+        determinism: 'agent-applied',
+        requires_agent_runtime: true,
+        requires: skill.requires,
+        description: skill.description,
+        instructions,
+        args,
+    };
+}
+//# sourceMappingURL=skill-dispatch.js.map

package/dist/engine/core/skill-examples.js

@@ -59,6 +59,48 @@ const PLACEHOLDER = /[<>${}|`*\\]/;
 const HELP_FLAGS = new Set(['--help', '-h', '--version', '-V']);
 /** Non-mutating subcommands worth executing even without a help flag. */
 const READ_ONLY_COMMANDS = new Set(['canary skills list']);
+/**
+ * The author's declaration that a block is illustrative (#707).
+ *
+ * Placed on its own line immediately above the fence it governs:
+ *
+ *     <!-- canary:illustrative -->
+ *     ```bash
+ *     canary katana scan --since HEAD~1
+ *     ```
+ *
+ * Two facts land in the same "unverifiable" bucket and they are not the same
+ * fact: "nobody could run this" and "this was never meant to be run". The
+ * first is a gap in the corpus; the second is a deliberate authoring choice.
+ * Collapsing them is what let 88% of the corpus read as coverage debt when
+ * some of it was prose doing its job — and, worse, hid the real gaps inside
+ * the pile.
+ *
+ * Marking is NOT an escape hatch from the executable-example rule. It changes
+ * the reason on one block; a code-bearing skill still has to carry at least
+ * one example that actually runs (`no-executable-example`), so a skill cannot
+ * mark its way to green.
+ */
+const ILLUSTRATIVE_MARKER = /^\s*<!--\s*canary:illustrative\s*-->\s*$/;
+/**
+ * The reason carried by a declared-illustrative example.
+ *
+ * Exported because the summary line splits the unverifiable bucket on it
+ * (see {@link countDeclaredIllustrative}). A string literal compared in two
+ * files is a drift waiting to happen, and the drift would be silent: the
+ * split would quietly read 0 declared and the distinction this issue exists
+ * to draw would be gone with nothing red.
+ */
+export const ILLUSTRATIVE_REASON = 'declared illustrative by the author, so it is not run';
+/**
+ * How many of a gate's skipped examples were skipped BY DECLARATION.
+ *
+ * The rest are the honest gap: examples nobody could run and nobody said
+ * were prose.
+ */
+export function countDeclaredIllustrative(skipped) {
+    return skipped.filter((s) => s.reason === ILLUSTRATIVE_REASON).length;
+}
 /** How an example turned out. */
 export var ExampleVerdict;
 (function (ExampleVerdict) {
@@ -75,6 +117,14 @@ export var ExampleFindingKind;
     ExampleFindingKind["ExampleFailed"] = "example-failed";
     /** A code-bearing skill's doc offers no command to execute at all. */
     ExampleFindingKind["NoDocumentedExample"] = "no-documented-example";
+    /**
+     * A code-bearing skill documents commands, but not one of them can be run
+     * (#707). Distinct from {@link NoDocumentedExample}, and it was the larger
+     * hole: 5 of 9 `cli:` skills sat here while the corpus looked documented.
+     * A skill in this state can break in every documented way and CI stays
+     * green, which is the false-green shape the whole check exists to close.
+     */
+    ExampleFindingKind["NoExecutableExample"] = "no-executable-example";
 })(ExampleFindingKind || (ExampleFindingKind = {}));
 /**
  * Whether `line` closes the currently open fence.
@@ -95,6 +145,11 @@ function fencedShellLines(text) {
     const lines = text.split('\n');
     let fence = null;
     let shell = false;
+    let illustrative = false;
+    // The marker governs the NEXT fence, so it survives the blank line authors
+    // naturally leave between a comment and a block, and is spent by the fence
+    // it opens — a marker cannot leak onto a later, unrelated example.
+    let pendingMarker = false;
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         const delimiter = /^\s*(`{3,}|~{3,})\s*([A-Za-z0-9_+-]*)/.exec(line);
@@ -104,16 +159,24 @@ function fencedShellLines(text) {
             if (delimiter) {
                 fence = delimiter[1];
                 shell = SHELL_FENCES.has((delimiter[2] ?? '').toLowerCase());
+                illustrative = pendingMarker;
+                pendingMarker = false;
+                continue;
             }
+            if (ILLUSTRATIVE_MARKER.test(line))
+                pendingMarker = true;
+            else if (line.trim() !== '')
+                pendingMarker = false;
             continue;
         }
         if (closesFence(line, delimiter, fence)) {
             fence = null;
             shell = false;
+            illustrative = false;
             continue;
         }
         if (shell)
-            out.push({ line: i + 1, raw: line });
+            out.push({ line: i + 1, raw: line, illustrative });
     }
     return out;
 }
@@ -146,7 +209,7 @@ function classify(command) {
  */
 export function extractExamples(text, skill, path) {
     const out = [];
-    for (const { line, raw } of fencedShellLines(text)) {
+    for (const { line, raw, illustrative } of fencedShellLines(text)) {
         // Strip a `$ ` or `> ` shell prompt; a doc that shows a prompt is still
         // documenting the command after it.
         const command = raw
@@ -157,8 +220,31 @@ export function extractExamples(text, skill, path) {
             continue;
         if (command !== 'canary' && !command.startsWith('canary '))
             continue;
+        // A declaration beats an inference. The author saying "this is prose"
+        // is a better fact than the classifier guessing why it could not run,
+        // and it is the fact a reader of the skipped list needs.
+        if (illustrative) {
+            out.push({
+                skill,
+                path,
+                command,
+                line,
+                executable: false,
+                declaredIllustrative: true,
+                reason: ILLUSTRATIVE_REASON,
+            });
+            continue;
+        }
         const { executable, reason } = classify(command);
-        out.push({ skill, path, command, line, executable, reason });
+        out.push({
+            skill,
+            path,
+            command,
+            line,
+            executable,
+            declaredIllustrative: false,
+            reason,
+        });
     }
     return out;
 }
@@ -239,6 +325,20 @@ export function checkExamples(surfaces, run, cwd) {
             }
             continue;
         }
+        // #707: documenting commands is not the same as documenting a RUNNABLE
+        // one. The cheapest fix is the skill's own `--help`, which needs no
+        // fixtures, credentials or network — and marking blocks illustrative
+        // cannot satisfy this, so the declaration stays honest.
+        if (codeBearing(decl) && !examples.some((e) => e.executable)) {
+            tally.findings.push({
+                kind: ExampleFindingKind.NoExecutableExample,
+                skill: decl.name,
+                path: decl.path,
+                detail: `declares a \`cli:\` and documents ${examples.length} command(s), ` +
+                    'but none is executable, so nothing in its doc has ever been run. ' +
+                    'Add one placeholder-free help-shaped example (its own `--help`).',
+            });
+        }
         tallyDeclaration(decl, runExamples(examples, run, cwd), tally);
     }
     return tally;