@event4u/agent-config 14.12.0 → 14.13.0

package/src/scripts/run_skill_evals.ts

@@ -153,6 +153,24 @@ export function _load_tool_trace(run_dir: string): string[] | null {
     return raw.map((e) => (typeof e === 'string' ? e : (e.tool ?? ''))).filter((s) => s !== '');
 }
 
+/**
+ * Load the recorded EVENT trace, or `null` when the run did not record one.
+ *
+ * Sibling of {@link _load_tool_trace}, and deliberately a separate file rather
+ * than a widened tool trace: a tool call is something the agent did, an event
+ * is something the harness observed — a gate running, a hook concern firing, a
+ * refusal. Conflating them would make "the linter ran" indistinguishable from
+ * "the agent invoked the linter", and the interesting failure is precisely the
+ * case where a gate was SKIPPED while the agent narrated that it passed.
+ */
+export function _load_event_trace(run_dir: string): string[] | null {
+    const p = path.join(run_dir, 'event-trace.json');
+    if (!_exists(p)) return null;
+    const raw = JSON.parse(fs.readFileSync(p, 'utf-8')) as Array<string | { event?: string }>;
+    if (!Array.isArray(raw)) return null;
+    return raw.map((e) => (typeof e === 'string' ? e : (e.event ?? ''))).filter((s) => s !== '');
+}
+
 /** Count meaningful steps: tool calls net of retries (a call whose name equals
  * the immediately-preceding call name is a retry, not a new step). */
 export function _count_meaningful_steps(trace: string[]): number {
@@ -217,6 +235,28 @@ export function _grade_assertions(
                     missing, forbidden, pass: missing.length === 0 && forbidden.length === 0,
                 });
             }
+        } else if (kind === 'event-choice') {
+            // The forbidden-event half of the case shape. Same manual-pending
+            // rule as tool-choice: no trace is NEVER a silent pass, because a
+            // missing trace and a clean run are the two readings this assertion
+            // exists to separate.
+            const mustEmit = (a['must_emit'] as string[] | undefined) ?? [];
+            const mustNotEmit = (a['must_not_emit'] as string[] | undefined) ?? [];
+            const trace = _load_event_trace(run_dir);
+            if (trace === null) {
+                results.push({
+                    kind, must_emit: mustEmit, must_not_emit: mustNotEmit, pass: null,
+                    note: 'manual-pending: no event-trace.json in run dir — record a trace or grade manually',
+                });
+            } else {
+                const seen = new Set(trace);
+                const missing = mustEmit.filter((e) => !seen.has(e));
+                const forbidden = mustNotEmit.filter((e) => seen.has(e));
+                results.push({
+                    kind, must_emit: mustEmit, must_not_emit: mustNotEmit,
+                    missing, forbidden, pass: missing.length === 0 && forbidden.length === 0,
+                });
+            }
         } else if (kind === 'trajectory_budget') {
             // Meaningful step = one tool call net of retries (a retry is a call whose
             // tool name repeats the immediately-preceding call). No trace → manual-pending.

package/src/scripts/schemas/delivery-manifest.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "delivery-manifest.schema.json",
+  "title": "Delivery manifest",
+  "description": "Obligations that may travel on a runtime carrier instead of standing context, and what happens to each when that carrier is unavailable. Contract: docs/contracts/resident-process-floors.md § 3. Resolver: src/scripts/_lib/delivery_criticality.ts.",
+  "type": "object",
+  "required": ["schema_version", "entries"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": 1 },
+    "entries": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/entry" }
+    }
+  },
+  "definitions": {
+    "entry": {
+      "type": "object",
+      "required": ["id", "criticality"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Logical obligation id — the rule, gate or floor being delivered."
+        },
+        "criticality": {
+          "enum": ["critical-A", "critical-B", "standard"],
+          "description": "critical-A never migrates off standing context. critical-B may migrate and is delivered EAGERLY when the carrier is unavailable, never dropped. standard may fail open. Required here even though the resolver defaults an omitted value to critical-B: a manifest is authored, and an author who has not decided should be made to, while a RUNTIME value that is merely absent must still fail closed."
+        },
+        "carrier": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The runtime carrier that would deliver this obligation."
+        },
+        "why": {
+          "type": "string",
+          "description": "Why this class and not the next one down. Required by review, not by schema."
+        }
+      }
+    }
+  }
+}

