@event4u/agent-config 8.7.0 → 8.9.0

package/docs/succession.md

@@ -0,0 +1,80 @@
+# Succession — the minimal knowledge to take over
+
+> **Bus-factor doc (road-to-maintainer-bus-factor Phase 3).** If the maintainer
+> is unavailable, this is what a successor needs to keep `main` healthy and cut
+> releases. **No secret values live here — pointers only.** Companion:
+> [`release-runbook.md`](release-runbook.md) (the how-to-release steps).
+
+## Honest bus-factor (tracked, not inflated)
+
+- **Distinct humans who have reviewed/merged in the trailing 90 days: 1** (the
+  maintainer, `@matze4u`). The project is a single-maintainer repo; an AI
+  self-review gate (deferred — see the roadmap Phase 1) raises the floor but is
+  **not** independent human review.
+- Recompute this number honestly at any time:
+
+  ```bash
+  # merged PRs in the last 90 days + who reviewed them
+  gh pr list --state merged --search "merged:>=$(date -v-90d +%Y-%m-%d 2>/dev/null || date -d '90 days ago' +%Y-%m-%d)" \
+    --json number,author,reviews \
+    --jq '[.[] | .reviews[]?.author.login] | unique'
+  ```
+
+  Report the count as-is. A bus-factor of 1 stated plainly beats a bus-factor of
+  1 implied to be more.
+
+## Secrets / tokens — where they live, what they gate
+
+Configured in **GitHub → Settings → Secrets and variables → Actions** (repo
+secrets), never in the tree. None is required for the *core* release (version
+bump + tag + GitHub Release); they gate the **downstream** publish/deploy legs.
+
+| Secret | Gates | Missing → |
+|---|---|---|
+| `RELEASE_PR_TOKEN` (optional PAT / App token, `contents:write` + `pull-requests:write`) | Unattended release PR checks in [`release.yml`](../.github/workflows/release.yml) | One manual **"Approve workflows to run"** click per release (deliberate checkpoint, not a failure). |
+| — (none: **npm OIDC Trusted Publishing**) | `publish-npm.yml` — uses `id-token: write`, no stored npm token | If OIDC trust is misconfigured on npmjs, npm publish fails; fix the trusted-publisher config on the npm package, not a secret. |
+| `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_WORKER_SUBDOMAIN`, `MCP_SMOKE_TOKEN` | `deploy-mcp-worker.yml` (MCP worker deploy + smoke) | MCP worker deploy skips/fails; core release unaffected. |
+| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY` | `cross-model-canary.yml` + any AI-council / self-review automation | Canary + council automation skip; core release unaffected. |
+| `GITHUB_TOKEN` (auto-provided) | all workflows' default auth | n/a — GitHub injects it. |
+
+The live source of truth for which workflow needs which secret is the
+`secrets.*` references in [`.github/workflows/`](../.github/workflows/) — grep
+there if this table drifts:
+
+```bash
+grep -rhoE "secrets\.[A-Z_]+" .github/workflows/ | sort -u
+```
+
+## Operator-gated steps (need a human with credentials)
+
+- **Release-PR workflow approval** — the "Approve workflows to run" click when
+  `RELEASE_PR_TOKEN` is absent (see the runbook § 3.A).
+- **Branch-protection ruleset** — applied in GitHub → Settings → Rules UI;
+  source of truth mirrored in [`branch-protection-policy.md`](contracts/branch-protection-policy.md).
+  Not in code; a successor edits it in the UI.
+- **Repo administration** (visibility / rename / delete) — the
+  `production-visibility` environment gates manual approval; see
+  [`CONTRIBUTING.md`](../CONTRIBUTING.md).
+- **npm trusted-publisher config** — set on npmjs.org for the package, not in
+  this repo.
+
+## "Healthy main" — what good looks like
+
+- Latest `main` commit is green on all required checks for its PR shape
+  (see [`branch-protection-policy.md`](contracts/branch-protection-policy.md),
+  [`ci-green-floor.md`](contracts/ci-green-floor.md)).
+- No drift gate red: `release-drift.yml`, `release-guard.yml`,
+  `check-visibility-drift.yml`, the consistency + claims + proof gates.
+- `docs/CLAIMS.md` resolves (`task check-claims`); `docs/proof.md` is in sync
+  (`task build-proof-check`).
+- No completed roadmap left unarchived in `agents/roadmaps/` (the
+  `roadmap:progress-check` backstop).
+
+## Minimal takeover checklist
+
+1. Get `gh` authenticated as a repo admin; confirm `gh auth status`.
+2. Read [`release-runbook.md`](release-runbook.md) end-to-end.
+3. Confirm the secrets above are present for whichever downstream legs matter.
+4. Cut a `--dry-run` release (`task release -- --dry-run`) to see the pipeline
+   with zero mutations.
+5. When ready, follow the runbook for a real release.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "8.7.0",
+    "version": "8.9.0",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,
@@ -12,7 +12,7 @@
     "bugs": {
         "url": "https://github.com/event4u-app/agent-config/issues"
     },
-    "homepage": "https://github.com/event4u-app/agent-config#readme",
+    "homepage": "https://event4u-app.github.io/agent-config",
     "keywords": [
         "ai-agent",
         "mcp",

package/src/agent-src/scripts/update_roadmap_progress.ts

@@ -67,8 +67,9 @@ const _require = createRequire(import.meta.url);
 // CHECKBOX_RE = re.compile(r"^\s*[-*]\s+\[([ xX~\-])\]\s", re.MULTILINE)
 const CHECKBOX_RE = /^[ \t\n\r\f\v]*[-*][ \t\n\r\f\v]+\[([ xX~\-])\][ \t\n\r\f\v]/gm;
 // PHASE_RE (MULTILINE) — H2/H3 "Phase <id>" with optional separator + name.
+// Numeric ids accept dotted sub-phases ("1.0", "4.1", "2.3.1").
 const PHASE_RE =
-    /^(#{2,3})[ \t\n\r\f\v]+Phase[ \t\n\r\f\v]+(\d+[a-z]?|[IVX]+|[A-Z](?:\d+)?)(?:[\s:—\-]+([\s\S]*?))?[ \t\f\v\r]*$/gm;
+    /^(#{2,3})[ \t\n\r\f\v]+Phase[ \t\n\r\f\v]+(\d+(?:\.\d+)*[a-z]?|[IVX]+|[A-Z](?:\d+)?)(?:[\s:—\-]+([\s\S]*?))?[ \t\f\v\r]*$/gm;
 // TITLE_RE = re.compile(r"^#\s+(?:Roadmap:\s*)?(.+?)\s*$", re.MULTILINE)
 const TITLE_RE = /^#[ \t\n\r\f\v]+(?:Roadmap:[ \t\n\r\f\v]*)?(.+?)[ \t\f\v\r]*$/m;
 const EXCLUDE_NAMES: ReadonlySet<string> = new Set([

package/src/config/agent-settings.template.yml

@@ -524,13 +524,21 @@ subagents:
   # on  = auto-dispatch delegable tasks without asking (surface the choice
   #       in one line).
   #
-  # Initial SHIPPED default is `ask` on hosts whose capability manifest reports
+  # SHIPPED default is `on` on hosts whose capability manifest reports
   # `subagent_spawn: true`, and `off` on hosts without a subagent primitive.
-  # The shipped default flips toward `on` (host-gated) only behind the Phase-6
-  # benchmark gate of road-to-auto-subagent-orchestration.md — never on an
-  # unmeasured claim. Auto-dispatch is also a no-op wherever the host manifest
-  # reports `subagent_spawn: false`, regardless of this value.
-  auto: ask
+  # Auto-dispatch stays a no-op wherever the manifest reports
+  # `subagent_spawn: false`, regardless of this value.
+  #
+  # The default was `ask` until 2026-07-09, when it was flipped to `on` after a
+  # re-evaluation (agents/settings/contexts/orchestration-default-flip-verdict.md
+  # § 2026-07-09; ADR-117). The flip rests on a bounded-downside argument, NOT a
+  # passed benchmark: delegable slices are already cost-routed to the cheapest
+  # capable tier, classification fires only on real structural signals (never
+  # unstructured or tiny work), and every return is verified — so `on` cannot
+  # delegate frontier-priced or speculative work. `resolveShippedDefault()`
+  # remains the telemetry-driven DEMOTION gate: a measured regression demotes
+  # back to `ask`.
+  auto: on
 
   # Route delegable sub-tasks to the lowest-capable model tier (cost + speed
   # via model downshift). true (default) = downshift per declared model_tier;
@@ -695,6 +703,17 @@ memory:
   # Example: ["api[_-]?key", "/Users/[a-z]+/Library"]
   redact_patterns: []
 
+  # Opt-in compact memory index at session start
+  # (road-to-memory-retrieval-economy Phase 5). When `on`, session_start
+  # injects a compact index of curated entries — id + title + ~tokens,
+  # hard cap 30 rows — through the hot-context hook surface. Bodies are
+  # never injected; the model fetches full entries via memory_get on
+  # demand. Default OFF: the ship-criterion (measured hit-rate gain at
+  # bounded fixed cost) is unproven — off unless proven.
+  #   off = (default) no session-start index.
+  #   on  = inject the compact index (spotlighted as DATA).
+  session_index: "off"
+
 # --- Knowledge cards: global cross-project sharing (ADR-100) ---
 #
 # Structure-grounding v2. Promote *expensive* (remote) knowledge cards from

package/src/scripts/_dispatch.bash

@@ -167,6 +167,12 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   mcp:run                    Run the built-in MCP server over stdio
                              (requires `mcp:setup` first; see docs/mcp-server.md)
                              (experimental — beta gates: docs/contracts/mcp-beta-criteria.md)
+  affected                   Show artefacts related to <artefact> via the discovery
+                             relation-graph (relation-filtered BFS). Flags: --depth N
+  graph-explain              Seed on a <concept>, expand 2 hops over the discovery
+                             relation-graph with a node budget. Flags: --budget N
+  benchmark                  Report context-token reduction vs the full always-loaded
+                             projection (from the pinned token baseline). Flags: --format
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
   roadmap:archive            Archive completed roadmaps (branch-touched by default;
@@ -431,6 +437,24 @@ cmd_mcp_render() {
   exec_ts "$script" "$@"
 }
 
+cmd_affected() {
+  local script
+  script="$(resolve_script "src/scripts/discovery_graph.ts")"
+  exec_ts "$script" affected "$@"
+}
+
+cmd_graph_explain() {
+  local script
+  script="$(resolve_script "src/scripts/discovery_graph.ts")"
+  exec_ts "$script" explain "$@"
+}
+
+cmd_benchmark() {
+  local script
+  script="$(resolve_script "src/scripts/benchmark.ts")"
+  exec_ts "$script" "$@"
+}
+
 cmd_mcp_check() {
   local script
   script="$(resolve_script "src/scripts/mcp_render.ts")"
@@ -1031,6 +1055,9 @@ main() {
     mcp:setup)               cmd_mcp_setup "$@" ;;
     mcp:run)                 cmd_mcp_run "$@" ;;
     use)                     cmd_use "$@" ;;
+    affected)                cmd_affected "$@" ;;
+    graph-explain)           cmd_graph_explain "$@" ;;
+    benchmark)               cmd_benchmark "$@" ;;
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
     roadmap:archive)         cmd_roadmap_archive "$@" ;;

package/src/scripts/_lib/claude_builtin_names.ts

@@ -0,0 +1,148 @@
+// Claude Code built-in command / bundled-skill names — the reserved namespace.
+//
+// A user- or project-scope skill (or flat command) whose name equals a
+// built-in Claude Code slash command SHADOWS the built-in: typing `/mcp`
+// then opens the package's skill instead of Claude Code's MCP auth dialog
+// (observed 2026-07-10). The suite's contract is to complement the host,
+// never to overlay or degrade it — so no Claude-facing projection may claim
+// one of these names.
+//
+// Enforced at three layers:
+//   1. `condense.ts::generate_claude_commands` — project-scope `.claude/skills/`
+//      command entries skip reserved slugs.
+//   2. `install.ts::_apply_claude_flat_command_wrappers` — user-scope
+//      `~/.claude/` deploys neither a skill wrapper nor a flat command file
+//      for a reserved slug (nested `/cluster:sub` commands are unaffected —
+//      built-ins carry no `:`).
+//   3. `lint_agent_skill_names.ts` — a skill in `src/skills/` (or a domain
+//      pack) with a reserved name fails CI unless it opts out of slash
+//      registration with `user-invocable: false` (Claude may still load it
+//      automatically; the built-in keeps the `/name`).
+//
+// Source: https://code.claude.com/docs/en/commands (fetched 2026-07-10),
+// plus a small legacy set still present in older Claude Code versions.
+// Refresh trigger: a package artefact stops appearing in Claude Code, or a
+// release-notes entry adds a new built-in command.
+
+const _CURRENT = [
+    'add-dir',
+    'advisor',
+    'agents',
+    'autofix-pr',
+    'background',
+    'batch',
+    'branch',
+    'btw',
+    'cd',
+    'chrome',
+    'claude-api',
+    'clear',
+    'code-review',
+    'color',
+    'compact',
+    'config',
+    'context',
+    'copy',
+    'cost',
+    'dataviz',
+    'debug',
+    'deep-research',
+    'design-login',
+    'design-sync',
+    'desktop',
+    'diff',
+    'doctor',
+    'effort',
+    'exit',
+    'export',
+    'fast',
+    'feedback',
+    'fewer-permission-prompts',
+    'focus',
+    'fork',
+    'goal',
+    'heapdump',
+    'help',
+    'hooks',
+    'ide',
+    'init',
+    'insights',
+    'install-github-app',
+    'install-slack-app',
+    'keybindings',
+    'login',
+    'logout',
+    'loop',
+    'mcp',
+    'memory',
+    'mobile',
+    'model',
+    'passes',
+    'permissions',
+    'plan',
+    'plugin',
+    'powerup',
+    'pr-comments',
+    'privacy-settings',
+    'radio',
+    'recap',
+    'release-notes',
+    'reload-plugins',
+    'reload-skills',
+    'remote-control',
+    'remote-env',
+    'rename',
+    'resume',
+    'review',
+    'rewind',
+    'run',
+    'run-skill-generator',
+    'sandbox',
+    'schedule',
+    'scroll-speed',
+    'security-review',
+    'setup-bedrock',
+    'setup-vertex',
+    'simplify',
+    'skills',
+    'stats',
+    'status',
+    'statusline',
+    'stickers',
+    'teleport',
+    'thinking',
+    'trust',
+    'upgrade',
+    'usage',
+    'verify',
+    'vim',
+    'web',
+    'whats-new',
+    'workflow',
+    'workflows',
+    'worktree',
+] as const;
+
+// Retired from the current docs but still registered by older Claude Code
+// versions users may run — reserving them costs nothing (no package artefact
+// uses these names) and avoids version-dependent shadowing.
+const _LEGACY = [
+    'bashes',
+    'bug',
+    'migrate-installer',
+    'output-style',
+    'terminal-setup',
+    'theme',
+    'todos',
+] as const;
+
+/** Lowercase names a Claude-facing `/name` projection must never claim. */
+export const CLAUDE_CODE_BUILTIN_NAMES: ReadonlySet<string> = new Set<string>([
+    ..._CURRENT,
+    ..._LEGACY,
+]);
+
+/** True when `slug` would shadow a Claude Code built-in command or bundled skill. */
+export function is_claude_builtin_name(slug: string): boolean {
+    return CLAUDE_CODE_BUILTIN_NAMES.has(slug.toLowerCase());
+}

package/src/scripts/_lib/file_slicer.ts

@@ -0,0 +1,117 @@
+/**
+ * Deterministic document slicer for oversized knowledge ingest
+ * (road-to-retrieval-substrate-hardening B8).
+ *
+ * Splits a large markdown document into bounded slices at the cleanest
+ * available boundary — heading > paragraph (blank line) > line — while
+ * guaranteeing three invariants a downstream re-assembler can rely on:
+ *
+ *   1. GAP-FREE + NON-OVERLAPPING — slices cover contiguous line ranges over
+ *      the whole document, in order.
+ *   2. CONCAT == ORIGINAL — joining every slice's `text` in order reproduces
+ *      the input byte-for-byte (slices are exact offset ranges).
+ *   3. PARENTED — every slice carries its source `parentPath` (when given) and
+ *      its `[startLine, endLine)` range, so a chunk can point home.
+ *
+ * Deterministic: identical input + budget → identical slices.
+ */
+
+export interface Slice {
+    parentPath: string | null;
+    index: number;
+    startLine: number; // 0-based, inclusive
+    endLine: number; // 0-based, exclusive
+    text: string;
+}
+
+/** Default per-slice character budget. */
+export const DEFAULT_MAX_CHARS = 2000;
+
+function _lineStartOffsets(text: string): number[] {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === '\n') starts.push(i + 1);
+    }
+    return starts; // one entry per line; starts[k] = offset where line k begins
+}
+
+function _isHeading(line: string): boolean {
+    return /^#{1,6}\s/.test(line);
+}
+function _isBlank(line: string): boolean {
+    return line.trim() === '';
+}
+
+/**
+ * Slice `text` into ≤ `maxChars` pieces (best-effort — a single over-long line
+ * is emitted whole rather than split mid-line, preserving invariant 2).
+ * `parentPath` is stamped on every slice.
+ */
+export function sliceDocument(
+    text: string,
+    opts: { maxChars?: number; parentPath?: string } = {},
+): Slice[] {
+    const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
+    const parentPath = opts.parentPath ?? null;
+    if (text === '') return [];
+
+    const starts = _lineStartOffsets(text);
+    const nLines = starts.length;
+    // lineAt(k) = the raw text of line k INCLUDING its trailing newline (if any).
+    const lineEnd = (k: number): number => (k + 1 < nLines ? starts[k + 1]! : text.length);
+    const lines: string[] = [];
+    for (let k = 0; k < nLines; k++) lines.push(text.slice(starts[k]!, lineEnd(k)));
+
+    const slices: Slice[] = [];
+    let sliceStartLine = 0;
+    let idx = 0;
+    const flush = (endLine: number): void => {
+        if (endLine <= sliceStartLine) return;
+        const from = starts[sliceStartLine]!;
+        const to = endLine < nLines ? starts[endLine]! : text.length;
+        slices.push({ parentPath, index: idx++, startLine: sliceStartLine, endLine, text: text.slice(from, to) });
+        sliceStartLine = endLine;
+    };
+
+    let curChars = 0;
+    for (let k = 0; k < nLines; k++) {
+        const lineLen = lines[k]!.length;
+        const wouldExceed = curChars + lineLen > maxChars && k > sliceStartLine;
+        // Cut BEFORE a heading that opens a new section (clean boundary), or
+        // when the budget would overflow — preferring a preceding blank line.
+        const headingBoundary = _isHeading(lines[k]!) && k > sliceStartLine;
+        if (headingBoundary || wouldExceed) {
+            // Prefer to end the previous slice at the last blank line in-range,
+            // so a slice ends on a paragraph boundary when one is available.
+            let cut = k;
+            if (wouldExceed && !headingBoundary) {
+                for (let b = k - 1; b > sliceStartLine; b--) {
+                    if (_isBlank(lines[b]!)) {
+                        cut = b + 1;
+                        break;
+                    }
+                }
+            }
+            flush(cut);
+            curChars = 0;
+            for (let j = sliceStartLine; j <= k; j++) curChars += lines[j]!.length;
+        } else {
+            curChars += lineLen;
+        }
+    }
+    flush(nLines);
+    return slices;
+}
+
+/** True iff the slices reproduce `text` exactly, gap-free and non-overlapping. */
+export function verifySlices(text: string, slices: readonly Slice[]): boolean {
+    if (slices.length === 0) return text === '';
+    let expectedLine = 0;
+    const parts: string[] = [];
+    for (const s of slices) {
+        if (s.startLine !== expectedLine) return false; // gap or overlap
+        expectedLine = s.endLine;
+        parts.push(s.text);
+    }
+    return parts.join('') === text;
+}

package/src/scripts/_lib/lexical_index.ts

@@ -0,0 +1,155 @@
+/**
+ * Hand-rolled, dependency-free lexical index for memory/knowledge retrieval
+ * (road-to-retrieval-substrate-hardening B2).
+ *
+ * The current `memory_lookup._score` gives every keyword match the SAME coarse
+ * bucket (0.8 glob / 0.6 substring), so several entries tie at the top and
+ * retrieval "recalls but does not rank" (the mean-tie-set 3.3 finding from
+ * road-to-second-brain-retrieval-precision). This module replaces that bucket
+ * with a continuous BM25 score over an IDF-weighted term index, plus a
+ * character-trigram candidate prefilter so it stays cheap at corpus scale.
+ *
+ * It is the BM25 core ADR-061 already sanctions — pure Node stdlib, NO engine
+ * fork, NO minisearch-class dependency. `_score` stays as the below-tripwire
+ * mini-corpus fallback; this index activates at the `lint_knowledge_scale`
+ * tripwire. Deterministic: identical docs + query → identical scores + order.
+ */
+
+/** BM25 term-frequency saturation. */
+export const BM25_K1 = 1.5;
+/** BM25 length-normalisation strength. */
+export const BM25_B = 0.75;
+/** Minimum token length kept (drops single chars / punctuation noise). */
+export const MIN_TOKEN_LEN = 2;
+
+export interface IndexDoc {
+    id: string;
+    /** All searchable text of the entry, already concatenated. */
+    text: string;
+}
+
+interface DocStats {
+    id: string;
+    len: number; // token count
+    tf: Map<string, number>; // term → frequency in this doc
+    trigrams: Set<string>;
+}
+
+/** Lowercase, split on non-alphanumeric, keep tokens ≥ MIN_TOKEN_LEN. */
+export function tokenize(s: string): string[] {
+    const out: string[] = [];
+    for (const raw of s.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (raw.length >= MIN_TOKEN_LEN) out.push(raw);
+    }
+    return out;
+}
+
+/** Character trigrams of a normalised string (alphanumerics + single spaces). */
+export function trigrams(s: string): Set<string> {
+    const norm = s.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+    const out = new Set<string>();
+    if (norm.length < 3) {
+        if (norm.length > 0) out.add(norm);
+        return out;
+    }
+    for (let i = 0; i + 3 <= norm.length; i++) {
+        out.add(norm.slice(i, i + 3));
+    }
+    return out;
+}
+
+/**
+ * An in-memory BM25 index over a fixed document set. Built once, queried many
+ * times. Stateless after construction — `rank()` / `score()` never mutate it,
+ * so a cached instance is safe to reuse until the underlying corpus changes.
+ */
+export class LexicalIndex {
+    private readonly docs: Map<string, DocStats> = new Map();
+    private readonly df: Map<string, number> = new Map();
+    private readonly n: number;
+    private readonly avgdl: number;
+
+    constructor(documents: readonly IndexDoc[]) {
+        let totalLen = 0;
+        for (const d of documents) {
+            const tokens = tokenize(d.text);
+            const tf = new Map<string, number>();
+            for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
+            for (const t of tf.keys()) this.df.set(t, (this.df.get(t) ?? 0) + 1);
+            this.docs.set(d.id, { id: d.id, len: tokens.length, tf, trigrams: trigrams(d.text) });
+            totalLen += tokens.length;
+        }
+        this.n = documents.length;
+        this.avgdl = this.n > 0 ? totalLen / this.n : 0;
+    }
+
+    /** Robertson–Spärck-Jones IDF, floored at 0 so common terms never subtract. */
+    private idf(term: string): number {
+        const df = this.df.get(term) ?? 0;
+        if (df === 0) return 0;
+        return Math.max(0, Math.log(1 + (this.n - df + 0.5) / (df + 0.5)));
+    }
+
+    /** BM25 score of one document against the tokenised query terms. */
+    score(queryTerms: readonly string[], docId: string): number {
+        const doc = this.docs.get(docId);
+        if (doc === undefined || doc.len === 0) return 0;
+        let s = 0;
+        for (const term of queryTerms) {
+            const tf = doc.tf.get(term);
+            if (tf === undefined) continue;
+            const idf = this.idf(term);
+            if (idf === 0) continue;
+            const denom = tf + BM25_K1 * (1 - BM25_B + (BM25_B * doc.len) / (this.avgdl || 1));
+            s += (idf * (tf * (BM25_K1 + 1))) / denom;
+        }
+        return s;
+    }
+
+    /**
+     * Rank documents for a set of query keys (phrases are tokenised). A
+     * character-trigram prefilter selects candidates cheaply; the guard keeps
+     * any doc sharing a query TOKEN even when no trigram overlaps, so the
+     * prefilter never drops a genuine lexical match. Ties break by id for a
+     * stable, deterministic order.
+     */
+    rank(queryKeys: readonly string[]): Array<{ id: string; score: number }> {
+        const queryText = queryKeys.join(' ');
+        const qTerms = tokenize(queryText);
+        const qTermSet = new Set(qTerms);
+        const qTrigrams = trigrams(queryText);
+
+        const candidates: string[] = [];
+        for (const [id, doc] of this.docs) {
+            let hit = false;
+            for (const t of qTrigrams) {
+                if (doc.trigrams.has(t)) {
+                    hit = true;
+                    break;
+                }
+            }
+            if (!hit) {
+                // Guard: keep a doc that shares an exact query token even with
+                // no trigram overlap (short tokens / edge normalisation).
+                for (const t of qTermSet) {
+                    if (doc.tf.has(t)) {
+                        hit = true;
+                        break;
+                    }
+                }
+            }
+            if (hit) candidates.push(id);
+        }
+
+        const scored = candidates
+            .map((id) => ({ id, score: this.score(qTerms, id) }))
+            .filter((r) => r.score > 0);
+        scored.sort((a, b) => (b.score - a.score) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        return scored;
+    }
+
+    /** Document count — for the caller's tripwire / diagnostics. */
+    get size(): number {
+        return this.n;
+    }
+}

package/src/scripts/_lib/orchestration_gate.ts

@@ -1,15 +1,19 @@
 /**
- * Default-flip decision gate (Phase 6).
+ * Default-flip / demotion decision gate (Phase 6 → telemetry-demotion).
  *
- * Pure, no-I/O. Encodes the Phase-6 falsification gate: the SHIPPED default for
- * `subagents.auto` flips toward `on` ONLY when a real benchmark shows a net
- * token-or-time win at held quality, and only on hosts with a subagent
- * primitive. Honest-null exit (no win, or quality regressed) keeps the
- * conservative default. Contract:
+ * Pure, no-I/O. Originally the Phase-6 falsification gate: the SHIPPED default
+ * for `subagents.auto` was to flip toward `on` ONLY on a passed benchmark.
+ *
+ * As of 2026-07-09 the shipped default IS `on` on subagent-capable hosts
+ * (ADR-117; agents/settings/contexts/orchestration-default-flip-verdict.md
+ * § 2026-07-09) — flipped on a bounded-downside re-evaluation, not a passed
+ * benchmark. This helper is therefore now the telemetry-driven DEMOTION gate:
+ * a `fail` verdict from accumulated real-world orchestration telemetry demotes
+ * the default back to `ask` (conservative). Contract:
  * `src/agent-src/contexts/execution/orchestration-benchmark-gate.md`.
  *
- * This helper decides; it never runs the benchmark. The measurement is the
- * empirical bench:ab step, authorised + run out of band.
+ * This helper decides; it never runs the measurement. The signal is realized
+ * orchestration telemetry, aggregated + evaluated out of band.
  */
 
 export interface BenchmarkResult {