@event4u/agent-config 14.0.0 → 14.2.0

package/src/scripts/hooks/skill_route_hook.ts

@@ -43,6 +43,66 @@
  * need an invalidation story for a tree that changes under the session, and
  * 12.3 ms does not buy one.
  *
+ * HOST-HONEST, AND FAIL-OPEN BY CONSTRUCTION (road-to-catalogue-host-fit Phase
+ * 3). The ranker reads the on-disk tree; the host does not necessarily deliver
+ * it. A skill the host truncated is still rankable and still pointable, and the
+ * pointer then names a skill whose description the model never received — worse
+ * than silence, because a pointer reads as a delivered capability. That is the
+ * roadmap's D-4, and it is MEASURED rather than assumed: 16 of 16 bare entries
+ * in the 2026-08-12 claude observation are still in this ranker's catalogue
+ * (`capture_skill_catalogue --pointable-bare`), among them `design-review`,
+ * `design-intelligence` and `fe-design` — skills this estate's own rules route
+ * to. So the pointer set is filtered against the latest per-entry observation
+ * for the CURRENT host.
+ *
+ * The filter only ever narrows on a positive reading, and every uncertain state
+ * resolves to no filtering at all: no observation log, no record for this host,
+ * a host that publishes no per-entry list, a malformed line, an unknown host, or
+ * any throw. `knownBareNames` returns `null` for each of them and
+ * `filterKnownBare` treats `null` as a pass-through, so behaviour is
+ * byte-identical to the unfiltered line. A filter that quietly hides skills on
+ * missing data is worse than the divergence it treats — the roadmap's own words,
+ * and the reason fail-open is a construction here rather than a convention.
+ *
+ * IT COSTS ZERO ON THE PATH THE HEADER ABOVE PROMISES IS FREE, AND 0.015 ms ON
+ * THE ONE THAT PAYS. The log read is passed in as a thunk, not a value, and
+ * `routePointers` calls it only after the term floor AND the rank both pass. A
+ * prompt below `MIN_TASK_TERMS` therefore still reads no files at all, which is
+ * the claim the 0 ms paragraph makes and an eagerly-read log would have quietly
+ * falsified.
+ *
+ * The FIRING path was measured rather than assumed, because R2 finding 10 is
+ * right that the paragraph above describes a path this branch changed. Measured
+ * 2026-08-18 on this tree, same method as the 12.3 ms figure: `knownBareForHost`
+ * alone is **0.015 ms median / 0.022 ms p95** (n=2000, warm) against a ranked
+ * pass of 8.3 ms median — three orders of magnitude below the ranker it rides
+ * on, and under 0.01 % of the slot's 250 ms p95 budget. The log is seven lines;
+ * a cache would need an invalidation story and 0.015 ms does not buy one, which
+ * is the same reasoning the ranker's own no-cache decision records.
+ *
+ * Note what the existing bench does NOT cover, so nobody reads it as coverage:
+ * `bench_hook_latency`'s synthetic payload carries neither `prompt` nor
+ * `platform`, so this concern returns before the ranker on every bench
+ * iteration. The figures above come from a direct probe, not from that harness.
+ *
+ * THE FLOOR APPLIES TO WHAT IS DELIVERED, NOT TO WHAT WAS RANKED. Filtering
+ * happens BEFORE `MIN_TOP_SCORE` and before the `TOP_K` slice, so the confidence
+ * question is asked of the best pointer the model can actually use. One rule, in
+ * one order: rank → drop the undeliverable → apply the floor → take the top
+ * three.
+ *
+ * That ordering makes silence a real outcome, and the number says so rather than
+ * the prose guessing: on `"review the authorization policy and tenant scope for
+ * this endpoint"` the ranker returns `authz-review` at 47 and the next entry at
+ * 23, against a floor of 31. Suppress the top-1 and NOTHING clears the floor —
+ * the line goes silent instead of naming a 23/100 pointer because the 47 one was
+ * undeliverable. That is the intended reading of a floor calibrated for
+ * confidence, and promoting a sub-floor pointer to fill the gap would be the
+ * "advisory worse than silence" failure this file's risk paragraph ranks first.
+ * `suppressed` is what distinguishes that silence from an unranked prompt, and
+ * `tests/hooks/skill_route_hook.test.ts` pins both cases against the real
+ * corpus rather than a constructed one.
+ *
  * NO ADOPTION THRESHOLD IS COMMITTED HERE. Whether the line changes behaviour
  * is a question for data, not for this header: `skill_route_pointer_rate` is
  * registered in `hook-token-budget.json` under the same owner/review discipline