package/src/scripts/schemas/drafting-channels.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/drafting-channels.schema.json",
+  "x-schemaVersion": "1.0.0",
+  "title": "Drafting channel registry (src/config/drafting-channels.yml)",
+  "$comment": "road-to-channel-contract-and-profile-drift Phase 1.2. Validated by tests/scripts/drafting_channels_schema.test.ts against the Draft-07 SUBSET exported by src/scripts/validate_frontmatter.ts (type, required, properties, additionalProperties:false, items, minItems, pattern, minLength, enum) — no $ref, no patternProperties, no if-then, because that validator supports none of them and a schema using them would silently not be checked. SCOPE: an output shape for prose this package writes. Deliberately NOT merged into reach-channels.schema.json: a reach channel is an external retrieval backend with an install string, a health probe and a lifecycle, and a drafting channel has none of those and carries a length and a cadence instead; a merged schema would make every field optional for half its rows. The `id` values are FLAG VALUES — what a user types after `--channel=` — which is why the enum is closed: the short form `linkedin` is the plausible typo, and an open enum would accept it silently.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "channels"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "enum": ["drafting-channels-v1"],
+      "description": "Registry format version. Bumped only on a breaking shape change."
+    },
+    "channels": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The `--channel` enum, one entry per accepted flag value. Order carries no meaning.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "length_default", "cadence"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "enum": ["tweet", "linkedin-post", "blog", "freeform"],
+            "description": "The literal `--channel=` value. Closed enum: adding a drafting channel is a contract change to docs/contracts/write-engine.md and to the three command surfaces, so it may not be done by adding a row here alone."
+          },
+          "length_default": {
+            "type": "integer",
+            "description": "Default word count when `--length` is omitted. Mirrors the Length-default column of write-engine.md § Per-channel defaults."
+          },
+          "cadence": {
+            "type": "string",
+            "minLength": 10,
+            "description": "Paragraph/structure guidance for this channel. Mirrors the Cadence-guidance column of write-engine.md § Per-channel defaults."
+          }
+        }
+      }
+    }
+  }
+}

package/src/scripts/schemas/evals.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/evals.schema.json",
-  "x-schemaVersion": "1.0.0",
+  "x-schemaVersion": "1.1.0",
   "title": "Skill behavioural evals (evals.json)",
   "$comment": "Behavioural-eval spec consumed by run_skill_evals.ts (scaffold/aggregate/report) and counted by skill_eval_coverage.ts. Distinct from triggers.json (activation/routing axis). Roadmap: road-to-skill-eval-coverage Phase 1. Assertion kinds mirror _grade_assertions() in run_skill_evals.ts exactly \u2014 add a kind there before adding it here.",
   "type": "object",
@@ -198,6 +198,29 @@
                       "description": "Ceiling on meaningful steps = tool calls net of retries (a call repeating the immediately-preceding call name is a retry, not a step). Counted from <run_dir>/tool-trace.json; no trace → manual-pending. v2, additive."
                     }
                   }
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["kind"],
+                  "anyOf": [
+                    { "required": ["kind", "must_emit"] },
+                    { "required": ["kind", "must_not_emit"] }
+                  ],
+                  "properties": {
+                    "kind": { "const": "event-choice" },
+                    "must_emit": {
+                      "type": "array",
+                      "items": { "type": "string", "minLength": 1 },
+                      "description": "Harness events the run MUST have emitted, checked against <run_dir>/event-trace.json. v2, additive."
+                    },
+                    "must_not_emit": {
+                      "type": "array",
+                      "items": { "type": "string", "minLength": 1 },
+                      "description": "Harness events the run MUST NOT have emitted — a skipped gate or a refused turn becomes checkable rather than narrated. v2, additive."
+                    }
+                  },
+                  "$comment": "Forbidden-event array alongside the expected-event array. An EVENT is something the harness observed (a gate running, a hook concern firing, a refusal); a TOOL call is something the agent did — conflating them makes \"the linter ran\" indistinguishable from \"the agent invoked the linter\", and the interesting failure is a gate that was SKIPPED while the agent narrated a pass. Hence a separate kind and a separate trace file. `anyOf` requires at least one of the two arrays BY CONSTRUCTION: the sibling tool-choice shape requires neither, so {\"kind\": \"tool-choice\"} is schema-valid and enforces nothing — this kind cannot express that. No trace present → pass:null manual-pending, never a silent pass."
                 }
               ]
             }

