@event4u/agent-config 8.8.0 → 8.9.0

package/src/scripts/benchmark.ts

@@ -0,0 +1,122 @@
+#!/usr/bin/env tsx
+/**
+ * `agent-config benchmark` — self-measuring token-reduction report
+ * (road-to-retrieval-substrate-hardening B7a).
+ *
+ * Reports the context-token reduction of the retrieval economy against the
+ * REAL alternative: the FULL always-loaded projection (council Q4) — the
+ * honest "what the user pays if everything loads eagerly + full descriptions".
+ * NOT a synthetic full-corpus strawman (explicitly rejected).
+ *
+ * Baseline components (from the pinned internal/bench/reports/token-baseline.json):
+ *   eager_rule_load + skill_descriptions + command_descriptions + mcp_schemas
+ * Reduced: eager→thin rule projection, descriptions/schemas unchanged.
+ *
+ * Deterministic (reads the pinned baseline). Every emitted number binds to
+ * docs/CLAIMS.md with a method line (council Q4 hard condition).
+ *
+ * Usage: benchmark.ts [--baseline PATH] [--format text|json]
+ * Exit codes: 0 ok, 1 baseline missing/malformed, 2 usage error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const PROG = 'benchmark.ts';
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+export const BASELINE = path.join(REPO_ROOT, 'internal', 'bench', 'reports', 'token-baseline.json');
+
+interface Metrics {
+    eager_rule_load: number;
+    thin_rule_load: number;
+    skill_descriptions: number;
+    command_descriptions: number;
+    mcp_schemas: number;
+}
+export interface BenchmarkReport {
+    baseline_full_projection: number;
+    reduced_projection: number;
+    saved: number;
+    reduction_ratio: number; // 0..1
+    method: string;
+    components: Metrics;
+}
+
+function _num(v: unknown): number {
+    return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+
+/** Compute the reduction report from a token-baseline metrics object. */
+export function computeReport(metrics: Metrics): BenchmarkReport {
+    const shared = metrics.skill_descriptions + metrics.command_descriptions + metrics.mcp_schemas;
+    const full = metrics.eager_rule_load + shared;
+    const reduced = metrics.thin_rule_load + shared;
+    const saved = full - reduced;
+    const ratio = full > 0 ? Math.round((saved / full) * 10000) / 10000 : 0;
+    return {
+        baseline_full_projection: full,
+        reduced_projection: reduced,
+        saved,
+        reduction_ratio: ratio,
+        method:
+            'Baseline = FULL always-loaded projection (eager rule load + skill/command ' +
+            'descriptions + MCP schemas) from token-baseline.json; reduced = thin rule ' +
+            'projection, shared surfaces unchanged. Not a synthetic strawman (council Q4).',
+        components: metrics,
+    };
+}
+
+export function loadMetrics(baselinePath: string): Metrics {
+    const parsed = JSON.parse(fs.readFileSync(baselinePath, 'utf-8')) as { metrics?: Record<string, unknown> };
+    const m = parsed.metrics ?? {};
+    return {
+        eager_rule_load: _num(m['eager_rule_load']),
+        thin_rule_load: _num(m['thin_rule_load']),
+        skill_descriptions: _num(m['skill_descriptions']),
+        command_descriptions: _num(m['command_descriptions']),
+        mcp_schemas: _num(m['mcp_schemas']),
+    };
+}
+
+export function main(argv: string[]): number {
+    let baselinePath = BASELINE;
+    let format: 'text' | 'json' = 'text';
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (a === '--baseline') baselinePath = argv[++i] ?? baselinePath;
+        else if (a === '--format') format = (argv[++i] as 'text' | 'json') ?? 'text';
+        else if (a === '-h' || a === '--help') {
+            process.stdout.write(`usage: ${PROG} [--baseline PATH] [--format text|json]\n`);
+            return 0;
+        } else {
+            process.stderr.write(`${PROG}: error: unknown argument ${a}\n`);
+            return 2;
+        }
+    }
+    let report: BenchmarkReport;
+    try {
+        report = computeReport(loadMetrics(baselinePath));
+    } catch (exc) {
+        process.stderr.write(`${PROG}: cannot read baseline ${baselinePath}: ${String(exc)}\n`);
+        return 1;
+    }
+    if (format === 'json') {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+        return 0;
+    }
+    const pct = (report.reduction_ratio * 100).toFixed(1);
+    process.stdout.write(
+        `context token reduction (vs full always-loaded projection):\n` +
+            `  full projection   ${report.baseline_full_projection} tokens\n` +
+            `  reduced (thin)    ${report.reduced_projection} tokens\n` +
+            `  saved             ${report.saved} tokens (${pct}%)\n` +
+            `  method            ${report.method}\n`,
+    );
+    return 0;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/build_proof.ts