@@ -51,6 +111,13 @@
  * removed. The score floor above is a TRIGGER calibration and is measured; the
  * adoption threshold is an OUTCOME claim and is deliberately absent.
  *
+ * `skill_route_bare_suppression_rate` is registered beside it under the same
+ * owner, review date and kill discipline, and inherits the same refusal: how
+ * often the filter fires is a number to collect, not one to promise. Its
+ * numerator is carried in the warn `reason` below — `N suppressed` — because no
+ * dedicated counter exists, and that gap is registered as a gap rather than
+ * implied to be automatic.
+ *
  * DELIVERY PATH — the verified one, copied rather than re-derived. A
  * `user_prompt_submit` concern returning `{decision:"allow", context:…}` at
  * exit 0 produces zero stdout: `host_semantics.emitFor` drops the field for
@@ -73,7 +140,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { readHookStdin } from "./hook_stdin.js";
 import { isSyntheticPrompt } from "../_lib/prompt_shape.js";
-import { resolveSkillsRoot } from "../_lib/skill_catalogue.js";
+import { OBSERVATION_LOG, readObservationLog, resolveSkillsRoot } from "../_lib/skill_catalogue.js";
+import { knownBareNames } from "../_lib/skill_catalogue_series.js";
 import { _tokenize, rank, type RankRow } from "../skill_tools/score_skill_relevance.js";
 
 const EXIT_ALLOW = 0;