package/src/scripts/schemas/rule.schema.json

@@ -158,7 +158,43 @@
         "type": "string",
         "enum": ["developer", "reviewer", "tester", "po", "incident", "planner"]
       },
-      "description": "Subagent role-mode scoping axis (road-to-lean-agent-init Phase 4), parallel to `workspaces`/`packs`. Closed vocabulary — the six RoleMode ids from src/scripts/_lib/subagent_spawn.ts. Absent/empty = untagged, fails safe (ships to every role). Kernel rules (type: always) always ship regardless of this field. Enforced via this schema's `enum` (not a src/config/discovery/*.yml + lint_artefact_frontmatter.ts cross-check like workspaces/packs) because lint_artefact_frontmatter.ts still scans the retired legacy rules tree (0 artefacts post-ADR-051 src/ migration) and is a no-op for src/rules/*.md today; validate_frontmatter.ts (the active src/rules linter) enforces this enum instead."
+      "description": "Subagent role-mode scoping axis (road-to-lean-agent-init Phase 4), parallel to `workspaces`/`packs`. Closed vocabulary — the six RoleMode ids from src/scripts/_lib/subagent_spawn.ts. Absent/empty = untagged, fails safe (ships to every role). Kernel rules (type: always) always ship regardless of this field. Enforced via this schema's `enum` (not a src/config/discovery/*.yml + lint_artefact_frontmatter.ts cross-check like workspaces/packs) because lint_artefact_frontmatter.ts still scans the retired legacy rules tree (0 artifacts post-ADR-051 src/ migration) and is a no-op for src/rules/*.md today; validate_frontmatter.ts (the active src/rules linter) enforces this enum instead."
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source_type"],
+      "allOf": [
+        {
+          "$comment": "`normative_level` states how binding the SOURCE is. For `own-analysis` there is no external source, so the field answers a question that does not arise and `informative` is its only coherent value — requiring it there forces a non-answer. `verified_on` is conditional for the same reason and not a second exception: it stamps when an EXTERNAL source pointer was last checked, and where there is no external source the rule\u2019s own git history is its staleness. Both are required for every other source_type, where the questions are real. Surfaced by the delivered-payload ceiling: ten blocks did not fit, and the two fields that did not fit were the two that were not saying anything.",
+          "if": { "properties": { "source_type": { "not": { "const": "own-analysis" } } }, "required": ["source_type"] },
+          "then": { "required": ["normative_level", "verified_on"] }
+        }
+      ],
+      "description": "Where this rule's NORMATIVE CONTENT came from, and what it was when it left. Optional; road-to-retired-claims-stay-retired Phase 3. Distinct from `decision_impact_evidence`, which points at an observation that the model already complies WITHOUT the rule \u2014 the opposite direction. A rule stating a threshold, a number, or a mechanism taken from outside this repository either cites it here or is recorded as own analysis; `src/rules/code-provenance.md` \u00a7 The knowledge layer states that obligation for prose, and this block is where a rule discharges it structurally. Optional on day one by design: 0 of 120 rules carried any provenance field before this, and a required field would fail the build on all of them at once \u2014 the gate-that-can-only-block shape this repository's own records name as the reason a gate gets suppressed.",
+      "properties": {
+        "source_type": {
+          "type": "string",
+          "enum": ["own-analysis", "internal-incident", "external-standard", "external-research", "vendor-doc"],
+          "description": "`own-analysis`: derived in this repository, no external source \u2014 a COMPLETE discharge, never a fallback for not having looked. `internal-incident`: a failure observed here. `external-standard`: OWASP, WCAG, an RFC, a regulation. `external-research`: a paper or study. `vendor-doc`: a host or provider's own documentation."
+        },
+        "source_urls": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 8 },
+          "description": "Optional. Where the source lives. An `ENC1:` token per `src/rules/source-confidentiality.md` where naming the source in the tracked tree is not permitted. Absent is CORRECT for `own-analysis`, and for an `internal-incident` whose record is a commit or an ADR rather than a URL."
+        },
+        "verified_on": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "description": "Dated stamp on the citation, in the same sense as the claims ledger's `https://\u2026 (YYYY-MM-DD)` evidence form: the date this block was last checked against the rule's normative content and the source it names. It is NOT a fetch receipt \u2014 nothing here retrieves a URL, and a block claiming otherwise would be the manufactured verification `src/rules/direct-answers.md` Iron Law 2 forbids. A stamp that never moves while the rule's body changes is the signal a reader should act on."
+        },
+        "normative_level": {
+          "type": "string",
+          "enum": ["mandatory", "recommended", "informative"],
+          "description": "How binding the SOURCE is \u2014 never how binding this rule is. A rule may impose an Iron Law on top of an `informative` source; stating the source's own level is what stops a house choice being read as an external requirement."
+        }
+      }
     },
     "lifecycle": {
       "type": "string",
@@ -192,6 +228,21 @@
       },
       "description": "ADR-013 trust block. Vocabulary mirrored by scripts/lint_artefact_frontmatter.py."
     },