@@ -26,6 +26,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { REPO, LEDGER_REL, load_ledger, pointer_unresolved } from './check_claims.js';
 import { collectSkillGaps } from './check_skill_gaps.js';
 import { loadRows as loadComparisonRows } from './check_comparison.js';
+import { computeStatus as domainSoundnessStatus } from './domain_soundness_status.js';
 
 const _FILE = fileURLToPath(import.meta.url);
 const OUT_REL = 'docs/proof.md';
@@ -118,30 +119,42 @@ function render(): string {
     L.push('checks the wrong property is worse than none), so the number grows');
     L.push('deliberately, not overnight.');
     L.push('');
+    const ds = domainSoundnessStatus();
     L.push('**Non-coding domain soundness — scoped, not proven.** The `finance` /');
     L.push('`founder` / `ops` / `content` profiles sell concrete domain value (DCF,');
     L.push('runway, RICE, incident command, messaging), but the skills are forged on');
     L.push('TS/PHP — "promising, not proven" off those stacks. A disclaimer floor');
     L.push('bounds *liability*, not *correctness*: a skill can be format-correct,');
-    L.push('disclaimered, and still embed a wrong domain assumption. Today **0 of 20**');
+    L.push(`disclaimered, and still embed a wrong domain assumption. Today **${ds.validated} of ${ds.total}**`);
     L.push('default-surface domain skills carry a sourced `domain-truth` fixture');
-    L.push('(`./scripts-run src/scripts/domain_soundness_status`); all are labeled');
-    L.push('`unvalidated` and the validated count is CI-ratcheted. Authoring the');
-    L.push('answer keys needs domain competence (a cited method, not the skill\'s own');
-    L.push('output), so validation lands deliberately — the gap is published, never');
-    L.push('implied away.');
+    L.push('(`./scripts-run src/scripts/domain_soundness_status`); the rest are labeled');
+    L.push('`unvalidated` and the validated count is CI-ratcheted. The fixtures landed');
+    L.push('so far are the **deterministic** targets (runway, unit-economics, DCF,');
+    L.push('forecasting, scenario band/sensitivity), whose answer keys are computed');
+    L.push('from cited standard formulas — never the skill\'s own output; the');
+    L.push('**rubric** targets (incident command, messaging, fundraising, editorial)');
+    L.push('need domain-competent grounding and remain unvalidated, so validation');
+    L.push('lands deliberately — the gap is published, never implied away.');
     L.push('');
-    L.push('**Second-brain substrate — continuity convenience, task-lift unmeasured.**');
-    L.push('The memory substrate is built (working-memory continuity across');
-    L.push('compaction, promotable knowledge cards, contradiction surfacing), but');
-    L.push('whether it beats a no-memory baseline on a reproducible task is **not yet');
-    L.push('measured**. The measurement rig exists — a deterministic multi-session');
-    L.push('recall corpus + scorer (`./scripts-run src/scripts/second_brain_score');
-    L.push('--dry-run`, no model-in-the-loop grading) — but the paired');
-    L.push('`memory-on`/`off`/`placebo` run is spend-bearing and pending. So no');
-    L.push('"second brain" capability claim is made anywhere; the substrate ships as');
-    L.push('continuity convenience until a paired run backs a lift. Boundary vs a');
-    L.push('human PKM is stated in [`docs/second-brain-scope.md`](second-brain-scope.md).');
+    L.push('**Second-brain substrate — measured recall lift, honestly bounded.** On a');
+    L.push('deterministic multi-session recall corpus, the memory substrate beats a');
+    L.push('no-memory baseline AND an equal-byte placebo: memory-on **27/27** vs');
+    L.push('no-memory **10/27** vs placebo **9/27** (claude-haiku-4-5, 9 tasks × 3');
+    L.push('seeds, sign test **p = 0.031** for both pairings) — a real,');
+    L.push('placebo-controlled lift (`internal/bench/reports/second-brain-delta.json`).');
+    L.push('Scoped, not oversold: this is the context-value upper bound (perfect');
+    L.push('retrieval on a one-fact-per-task corpus), NOT retrieval precision under a');
+    L.push('large store; the lift concentrates exactly where memory is the only source');
+    L.push('and ties where the prompt self-contains the fact. Boundary vs a human PKM,');
+    L.push('and why the Obsidian export stays declined, are in');
+    L.push('[`docs/second-brain-scope.md`](second-brain-scope.md).');
+    L.push('');
+    L.push('A follow-up removed the perfect-retrieval assumption: against a store of');
+    L.push('keyword-overlapping confusers the REAL retrieval recalls the needed');
+    L.push('decision into the top-5 (9/9) and the model disambiguates it — retrieval-on');
+    L.push('**27/27** vs no-memory **5/27** and vs placebo **5/27** (p=0.008 both). The');
+    L.push('honest limit: the keyword scorer recalls but does not rank (mean tie-set');
+    L.push('3.3), which is the SQLite-FTS5 activation signal (ADR-116) at scale.');
     L.push('');
     L.push('## 3. Known limits (published, witness-tested)');
     L.push('');

package/src/scripts/check_memory.ts

@@ -81,7 +81,9 @@ const CRITICAL_WARN_THRESHOLD = 10;
 const CRITICAL_STALE_DAYS = 90;
 const KNOWN_TYPES: ReadonlySet<string> = new Set([
     'domain-invariants',
+    'historical-patterns',
     'incident-learnings',
+    'ownership',
     'product-rules',
 ]);
 

package/src/scripts/check_quality_regression.ts

@@ -108,6 +108,57 @@ export function evaluatePair(
   return { id: task.id, winner, length_delta, winner_is_longer };
 }
 
+/**
+ * Cohen's Kappa — chance-corrected agreement between two raters over the same
+ * categorical labels (road-to-retrieval-substrate-hardening B7b). 1 = perfect,
+ * 0 = chance-level, <0 = worse than chance. `NaN` when there is no data.
+ */
+export function cohensKappa(labelsA: readonly string[], labelsB: readonly string[]): number {
+  const n = Math.min(labelsA.length, labelsB.length);
+  if (n === 0) return Number.NaN;
+  const cats = new Set<string>();
+  for (let i = 0; i < n; i++) {
+    cats.add(labelsA[i] as string);
+    cats.add(labelsB[i] as string);
+  }
+  let observedAgree = 0;
+  const countA = new Map<string, number>();
+  const countB = new Map<string, number>();
+  for (let i = 0; i < n; i++) {
+    const a = labelsA[i] as string;
+    const b = labelsB[i] as string;
+    if (a === b) observedAgree += 1;
+    countA.set(a, (countA.get(a) ?? 0) + 1);
+    countB.set(b, (countB.get(b) ?? 0) + 1);
+  }
+  const po = observedAgree / n;
+  let pe = 0;
+  for (const c of cats) pe += ((countA.get(c) ?? 0) / n) * ((countB.get(c) ?? 0) / n);
+  if (pe === 1) return 1; // both raters unanimous on one label → perfect by convention
+  return Math.round(((po - pe) / (1 - pe)) * 10000) / 10000;
+}
+
+/**
+ * Second-independent-judge validation: Cohen's Kappa over the two judges'
+ * per-pair winner labels (aligned by task id). A LOW kappa means the win-rate
+ * verdict rests on an unreliable grader — the trustworthiness gap the
+ * token-saving live run surfaced (33% judge-inconsistency), distinct from the
+ * effect-significance the Wilcoxon/McNemar gates already test.
+ */
+export function judgeKappa(resultsA: readonly PairResult[], resultsB: readonly PairResult[]): number {
+  const byIdB = new Map(resultsB.map((r) => [r.id, r.winner]));
+  const a: string[] = [];
+  const b: string[] = [];
+  for (const r of resultsA) {
+    const bw = byIdB.get(r.id);
+    if (bw !== undefined) {
+      a.push(r.winner);
+      b.push(bw);
+    }
+  }
+  return cohensKappa(a, b);
+}
+
 export interface QualityAggregate {
   total: number;
   thin_wins: number;

package/src/scripts/check_roadmap_trackable.ts

@@ -37,10 +37,11 @@ const ROADMAP_ROOT = 'agents/roadmaps';
 // CHECKBOX_RE = re.compile(r"^\s*[-*]\s+\[([ xX~\-])\]\s", re.MULTILINE)
 const CHECKBOX_RE = /^[ \t]*[-*][ \t]+\[([ xX~\-])\][ \t\f\v]/m;
 // PHASE_RE = re.compile(
-//   r"^(#{2,3})\s+Phase\s+(\d+[a-z]?|[IVX]+|[A-Z](?:\d+)?)"
+//   r"^(#{2,3})\s+Phase\s+(\d+(?:\.\d+)*[a-z]?|[IVX]+|[A-Z](?:\d+)?)"
 //   r"(?:[\s:—\-]+(.*?))?\s*$", re.MULTILINE)
+// Numeric ids accept dotted sub-phases ("1.0", "4.1") — mirrors the dashboard's PHASE_RE.
 const PHASE_RE =
-    /^(#{2,3})[ \t\f\v]+Phase[ \t\f\v]+(\d+[a-z]?|[IVX]+|[A-Z](?:\d+)?)(?:[\s:—\-]+(.*?))?[ \t\f\v]*$/gm;
+    /^(#{2,3})[ \t\f\v]+Phase[ \t\f\v]+(\d+(?:\.\d+)*[a-z]?|[IVX]+|[A-Z](?:\d+)?)(?:[\s:—\-]+(.*?))?[ \t\f\v]*$/gm;
 // FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\s*\n", re.DOTALL)
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\s*\n/;
 const DRAFT_VALUES: ReadonlySet<string> = new Set(['draft']);

package/src/scripts/condense.ts

@@ -40,6 +40,7 @@ import {
     strip_source_prefix,
 } from './_lib/agent_src.js';
 import { build_claude_hook_matrix } from './_lib/claude_settings_hooks.js';
+import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 import { project_settings_path, load_agent_settings } from './_lib/agent_settings.js';
 import { info, success, flush_summary, resolve_level } from './_lib/script_output.js';
 import {
@@ -1529,6 +1530,7 @@ export function generate_claude_commands(active_command_slugs: ReadonlySet<strin
     const current_slugs = new Set<string>();
     let count = 0;
     let skipped = 0;
+    let reserved = 0;
     let rendered = 0;
     const auto = _read_model_auto_switch() === 'auto';
     for (const [source_file, slug] of iterCommands()) {
@@ -1539,6 +1541,15 @@ export function generate_claude_commands(active_command_slugs: ReadonlySet<strin
             skipped += 1;
             continue;
         }
+        // Never claim a `/name` that is a Claude Code built-in command or
+        // bundled skill — a same-name entry shadows the built-in (e.g. a
+        // `review` entry hides Claude Code's own /review). Nested
+        // `/cluster:sub` slugs are hyphen-joined and cannot collide.
+        // See src/scripts/_lib/claude_builtin_names.ts.
+        if (is_claude_builtin_name(slug)) {
+            reserved += 1;
+            continue;
+        }
         current_slugs.add(slug);
 
         const skill_dir = path.join(MODULE_STATE.CLAUDE_SKILLS_DIR, slug);
@@ -1588,6 +1599,9 @@ export function generate_claude_commands(active_command_slugs: ReadonlySet<strin
     if (skipped) {
         msg += ` (${skipped} skipped — same-name skill exists)`;
     }
+    if (reserved) {
+        msg += ` (${reserved} withheld — Claude Code built-in name)`;
+    }
     if (removed_dirs) {
         msg += ` (${removed_dirs} stale dirs removed)`;
     }

package/src/scripts/external_sources_denylist.json

@@ -54,7 +54,10 @@
     "gztchan",
     "amaancoderx",
     "npxskillui",
-    "\\bskillui\\b"
+    "\\bskillui\\b",
+    "\\bgraphify\\b",
+    "graphify-labs",
+    "penpax"
   ],
   "skip_paths": [
     "src/scripts/check_no_external_sources.py",

package/src/scripts/generate_index.ts

@@ -24,6 +24,7 @@ import {
     iter_commands,
     strip_source_prefix,
 } from './_lib/agent_src.js';
+import { computeStatus as domainSoundnessStatus } from './domain_soundness_status.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -398,6 +399,7 @@ export function _render_catalog(
     const publicRules = rules.filter((r) => !INTERNAL_RULES.has(r.name));
     const publicCommands = commands.filter((c) => c.kind === 'command');
     const total = skills.length + publicRules.length + publicCommands.length + guidelines.length;
+    const ds = domainSoundnessStatus();
     const parts = [
         '# agent-config — Public Catalog',
         '',
@@ -419,8 +421,9 @@ export function _render_catalog(
         '',
         '> **Non-coding domain correctness is scoped, not proven.** The',
         '> `finance` / `founder` / `ops` / `content` skills are forged on TS/PHP',
-        '> codebases; their embedded domain heuristics are labeled `unvalidated`',
-        '> until they pass a sourced `evals/domain-truth.json` fixture',
+        `> codebases; ${ds.validated} of ${ds.total} default-surface domain skills carry a sourced`,
+        '> `evals/domain-truth.json` fixture (deterministic targets, keys from',
+        '> cited formulas); the rest are labeled `unvalidated` until they pass one',
         '> (`./scripts-run src/scripts/domain_soundness_status`). A disclaimer',
         '> floor bounds liability, not correctness — see [the proof page](proof.md).',
         '',

package/src/scripts/install-hooks.sh

@@ -42,6 +42,31 @@ if ! ./scripts-run src/scripts/check_no_conflict_markers --quiet; then
     fail=1
 fi
 
+# Changed-files static pass (typecheck + lint) — the deterministic backstop to
+# the behavioural verify-before-complete rule (#818). Catches the compile/lint
+# errors that reach remote CI "Static Checks" (e.g. TS18048). Runs only when
+# the push touches .ts, so docs-only pushes stay fast. Skip a genuine WIP push
+# with AGENT_CONFIG_SKIP_PREPUSH_STATIC=1 (the agent cannot use --no-verify).
+echo "🔍 Static check on changed TypeScript (typecheck + lint)..."
+if [ "${AGENT_CONFIG_SKIP_PREPUSH_STATIC:-}" = "1" ]; then
+    echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_STATIC=1"
+else
+    base="$(git merge-base HEAD origin/main 2>/dev/null || echo HEAD~1)"
+    changed_ts="$(git diff --name-only --diff-filter=d "$base"...HEAD -- '*.ts' 2>/dev/null || true)"
+    if [ -n "$changed_ts" ]; then
+        if ! npx eslint $changed_ts; then
+            echo "❌  ESLint failed on changed TypeScript. Fix before pushing (or AGENT_CONFIG_SKIP_PREPUSH_STATIC=1 for a WIP push)."
+            fail=1
+        fi
+        if ! npm run --silent typecheck; then
+            echo "❌  Typecheck (tsc) failed — this is the class of error remote CI 'Static Checks' catches (#818). Fix before pushing."
+            fail=1
+        fi
+    else
+        echo "⏭️  no changed .ts vs origin/main — skipping."
+    fi
+fi
+
 if [ $fail -ne 0 ]; then
     echo ""
     echo "   Push blocked — fix the failures above and re-push."

package/src/scripts/install.ts

@@ -72,6 +72,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import type * as YamlModule from 'yaml';
 
 import { build_merge_entries } from './_lib/json_pointers.js';
+import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 import * as installed_lock from './_lib/installed_lock.js';
 import * as surface_tiers from './_lib/surface_tiers.js';
 import * as global_deploy_inventory from './_lib/global_deploy_inventory.js';
@@ -2847,15 +2848,40 @@ function _deploy_claude_desktop(
  * discovery (revert = one package release, no per-machine gating).
  * Tier-2/internal flat commands stay command files. A command whose name
  * collides with a real skill is skipped (the skill already owns `/name`).
+ *
+ * Reserved-name floor: a flat `/name` that equals a Claude Code BUILT-IN
+ * command or bundled skill (see `_lib/claude_builtin_names.ts`) would shadow
+ * the built-in — e.g. a `review` wrapper hides Claude Code's own `/review`.
+ * Such slugs get NEITHER a skill wrapper NOR a flat command file on this
+ * anchor (their nested `/cluster:sub` commands are untouched); the flat file
+ * is removed so a future upstream flat-discovery fix cannot resurrect the
+ * shadowing. The suite complements the host — it never overlays built-ins.
  */
 const _CLAUDE_FLAT_WRAPPER_EXTRA = new Set(['commit']); // essential; absent from the manifest
 export function _apply_claude_flat_command_wrappers(
     anchor: string,
     package_root: string,
     current_files: Set<string>,
-): { wrapped: string[]; collisions: string[] } {
+): { wrapped: string[]; collisions: string[]; reserved: string[] } {
     const wrapped: string[] = [];
     const collisions: string[] = [];
+    const reserved: string[] = [];
+    // Reserved-name sweep over ALL flat command files (any tier): a name
+    // shadowing a Claude Code built-in never ships on the claude-code anchor.
+    const commands_dir = path.join(anchor, 'commands');
+    let flat_entries: string[] = [];
+    try {
+        flat_entries = fs.readdirSync(commands_dir).filter((f) => f.endsWith('.md'));
+    } catch {
+        // No commands dir → nothing to sweep.
+    }
+    for (const fname of flat_entries.sort()) {
+        const slug = fname.slice(0, -'.md'.length);
+        if (!is_claude_builtin_name(slug)) continue;
+        fs.rmSync(path.join(commands_dir, fname), { force: true });
+        current_files.delete(`commands/${fname}`);
+        reserved.push(slug);
+    }
     // Tier-0/1 visible command slugs from the locked discovery manifest.
     const eligible = new Set<string>(_CLAUDE_FLAT_WRAPPER_EXTRA);
     try {
@@ -2892,7 +2918,7 @@ export function _apply_claude_flat_command_wrappers(
         current_files.add(`skills/${slug}/SKILL.md`);
         wrapped.push(slug);
     }
-    return { wrapped, collisions };
+    return { wrapped, collisions, reserved };
 }
 
 function _deploy_global_content(
@@ -2949,6 +2975,13 @@ function _deploy_global_content(
                         'skill wrappers (Claude Code flat-command discovery workaround)',
                 );
             }
+            if (res.reserved.length > 0 && !state.QUIET) {
+                info(
+                    `  claude-code: ${res.reserved.length} flat command(s) withheld — name is a ` +
+                        `Claude Code built-in (${res.reserved.join(', ')}); nested /cluster:sub ` +
+                        'commands remain available',
+                );
+            }
         }
 
         const missing_targets = _verify_deploy_targets(anchor, plan);

package/src/scripts/lint_agent_skill_names.ts

@@ -14,6 +14,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { command_slug } from './_lib/agent_src.js';
+import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 
 const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.dirname(path.dirname(SCRIPTS_DIR));
@@ -97,6 +98,18 @@ function frontmatterNameFromFile(p: string): string | null {
     return _frontmatter_name(fs.readFileSync(p, 'utf-8'));
 }
 
+const USER_INVOCABLE_FALSE_RE = /^user-invocable:\s*false\s*$/m;
+
+/** True when the SKILL.md opts out of slash registration (`user-invocable: false`). */
+export function _opts_out_of_slash(text: string): boolean {
+    if (!text.startsWith('---')) {
+        return false;
+    }
+    const end = text.indexOf('\n---', 3);
+    const block = end !== -1 ? text.slice(3, end) : text;
+    return USER_INVOCABLE_FALSE_RE.test(block);
+}
+
 export function _spec_violation(name: string): string | null {
     if (name.length > MAX_NAME_LEN) {
         return `longer than ${MAX_NAME_LEN} chars`;
@@ -178,6 +191,22 @@ export function check_skills(): string[] {
                     'requires the folder name to match the `name:` field',
             );
         }
+        // Reserved-name floor: a skill named after a Claude Code built-in
+        // command / bundled skill shadows the built-in when projected as
+        // `/name` (e.g. a `mcp` skill hides Claude Code's own /mcp dialog).
+        // Opting out of slash registration (`user-invocable: false`) keeps
+        // the skill model-loadable while the host retains the /name.
+        // Reserved set: src/scripts/_lib/claude_builtin_names.ts.
+        if (
+            is_claude_builtin_name(dirname) &&
+            !_opts_out_of_slash(fs.readFileSync(md, 'utf-8'))
+        ) {
+            violations.push(
+                `${rel}: \`${dirname}\` is a Claude Code built-in command name — ` +
+                    'add `user-invocable: false` (model-only invocation) or rename ' +
+                    'the skill; the suite must never shadow a host built-in',
+            );
+        }
     }
     return violations;
 }

package/src/scripts/lint_knowledge_scale.ts

@@ -14,9 +14,10 @@
  *   - sessions scale   — `agents/knowledge/sessions/` > 50 pages
  *                        → design fold-through-consolidate-gate for tracked pages
  *   - type scale       — any single memory/knowledge type > 200 files
- *                        → build the pre-decided file-first in-memory BM25 CLI
+ *                        → rank via `_lib/lexical_index.ts` (hand-rolled BM25 +
+ *                          trigram, no engine fork / no FTS5; ADR-061 honoured)
  *   - corpus scale     — > 500 files across all types
- *                        → same BM25 activation path
+ *                        → same lexical-index activation path
  *   - hot-context size — `agents/runtime/state/hot-context.md` > 600 tokens
  *                        (estimated at 4 chars/token) → trim schema / fix the
  *                        deterministic writer
@@ -151,7 +152,7 @@ export function runChecks(root: string): Warning[] {
                 metric: `${n}/${TYPE_FILES_MAX}`,
                 message:
                     `type '${type}' holds ${n} files (> ${TYPE_FILES_MAX}). ` +
-                    'Activation path (pre-decided): build the file-first in-memory BM25 CLI (re-index at session start, no vectors, no service).',
+                    'Activation path (resolved, road-to-retrieval-substrate-hardening B2): rank via the hand-rolled BM25 + trigram index in `_lib/lexical_index.ts` (pure stdlib, NO engine fork / NO SQLite-FTS5, ADR-061 honoured). Measured lift: mean tie-set 3.333 → 1.0 (internal/bench/reports/lexical-ranking.json). Wire it lazily at first lookup + a stat-index, no vectors, no service.',
             });
         }
     }