@@ -119,31 +187,115 @@ function _isObject(v: unknown): v is JsonObject {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 
+/**
+ * Names this host is known to have delivered bare, or `null` for no filtering.
+ *
+ * Every failure mode collapses to `null` — an unknown host, a missing log, an
+ * unreadable one, a host that enumerates nothing, a throw from anywhere in the
+ * read. The three-way distinction `knownBareNames` draws is preserved: an empty
+ * set means *measured clean*, `null` means *never measured*, and only the second
+ * one is produced here by accident.
+ */
+export function knownBareForHost(workspaceRoot: string, host: string | null): Set<string> | null {
+  if (host === null || host === "") return null;
+  try {
+    return knownBareNames(readObservationLog(path.join(workspaceRoot, OBSERVATION_LOG)), host);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Drop the ranked rows this host is known to have delivered bare.
+ *
+ * `null` is a pass-through and returns the input order untouched, which is the
+ * fail-open half of the header's contract and what makes an absent observation
+ * byte-identical to today.
+ */
+export function filterKnownBare(
+  rows: readonly RankRow[],
+  bare: Set<string> | null,
+): RankRow[] {
+  if (bare === null || bare.size === 0) return [...rows];
+  return rows.filter(([name]) => !bare.has(name));
+}
+
+/** What one routing pass decided, including what it refused to name. */
+export interface RouteDecision {
+  rows: RankRow[];
+  /**
+   * Would-be POINTERS dropped as known-bare — the suppression metric's numerator.
+   *
+   * Scoped to the pointer window (`TOP_K` of the unfiltered ranking), not to the
+   * whole ranked list. R2 finding 1: `rank` returns every non-zero-scoring skill
+   * and this catalogue has hundreds, so counting drops across all of them would
+   * let a bare name at rank 40 — never pointable, never a loss — bump the count
+   * on almost every fire. The registered metric defines this as skills the
+   * ranker wanted to POINT AT, and its upper falsifier would otherwise fire on a
+   * perfectly healthy join.
+   */
+  suppressed: number;
+}
+
 /**
  * Rank a prompt and return the pointers worth injecting, or `[]` for silence.
  *
  * Total by construction: a missing root, an unreadable catalogue, or a ranker
  * error all resolve to `[]`. A routing advisory that can crash a turn is worse
  * than one that says nothing.
+ *
+ * `bareProvider` is a THUNK, deliberately — see the header's zero-cost
+ * paragraph. It is called only once both the term floor and the rank have
+ * passed, so the short-prompt path still touches no files. Omitting it disables
+ * filtering entirely, which is what keeps every caller that predates the filter
+ * behaviourally unchanged.
  */
-export function routePointers(prompt: string, skillsDir: string | null): RankRow[] {
-  if (skillsDir === null) return [];
+export function routeDecision(
+  prompt: string,
+  skillsDir: string | null,
+  bareProvider?: () => Set<string> | null,
+): RouteDecision {
+  const silent: RouteDecision = { rows: [], suppressed: 0 };
+  if (skillsDir === null) return silent;
   // Denominator floor BEFORE the catalogue read: a prompt too short to score
   // meaningfully cannot produce a pointer worth 337 file reads either.
   try {
-    if (_tokenize(prompt).size < MIN_TASK_TERMS) return [];
+    if (_tokenize(prompt).size < MIN_TASK_TERMS) return silent;
   } catch {
-    return [];
+    return silent;
   }
   let rows: RankRow[];
   try {
     rows = rank(prompt, skillsDir);
   } catch {
-    return [];
+    return silent;
+  }
+  let bare: Set<string> | null = null;
+  if (bareProvider !== undefined) {
+    try {
+      bare = bareProvider();
+    } catch {
+      bare = null; // fail open, never silent-narrow
+    }
   }
-  const top = rows[0];
-  if (top === undefined || top[1] < MIN_TOP_SCORE) return [];
-  return rows.slice(0, TOP_K);
+  const deliverable = filterKnownBare(rows, bare);
+  // The pointer WINDOW, not the ranked list — see `RouteDecision.suppressed`.
+  const suppressed =
+    bare === null ? 0 : rows.slice(0, TOP_K).filter(([name]) => bare.has(name)).length;
+  // The floor asks its question of the best DELIVERABLE pointer, not of a
+  // pointer the model cannot use. See the header's one-rule-one-order note.
+  const top = deliverable[0];
+  if (top === undefined || top[1] < MIN_TOP_SCORE) return { rows: [], suppressed };
+  return { rows: deliverable.slice(0, TOP_K), suppressed };
+}
+
+/** The rows alone. Kept because most callers and fixtures want only these. */
+export function routePointers(
+  prompt: string,
+  skillsDir: string | null,
+  bareProvider?: () => Set<string> | null,
+): RankRow[] {
+  return routeDecision(prompt, skillsDir, bareProvider).rows;
 }
 
 /**
@@ -191,13 +343,22 @@ export function main(): number {
   if (!prompt) return EXIT_ALLOW;
   if (isSyntheticPrompt(prompt)) return EXIT_ALLOW; // harness turn, not a task
 
-  const rows = routePointers(prompt, resolveSkillsRoot(_workspaceRoot(env)));
+  const root = _workspaceRoot(env);
+  const platform = env["platform"];
+  const host = typeof platform === "string" && platform ? platform : null;
+  const { rows, suppressed } = routeDecision(prompt, resolveSkillsRoot(root), () =>
+    knownBareForHost(root, host),
+  );
   if (rows.length === 0) return EXIT_ALLOW; // silence is the default
 
   process.stdout.write(
     `${JSON.stringify({
       decision: "warn",
-      reason: `skill-route: ${rows.length} pointer(s), top ${rows[0]![1]}/100`,
+      reason:
+        `skill-route: ${rows.length} pointer(s), top ${rows[0]![1]}/100` +
+        // The suppression metric's numerator. Named only when non-zero, so the
+        // common line keeps its shape and its registered byte budget.
+        (suppressed > 0 ? `, ${suppressed} suppressed as host-bare` : ""),
       additional_context: buildRouteLine(rows),
     })}\n`,
   );

package/src/scripts/install-hooks.sh

@@ -35,6 +35,32 @@ cat > "$HOOKS_DIR/pre-push" << 'EOF'
 # so any derived-output drift blocks the push here. Runtime ~15-40s (it
 # regenerates the tool trees) — cheaper than a red CI run and a fixup re-push.
 
+# A delete-only push has no content to gate, so every check below is answering
+# a question nobody asked. Measured 2026-08-18 during the 14.0.0 release:
+# `git push origin --delete release/14.0.0` was refused by the branch-freshness
+# gate because the CHECKED-OUT branch was behind main — a fact with no bearing
+# on removing a remote ref. The deletion had to go through the GitHub API to
+# happen at all, which routes around the whole hook rather than around one gate.
+#
+# Git feeds pre-push one line per ref on stdin:
+#   <local ref> <local sha> <remote ref> <remote sha>
+# and a deletion carries the all-zero local sha. Reading stdin is safe here:
+# nothing below consumes it.
+delete_only=1
+saw_ref=0
+while read -r _local_ref local_sha _remote_ref _remote_sha; do
+    [ -z "${local_sha:-}" ] && continue
+    saw_ref=1
+    # Any non-zero character means a real object is being pushed.
+    case "$local_sha" in
+        *[!0]*) delete_only=0 ;;
+    esac
+done
+if [ "$saw_ref" = "1" ] && [ "$delete_only" = "1" ]; then
+    echo "🗑️  Delete-only push — no ref advances, so the content gates have nothing to check. Skipping."
+    exit 0
+fi
+
 fail=0
 
 if ! command -v task >/dev/null 2>&1; then