+    "composition_review": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The authoring-search record (road-to-composition-before-creation Phase 3): which incumbents were searched before this artifact was created, and the declared delta for each. Optional on existing artifacts by design \u2014 nothing is backfilled. Distinct from `collision_ok`, which is keyed by trigger VALUE and fires only on a trigger collision; this is keyed by INCUMBENT and is written at authoring time whether or not any trigger is shared.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["candidate", "disposition", "rationale"],
+        "properties": {
+          "candidate": {"type": "string", "minLength": 1, "description": "The incumbent searched, as `skill:<name>` / `rule:<name>` / `command:<name>` / `guideline:<path>`. The literal `none` records a search that found no credible incumbent \u2014 the value that must exist so an author is never pushed to invent one to satisfy the schema."},
+          "disposition": {"type": "string", "enum": ["extend_incumbent", "compose_with_incumbent", "create_separate", "none_found"], "description": "What happened to this candidate. `create_separate` is the value no other disposition vocabulary in this tree can express: an incumbent exists, was evaluated, and a separate artifact was authored anyway."},
+          "rationale": {"type": "string", "minLength": 16, "description": "One sentence naming the delta \u2014 what this artifact does that the candidate does not, or why the candidate could not absorb it. A lint checks that this is non-empty and that `candidate` resolves; it cannot check that the search was diligent, and does not pretend to."}
+        }
+      }
+    },
     "collision_ok": {
       "type": "object",
       "additionalProperties": {"type": "string", "minLength": 8},

package/src/scripts/schemas/skill.schema.json

@@ -26,7 +26,7 @@
       "type": "string",
       "minLength": 1,
       "maxLength": 200,
-      "description": "Trigger phrase; the ceiling is 200 chars, measured. Lowered from 220 on 2026-08-22 because 220 described no artefact that existed: across all 290 skills the distribution was median 181 / p75 189 / max 200, with ZERO over 200, so the 20 chars above the recommended line were dead headroom a future author could fill with no gate objecting. p75 = 189 is the recorded soft target; 200 is the hard line. Descriptions load eagerly via progressive disclosure, so every char here is standing cost on every spawn."
+      "description": "Trigger phrase; the ceiling is 200 chars, measured. Lowered from 220 on 2026-08-22 because 220 described no artifact that existed: across all 290 skills the distribution was median 181 / p75 189 / max 200, with ZERO over 200, so the 20 chars above the recommended line were dead headroom a future author could fill with no gate objecting. p75 = 189 is the recorded soft target; 200 is the hard line. Descriptions load eagerly via progressive disclosure, so every char here is standing cost on every spawn."
     },
     "compatibility": {
       "type": "string",
@@ -374,6 +374,21 @@
       "default": "active",
       "description": "ADR-013 lifecycle state."
     },
