@event4u/agent-config 12.1.0 → 14.0.0

package/src/scripts/lint_rule_skill_pack_reach.ts

@@ -66,6 +66,7 @@ import { fileURLToPath } from 'node:url';
 
 import { parse as parseYaml } from 'yaml';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -404,6 +405,48 @@ function main(argv: readonly string[] = process.argv.slice(2)): number {
     const errors = findings.filter((f) => f.kind === 'unreachable-route');
     const advisories = findings.filter((f) => f.kind === 'unrouted-skill');
 
+    // Per-target completeness accounting over BOTH populations this gate
+    // reasons about, id-prefixed so they stay distinguishable in one tally.
+    // The skips are the point: check 1 walks past every unscoped rule and
+    // check 2 past every unscoped skill, because "ships everywhere" makes the
+    // reachability question inapplicable rather than satisfied. Without the
+    // ledger those walk-pasts were indistinguishable from checks that passed —
+    // the exact "checked 20 of 300, printed one green line" shape.
+    //
+    // This tally is deliberately NOT the `scanned:` line below. That line is
+    // the machine-read coverage contract and stays the rule count; this is the
+    // human-auditable breakdown beside it, per `_lib/gate_ledger` § report.
+    const ledger = new GateLedger('lint_rule_skill_pack_reach');
+    const routedSkills = [...new Set(rules.flatMap((r) => r.routesToSkills))]
+        .filter((sk) => skillPacks.has(sk))
+        .sort();
+    ledger.plan([
+        ...rules.map((r) => `rule:${r.name}`),
+        ...routedSkills.map((sk) => `skill:${sk}`),
+    ]);
+    const failedSubjects = new Set(findings.map((f) => f.subject));
+    for (const rule of rules) {
+        const id = `rule:${rule.name}`;
+        if (rule.packs.length === 0) {
+            ledger.skip(id, 'not_applicable_kind');
+        } else if ([...failedSubjects].some((sub) => sub.startsWith(`${rule.name} → skill:`))) {
+            ledger.fail(id, 'unreachable-route');
+        } else {
+            ledger.complete(id);
+        }
+    }
+    for (const sk of routedSkills) {
+        const id = `skill:${sk}`;
+        if ((skillPacks.get(sk) ?? []).length === 0) {
+            ledger.skip(id, 'not_applicable_kind');
+        } else if (failedSubjects.has(id)) {
+            ledger.fail(id, 'unrouted-skill');
+        } else {
+            ledger.complete(id);
+        }
+    }
+    ledger.report();
+
     // --quiet suppresses the per-finding lines but never the count line: this
     // gate is expected to stay non-empty for a while, and a quiet run that
     // printed nothing at all would read as clean.

package/src/scripts/lint_skill_router_head.ts

@@ -38,6 +38,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const _FILE = fileURLToPath(import.meta.url);
@@ -204,6 +205,26 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const heads = collectSkillHeads(path.join(REPO, SKILLS_REL));
     const { findings, staleAllowlist } = evaluate(heads);
 
+    // Per-target completeness accounting. The interesting outcome here is the
+    // SKIP: a grandfathered head is over the cap and deliberately unchecked, so
+    // without a ledger it was indistinguishable from a head that passed. The
+    // allowlist size is already printed, but only the ledger ties each skipped
+    // name to the reason it went unchecked.
+    const ledger = new GateLedger('lint_skill_router_head');
+    ledger.plan(heads.map((h) => h.name));
+    const failed = new Set(findings.map((f) => f.skill));
+    const allow = new Set(GRANDFATHERED);
+    for (const h of heads) {
+        if (failed.has(h.name)) {
+            ledger.fail(h.name, `${String(h.lines)} lines over the ${String(MAX_HEAD_LINES)}-line cap with no mode bodies`);
+        } else if (h.lines > MAX_HEAD_LINES && allow.has(h.name)) {
+            ledger.skip(h.name, 'declared_exemption');
+        } else {
+            ledger.complete(h.name);
+        }
+    }
+    ledger.report();
+
     for (const s of staleAllowlist) {
         process.stderr.write(
             `⚠️   lint_skill_router_head: '${s}' is grandfathered but no longer over the cap — remove it from GRANDFATHERED so the ratchet keeps its teeth\n`,

package/src/scripts/mcp_server/consumer_tool_catalog.json

@@ -544,10 +544,33 @@
     },
     {
       "name": "suggest_skill_for_task",
-      "description": "[stub — implemented on demand] Match a free-form task description to the most relevant skills, ranked by their frontmatter triggers. Use to pick a skill for a described task before starting work. Read-only. Returns a ranked list of skills with name, description, and match reason.",
+      "description": "Match a free-form task description to the most relevant skills, ranked by a deterministic keyword scorer over SKILL.md frontmatter. Use when a skill you need is not in the catalogue the host delivered — a measured host dropped 402 entries from its model-visible list — so asking by name is impossible while asking by task is not. Read-only: no shell, no writes, and no skill bodies are returned, only names, scores and declared personas.",
       "side_effect": "ro",
-      "implemented_on": [],
-      "input_schema": {}
+      "implemented_on": [
+        "stdio"
+      ],
+      "input_schema": {
+        "type": "object",
+        "required": [
+          "task"
+        ],
+        "properties": {
+          "task": {
+            "type": "string",
+            "description": "Free-form description of the task to match skills against."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "default": 5,
+            "description": "Maximum number of skills to return. Defaults to 5."
+          }
+        },
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
+      }
     },
     {
       "name": "sync_agent_settings",

package/src/scripts/mcp_server/tool_catalog_source.ts

@@ -96,30 +96,12 @@ export const STUB_TOOLS: readonly StubToolSource[] = [
             additionalProperties: false,
         },
     },
-    {
-        name: 'suggest_skill_for_task',
-        description:
-            'Match a free-form task description to the most relevant ' +
-            'skills, ranked by their frontmatter triggers. Use to pick a ' +
-            'skill for a described task before starting work. Read-only. ' +
-            'Returns a ranked list of skills with name, description, and ' +
-            'match reason.',
-        side_effect: 'ro',
-        input_schema: {
-            type: 'object',
-            properties: {
-                task: { type: 'string', description: 'Free-form description of the task to find a skill for.' },
-                limit: {
-                    type: 'integer',
-                    minimum: 1,
-                    default: 5,
-                    description: 'Maximum number of skills to return. Defaults to 5.',
-                },
-            },
-            required: ['task'],
-            additionalProperties: false,
-        },
-    },
+    // `suggest_skill_for_task` moved to ALLOWLIST in mcp_server/tools.ts
+    // (road-to-inbox-harvest-2026-08-d-runtime-skill-routing 4.1) — it is
+    // implemented now, and `build_mcp_catalog` refuses a name registered in
+    // both places. Its published input schema (`task` + `limit`) was carried
+    // over verbatim rather than re-designed: the stub is a contract consumers
+    // may already have read.
     {
         name: 'mine_session',
         description:

package/src/scripts/mcp_server/tools.ts

@@ -1210,7 +1210,94 @@ async function _readResourceBodyHandler(
 // unlisted tool. Boot-time stderr log enumerates the registered set.
 // ---------------------------------------------------------------------
 
+/**
+ * `suggest_skill_for_task` — the recovery path for a truncated catalogue.
+ *
+ * Promoted from a discovery stub because the defect it answers is measured, not
+ * hypothetical: on the one host that publishes its own truncation, a default
+ * install had 402 entries dropped from the model-visible skills list — the
+ * host's own count against its own denominator, not a subtraction over ours
+ * (`agents/evidence/analysis/scoped-projection-host-delivery.md`). An agent
+ * that cannot see a skill also cannot ask for it by name, so the only reachable
+ * question is "what fits this task" — which is what the deterministic ranker
+ * answers, over the TREE rather than over the host's catalogue.
+ *
+ * Read-only and shell-free by construction: it reads SKILL.md frontmatter and
+ * returns names, scores and declared personas. No skill BODY is returned — the
+ * caller opens what it picked, so a wrong rank costs one read rather than a
+ * context payload.
+ */
+async function _suggestSkillForTaskHandler(
+    args: Record<string, unknown>,
+    consumerRoot: string,
+): Promise<Record<string, unknown>> {
+    const task = typeof args['task'] === 'string' ? args['task'] : '';
+    if (task.trim() === '') {
+        return { status: 'error', error: 'task must be a non-empty string', suggestions: [] };
+    }
+    // `limit`, not `top` — the stub published `limit` and a consumer may have
+    // read that contract already. Renaming it on promotion would break a
+    // caller for cosmetic reasons.
+    const limitRaw = args['limit'];
+    const limit =
+        typeof limitRaw === 'number' && Number.isFinite(limitRaw) ? Math.floor(limitRaw) : 5;
+
+    const catalogue = await import('../_lib/skill_catalogue.js');
+    const skillsDir = catalogue.resolveSkillsRoot(consumerRoot);
+    if (skillsDir === null) {
+        // A missing catalogue is UNKNOWN, never "no skill fits this task". The
+        // second reads as a ranked answer and would be a confident empty list —
+        // the same zero-from-silence failure `capture_skill_catalogue` refuses.
+        return {
+            status: 'no_catalogue',
+            searched: [...catalogue.DEFAULT_CATALOGUE_ROOTS],
+            consumer_root: consumerRoot,
+            suggestions: [],
+        };
+    }
+
+    const { rank } = await import('../skill_tools/score_skill_relevance.js');
+    const rows = rank(task, skillsDir).slice(0, Math.max(1, limit));
+    return {
+        status: 'ok',
+        skills_root: skillsDir,
+        suggestions: rows.map(([name, score, personas]) => ({ skill: name, score, personas })),
+    };
+}
+
 export const ALLOWLIST: Record<string, BuiltinTool> = {
+    suggest_skill_for_task: {
+        name: 'suggest_skill_for_task',
+        side_effect: 'ro',
+        description:
+            'Match a free-form task description to the most relevant skills, ' +
+            'ranked by a deterministic keyword scorer over SKILL.md ' +
+            'frontmatter. Use when a skill you need is not in the catalogue ' +
+            'the host delivered — a measured host dropped 402 entries from ' +
+            'its model-visible list — so asking by name is impossible while ' +
+            'asking by task is not. ' +
+            'Read-only: no shell, no writes, and no skill bodies are returned, ' +
+            'only names, scores and declared personas.',
+        input_schema: {
+            type: 'object',
+            required: ['task'],
+            properties: {
+                task: {
+                    type: 'string',
+                    description:
+                        'Free-form description of the task to match skills against.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    default: 5,
+                    description: 'Maximum number of skills to return. Defaults to 5.',
+                },
+            },
+            additionalProperties: false,
+        },
+        handler: _suggestSkillForTaskHandler,
+    },
     lint_skills: {
         name: 'lint_skills',
         side_effect: 'ro',

package/src/scripts/release.ts

@@ -124,7 +124,9 @@ import {
     derive_category_hits,
     render_derived_head_values,
 } from './_lib/release_highlights.js';
+import { gh_argv_label, gh_retry } from './_lib/gh_transient.js';
 import {
+    NEXT_SECTION_RE,
     extract_changelog_section,
     pr_body_from_section,
     release_notes_from_section,
@@ -616,6 +618,31 @@ function git(args: readonly string[], opts: { capture?: boolean } = {}): string
     return capture ? r.stdout.trim() : '';
 }
 
+function _sleep_ms(ms: number): void {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * `gh` with transient-failure retry and a readable death. Always captures, so
+ * the classifier can see stderr; `check: false` keeps the caller's fallback.
+ */
+function gh(args: readonly string[], opts: { check?: boolean } = {}): RunResult {
+    const check = opts.check ?? true;
+    const r = gh_retry(args, (argv) => run(argv, { check: false, capture: true }), {
+        sleep: (ms) => (_exec_override ? undefined : _sleep_ms(ms)),
+        notify: (m) => process.stdout.write(`${m}\n`),
+    });
+    if (check && r.returncode !== 0) {
+        die(`${gh_argv_label(args)} failed (${r.returncode}):\n${(r.stderr || r.stdout).trim()}`);
+    }
+    // Mutating calls used to inherit stdio — echo, or the PR / release URL
+    // vanishes. Probes (`check: false`) stay quiet; their stdout is JSON.
+    if (check && r.stdout.trim()) {
+        process.stdout.write(`${r.stdout.trim()}\n`);
+    }
+    return r;
+}
+
 /**
  * One name per failing check, from `gh pr checks --json name,bucket` output.
  *
@@ -879,14 +906,14 @@ function watch_pr_checks(branch: string): void {
  *
  * git's wording for this is stable across versions: the hint is `fetch first`
  * / `Updates were rejected`, and the ref line carries `[rejected]` with
- * `non-fast-forward` or `fetch first`.
+ * `non-fast-forward` or `fetch first`. A stale lease is a SECOND wording —
+ * `[remote rejected]` + `cannot lock ref … but expected`; pinned in the tests.
  */
 export function _is_non_fast_forward(stderr: string, stdout: string): boolean {
     const text = `${stderr}\n${stdout}`;
-    return (
-        /\[rejected\]/i.test(text) &&
-        /(non-fast-forward|fetch first|behind its remote counterpart)/i.test(text)
-    );
+    if (!/\[(?:remote )?rejected\]/i.test(text)) return false;
+    if (/cannot lock ref[^\n]*but expected/i.test(text)) return true;
+    return /(non-fast-forward|fetch first|behind its remote counterpart)/i.test(text);
 }
 
 function push_release_branch(branch: string): void {
@@ -923,13 +950,9 @@ function push_release_branch(branch: string): void {
 
 /** mergeStateStatus of the branch's PR ('' when the probe fails). */
 function _pr_merge_state(branch: string): string {
-    const r = run(
-        ['gh', 'pr', 'view', branch, '--json', 'mergeStateStatus', '--jq', '.mergeStateStatus'],
-        {
-            check: false,
-            capture: true,
-        },
-    );
+    const r = gh(['pr', 'view', branch, '--json', 'mergeStateStatus', '--jq', '.mergeStateStatus'], {
+        check: false,
+    });
     return r.returncode === 0 ? r.stdout.trim() : '';
 }
 
@@ -973,14 +996,11 @@ function _refresh_pr_body_from_head(branch: string, target: string): void {
     }
     const capped = _cap_body(section!.body, GH_PR_BODY_LIMIT - 200, '`CHANGELOG.md` in this PR');
     const body = pr_body_from_section(capped, target);
-    const live = run(['gh', 'pr', 'view', branch, '--json', 'body', '-q', '.body'], {
-        check: false,
-        capture: true,
-    });
+    const live = gh(['pr', 'view', branch, '--json', 'body', '-q', '.body'], { check: false });
     if (live.returncode === 0 && live.stdout.replace(/\r\n/gu, '\n').trim() === body.trim()) {
         return;
     }
-    run(['gh', 'pr', 'edit', branch, '--body', body]);
+    gh(['pr', 'edit', branch, '--body', body]);
 }
 
 function merge_release_pr(branch: string, wait_for_checks: boolean): void {
@@ -1147,22 +1167,8 @@ function _push_tag(tag: string): void {
 
 /** Most recent PR (any state) with `release/X.Y.Z` as head, or null. */
 function _pr_for_branch(branch: string): Record<string, unknown> | null {
-    const r = run(
-        [
-            'gh',
-            'pr',
-            'list',
-            '--head',
-            branch,
-            '--state',
-            'all',
-            '--json',
-            'number,state,url',
-            '--limit',
-            '1',
-        ],
-        { check: false, capture: true },
-    );
+    const argv = ['pr', 'list', '--head', branch, '--state', 'all', '--json', 'number,state,url'];
+    const r = gh([...argv, '--limit', '1'], { check: false });
     if (r.returncode !== 0) {
         return null;
     }
@@ -1476,8 +1482,7 @@ function _previous_test_count_from_changelog(prev_tag: string | null): number |
     }
     const headEnd = m.index + m[0].length;
     const rest = text.slice(headEnd);
-    const next_re = /^##\s+\[?\d+\.\d+\.\d+/m;
-    const next_heading = next_re.exec(rest);
+    const next_heading = NEXT_SECTION_RE.exec(rest);
     const sectionEnd = headEnd + (next_heading ? next_heading.index : rest.length);
     const section = text.slice(headEnd, sectionEnd);
     const count_match = _TEST_COUNT_LINE_RE.exec(section);
@@ -2141,19 +2146,8 @@ function execute(
             '`CHANGELOG.md` in this PR',
         );
         const pr_body = pr_body_from_section(pr_changelog, plan.target);
-        run([
-            'gh',
-            'pr',
-            'create',
-            '--base',
-            MAIN_BRANCH,
-            '--head',
-            branch,
-            '--title',
-            `release: ${plan.target}`,
-            '--body',
-            pr_body,
-        ]);
+        gh(['pr', 'create', '--base', MAIN_BRANCH, '--head', branch,
+            '--title', `release: ${plan.target}`, '--body', pr_body]);
     }
 
     // ─── 6. wait for checks ─────────────────────────────────────────────────
@@ -2236,16 +2230,7 @@ function execute(
             GH_RELEASE_NOTES_LIMIT,
             '`CHANGELOG.md`',
         );
-        run([
-            'gh',
-            'release',
-            'create',
-            plan.target,
-            '--title',
-            plan.target,
-            '--notes',
-            notes,
-        ]);
+        gh(['release', 'create', plan.target, '--title', plan.target, '--notes', notes]);
 
         // ─── 9b. dispatch-chain the tag-triggered workflows (--ci only) ──────
         // release-guard.yml, publish-npm.yml, and cloud-release.yml all

package/src/scripts/routing_doctor.ts

@@ -63,7 +63,7 @@ import {
   classifyTask,
   type ActivationInputs,
 } from "./_lib/auto_dispatch.js";
-import { TIER_ORDER, readCooldowns } from "./_lib/tier_budget_routing.js";
+import { COOLDOWN_FILE, TIER_ORDER, readCooldowns } from "./_lib/tier_budget_routing.js";
 import {
   instructionsLoadedRecord,
   measureStandingDelivery,
@@ -111,6 +111,13 @@ export interface OrchestrationReport {
   downshift: boolean;
   /** cost.budgets.per_tier ceilings + live cool-down state per tier. */
   tier_budgets: Record<string, { ceiling_usd: number | null; cooldown_until_ms: number }>;
+  /**
+   * Whether the cool-down store exists on disk. `readCooldowns` returns all
+   * zeros both when no tier is cooling AND when nothing has ever written the
+   * file, so a bare zero cannot distinguish "measured: live" from "no reading
+   * exists". This flag is what separates them.
+   */
+  cooldown_store_present: boolean;
   host_manifest: HostCapabilityManifest;
   /**
    * The host identifier the capability registry was keyed on, and whether it
@@ -158,14 +165,23 @@ export interface OrchestrationReport {
 }
 
 /**
- * Adherence ≠ delivery: budget-aware tier routing has no on/off setting any
- * more (always-on orchestration removed `subagents.budget_routing`), so the
- * doctor always checks the DELIVERY evidence — orchestration audit lines
- * that carry a tier decision. Dispatches recorded with ZERO tier-carrying
- * lines → WARN with the exact reason. Read-only over
- * agents/runtime/state/audit/*.jsonl; no new state. This closes the same
- * blind-spot class the session-canary incident exposed (policy present,
- * delivery silently absent).
+ * Tier-decision coverage in the orchestration record.
+ *
+ * REPOINTED 2026-08-16. This used to check "delivery evidence" for budget-aware
+ * tier routing, on the reasoning that policy can be present while delivery is
+ * silently absent — the session-canary blind-spot class. That layer is now
+ * ARCHIVED (`docs/contracts/budget-routing.md`), so the old rationale no longer
+ * holds and the old warning would have been permanently true and un-actionable:
+ * nothing dispatches through a tier decision by design, so telling the operator
+ * "the relation may not be running" is a dead advisory of exactly the shape this
+ * repository keeps removing elsewhere.
+ *
+ * What it measures now is narrower and still worth having: how many recorded
+ * dispatches carry a `tier` at all. That is the SAME field the archived layer's
+ * revisit-if depends on — a saving can only be computed once both the chosen and
+ * the realized tier are recorded — so this is the instrument that would show the
+ * reopen condition arriving. It reports coverage rather than warning about it.
+ * Read-only over agents/runtime/state/audit/*.jsonl; no new state.
  */
 export function check_budget_delivery(
   workspace_root: string,
@@ -202,9 +218,10 @@ export function check_budget_delivery(
   }
   if (out.eligible_dispatches > 0 && out.budget_evidence_lines === 0) {
     out.warning =
-      `budget-aware tier routing shows no delivery evidence: ` +
-      `${out.eligible_dispatches} orchestration dispatch(es) recorded, 0 carry a tier decision — ` +
-      `the relation may not be running (adherence != delivery)`;
+      `tier-decision coverage is 0 of ${out.eligible_dispatches} recorded dispatch(es) — ` +
+      `expected while budget routing stays archived (docs/contracts/budget-routing.md). ` +
+      `This is the counter its revisit-if reads: a non-zero value here is the signal ` +
+      `that per-tier dispatch has reappeared and the decision can be reopened`;
   }
   return out;
 }
@@ -356,6 +373,7 @@ export function collect_orchestration(
   const ledger_present = fs.existsSync(path.join(tracking_dir, "sessions.jsonl"));
   const per_tier = (cost_budgets["per_tier"] ?? {}) as Record<string, unknown>;
   const cooldowns = readCooldowns(tracking_dir);
+  const cooldown_store_present = fs.existsSync(path.join(tracking_dir, COOLDOWN_FILE));
   const tier_budgets: OrchestrationReport["tier_budgets"] = {};
   for (const t of TIER_ORDER) {
     const v = per_tier[t];
@@ -382,6 +400,7 @@ export function collect_orchestration(
     halted,
     downshift,
     tier_budgets,
+    cooldown_store_present,
     host_manifest,
     host_platform: platform,
     host_platform_assumed: platform_assumed,
@@ -636,10 +655,28 @@ function _render(report: DoctorReport): string {
   );
   const tierBits = Object.entries(o.tier_budgets).map(([t, s]) => {
     const cap = s.ceiling_usd === null ? "no cap" : `$${s.ceiling_usd}`;
-    const cool = s.cooldown_until_ms > 0 ? " COOLING" : "";
+    // `> Date.now()`, not `> 0`. The purger went with the archived permit
+    // lifecycle (`tripCooldown` rewrote the map on every write), so a stale
+    // entry now has nothing to clear it and `> 0` would render COOLING for
+    // ever. Latent rather than live — there is no writer either — but the
+    // comparison should be the one that stays correct if a writer returns.
+    const cool = s.cooldown_until_ms > Date.now() ? " COOLING" : "";
     return `${t}=${cap}${cool}`;
   });
   lines.push(`  tier budgets (rolling-24h): ${tierBits.join(" · ")}`);
+  // `readCooldowns` returns all zeros both when no tier is cooling and when
+  // nothing has ever written the store, so a missing COOLING marker alone
+  // cannot be read as a measured "this tier is live". Report which of the two
+  // it is — the same unavailable-vs-false distinction the capability-
+  // provenance line above makes two lines earlier. Derived from the store's
+  // existence rather than from a caller count, so it stays true if the
+  // cool-down producer is ever wired.
+  if (!o.cooldown_store_present) {
+    lines.push(
+      `  cool-down state: no reading on disk (${COOLDOWN_FILE} absent) — ` +
+        `absence of COOLING above is not evidence of a live tier`,
+    );
+  }
   if (o.delivery.warning) {
     lines.push(`  ⚠️ ${o.delivery.warning}`);
   } else if (o.delivery.eligible_dispatches > 0) {