+    "composition_review": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The authoring-search record (road-to-composition-before-creation Phase 3): which incumbents were searched before this artifact was created, and the declared delta for each. Optional on existing artifacts by design \u2014 nothing is backfilled. Distinct from `collision_ok`, which is keyed by trigger VALUE and fires only on a trigger collision; this is keyed by INCUMBENT and is written at authoring time whether or not any trigger is shared.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["candidate", "disposition", "rationale"],
+        "properties": {
+          "candidate": {"type": "string", "minLength": 1, "description": "The incumbent searched, as `skill:<name>` / `rule:<name>` / `command:<name>` / `guideline:<path>`. The literal `none` records a search that found no credible incumbent \u2014 the value that must exist so an author is never pushed to invent one to satisfy the schema."},
+          "disposition": {"type": "string", "enum": ["extend_incumbent", "compose_with_incumbent", "create_separate", "none_found"], "description": "What happened to this candidate. `create_separate` is the value no other disposition vocabulary in this tree can express: an incumbent exists, was evaluated, and a separate artifact was authored anyway."},
+          "rationale": {"type": "string", "minLength": 16, "description": "One sentence naming the delta \u2014 what this artifact does that the candidate does not, or why the candidate could not absorb it. A lint checks that this is non-empty and that `candidate` resolves; it cannot check that the search was diligent, and does not pretend to."}
+        }
+      }
+    },
     "requires_skills": {
       "type": "array",
       "minItems": 1,
@@ -382,7 +397,7 @@
         "type": "string",
         "pattern": "^[a-z][a-z0-9-]*$"
       },
-      "description": "Skill-composition graph (roadmap 3.4): names of sub-skills this skill's body invokes/assumes. Distinct from ADR-015 `requires` (artefact→pack edges). scripts/check_skill_requires.py enforces (a) each target exists and (b) the required skill is co-available wherever this skill ships (same pack, a requires_hint-reachable pack, or always-on)."
+      "description": "Skill-composition graph (roadmap 3.4): names of sub-skills this skill's body invokes/assumes. Distinct from ADR-015 `requires` (artifact→pack edges). scripts/check_skill_requires.py enforces (a) each target exists and (b) the required skill is co-available wherever this skill ships (same pack, a requires_hint-reachable pack, or always-on)."
     },
     "trust": {
       "type": "object",

package/src/scripts/skill_overlap.ts

@@ -300,7 +300,13 @@ export function render(pairs: Pair[], total: number): string {
     const lines: string[] = [
         '# Skill Structural Overlap (baseline)',
         '',
-        '> Generated by `scripts/skill_overlap.py`. Scans',
+        // The literal rather than `_lib/generated_by`'s helper, deliberately:
+        // `lint_skill_originality`'s harness copies THIS FILE ALONE into a
+        // synthetic tree and runs it, so a `./_lib/` import here fails to
+        // resolve at runtime. The attribution is a constant, not a
+        // computation, and the tree-wide invariant is held by the sweep in
+        // tests/scripts/generated_by.test.ts rather than by this import.
+        '> Generated by `skill_overlap`. Do not edit. Scans',
         '> `src/skills/*/SKILL.md` frontmatter (description +',
         '> trigger metadata) and body symbol references. Reports pairs in two',
         `> tiers: **strong** ≥ ${pyFloatStr(STRONG_TOKEN)} description-token Jaccard or ≥ ${pyFloatStr(STRONG_SYMBOL)}`,

package/src/scripts/skill_tools/run_block_d_eval.ts

@@ -28,6 +28,9 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { audit, type PersonaRow } from './audit_persona_coverage.js';
+/** Sentinel for "no catalogue root resolved" — never a readable path. */
+const NO_CATALOGUE = '<no-skills-catalogue>';
+
 import { DEFAULT_SKILLS_DIR, rank } from './score_skill_relevance.js';
 import { suggest } from './suggest_skill_for_task.js';
 import { pyRound } from '../_lib/value_ladder.js';
@@ -312,7 +315,11 @@ function _argError(message: string): never {
 
 export function parse_args(argv: string[]): Args {
     const args: Args = {
-        skills_dir: DEFAULT_SKILLS_DIR,
+        // `?? ''` is deliberately NOT used here: an empty string re-creates
+        // exactly the silent-empty-catalogue defect that repointing
+        // DEFAULT_SKILLS_DIR removed. When no catalogue resolves, this reads
+        // as the literal marker below and the caller's own check reports it.
+        skills_dir: DEFAULT_SKILLS_DIR ?? NO_CATALOGUE,
         personas_dir: PERSONAS_DIR,
         corpus_dir: CORPUS_DIR,
         json: false,

package/src/scripts/skill_tools/score_skill_relevance.ts

@@ -50,7 +50,25 @@ const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/skill_tools/score_skill_relevance.ts → parents[3] of the .py
 // (skill_tools → scripts → src → repo root) is the package root.
 export const ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
-export const DEFAULT_SKILLS_DIR = path.join(ROOT, '.agent-src.uncondensed', 'skills');
+/**
+ * The skills root, resolved the way the two real consumers already resolve it.
+ *
+ * `road-to-inbox-harvest-2026-08-f-skill-selection-evidence` 1.1. This used to be
+ * a hardcoded path to a directory that no longer exists, and the failure was
+ * SILENT: `--task "review a pull request"` printed `(no relevant skills found)`
+ * and exited 0, which is indistinguishable from a task that genuinely matches
+ * nothing. A ranker that reports an empty catalogue as an empty result is worse
+ * than one that crashes.
+ *
+ * `resolveSkillsRoot` is the shared resolver the `skill-route` concern and the
+ * `suggest_skill_for_task` MCP handler use — deliberately shared, because two
+ * resolvers over one catalogue is how a ranker and the tool that exposes it
+ * start ranking different trees. `null` when no candidate root exists, and the
+ * CLI turns that into a distinct exit code rather than an empty list.
+ */
+import { DEFAULT_CATALOGUE_ROOTS, resolveSkillsRoot } from '../_lib/skill_catalogue.js';
+
+export const DEFAULT_SKILLS_DIR: string | null = resolveSkillsRoot(ROOT);
 
 /** Mirror Python len(str) — count Unicode code points, not UTF-16 units. */
 function pyLen(s: string): number {
@@ -364,7 +382,8 @@ const PROG = 'score_skill_relevance.py';
 
 interface Args {
     task: string;
-    skills_dir: string;
+    /** `null` when no catalogue root exists — a DIFFERENT answer from an empty ranking. */
+    skills_dir: string | null;
     top: number;
     json: boolean;
     sample: boolean;
@@ -433,13 +452,75 @@ export const _SAMPLE = {
     task: 'build a livewire component for the user dashboard with reactive state',
 };
 
+/**
+ * Why this catalogue root cannot be ranked, or `null` when it can.
+ *
+ * `road-to-inbox-harvest-2026-08-f-skill-selection-evidence` 1.2. Three states,
+ * and the middle one is the one that actually bit: a root that does not exist, a
+ * root that exists and is EMPTY, and a readable root. `.claude/skills` is a
+ * gitignored projection, so a fresh worktree has the second — and the ranker
+ * reported it as "no relevant skills found", exit 0, on a task that scores 47
+ * against `src/skills`.
+ *
+ * An empty directory is not a missing directory, and neither is an empty result.
+ */
+function catalogueDeficit(dir: string | null): string | null {
+    if (dir === null) {
+        return `no catalogue root resolved — tried ${DEFAULT_CATALOGUE_ROOTS.join(', ')} under ${ROOT}`;
+    }
+    try {
+        if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+            return `${dir} is not a directory`;
+        }
+        if (fs.readdirSync(dir).length === 0) {
+            return `${dir} exists and is EMPTY — an empty catalogue, not an empty result`;
+        }
+    } catch (e) {
+        return `${dir} could not be read: ${e instanceof Error ? e.message : String(e)}`;
+    }
+    return null;
+}
+
 export function main(argv: string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
     const task = args.sample ? _SAMPLE.task : args.task;
     if (!task) {
         _argError('--task is required (or pass --sample)');
     }
-    const rows = rank(task, args.skills_dir);
+    // 1.2 — "no matches" and "no catalogue" are DIFFERENT answers and now have
+    // different exit codes. `missing-skill-recovery` already draws that line for
+    // the MCP tool (`status: no_catalogue`); the CLI did not, and an agent
+    // reading `(no relevant skills found)` from an unreachable catalogue
+    // concludes "no skill covers this" — the exact wrong conclusion that rule
+    // exists to prevent.
+    // The check covers an EXPLICIT --skills-dir too, not only the default. An
+    // operator who passes a wrong path is in exactly the position the silent
+    // failure was about, and answering them with "(no relevant skills found)"
+    // is the same wrong answer with a different cause.
+    const unreadable = catalogueDeficit(args.skills_dir);
+    if (unreadable !== null) {
+        if (args.json) {
+            process.stdout.write(
+                pyJsonDumpsIndent2({
+                    task,
+                    status: 'no_catalogue',
+                    reason: unreadable,
+                    ...(args.skills_dir === null ? { tried: [...DEFAULT_CATALOGUE_ROOTS] } : { skills_dir: args.skills_dir }),
+                }),
+            );
+            process.stdout.write('\n');
+        } else {
+            process.stderr.write(
+                `(no skills catalogue read — ${unreadable})\n` +
+                    'This is NOT "no skill matches": nothing was read, so no conclusion about ' +
+                    'skill coverage follows from it.\n',
+            );
+        }
+        return 3;
+    }
+    // Non-null past the deficit check above, which returns before this line
+    // whenever the root cannot be ranked.
+    const rows = rank(task, args.skills_dir as string);
     if (args.json) {
         const sliced = args.top ? rows.slice(0, args.top) : rows;
         const payload = sliced.map(([n, s, p]) => ({ name: n, score: s, personas: p }));

package/src/scripts/skill_tools/suggest_skill_for_task.ts

@@ -29,6 +29,9 @@ import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { audit, type PersonaRow } from './audit_persona_coverage.js';
+/** Sentinel for "no catalogue root resolved" — never a readable path. */
+const NO_CATALOGUE = '<no-skills-catalogue>';
+
 import { DEFAULT_SKILLS_DIR, rank } from './score_skill_relevance.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -211,7 +214,11 @@ function _parseInt(raw: string): number {
 export function parse_args(argv: string[]): Args {
     const args: Args = {
         task: '',
-        skills_dir: DEFAULT_SKILLS_DIR,
+        // `?? ''` is deliberately NOT used here: an empty string re-creates
+        // exactly the silent-empty-catalogue defect that repointing
+        // DEFAULT_SKILLS_DIR removed. When no catalogue resolves, this reads
+        // as the literal marker below and the caller's own check reports it.
+        skills_dir: DEFAULT_SKILLS_DIR ?? NO_CATALOGUE,
         personas_dir: DEFAULT_PERSONAS,
         top: 3,
         json: false,

package/src/scripts/skill_usage_report.ts

@@ -24,6 +24,7 @@ import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 // tier-usage re-tier already ships. Imported rather than restated so the sink
 // section and the re-tier decision cannot drift to two different numbers.
 import { DEFAULT_TIER_USAGE_RETIER } from '../agent-src/templates/scripts/telemetry/settings.js';
+import { generatedByQuote } from './_lib/generated_by.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 // parent.parent.parent of the .py file (src/scripts/skill_usage_report.py)
@@ -469,7 +470,7 @@ export function render(
     const lines: string[] = [
         '# Skill Usage Report (baseline)',
         '',
-        '> Generated by `src/scripts/skill_usage_report.ts`. Source:',
+        generatedByQuote('skill_usage_report', 'Source:'),
         '> `agents/runtime/metrics/skill-usage.jsonl` (collector emits per-turn',
         '> exposure/mention records). See',
         '> [`step-2-skill-inventory-rationalization.md`](../roadmaps/step-2-skill-inventory-rationalization.md)',