@event4u/agent-config 8.8.0 → 8.9.0

package/docs/proof.md

@@ -28,18 +28,22 @@ evidence pointer, or `task check-claims` fails the build.
 |---|---|---|---|
 | The release process is documented as an inheritable runbook + succession doc, and the project's bus-factor (trailing-90-day distinct human reviewers) is tracked and reported truthfully — currently 1, not implied to be more. | qual | `docs/succession.md#trailing 90 days` | ✅ |
 | 172 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| The retrieval economy cuts always-loaded context tokens ~65.6% measured against the FULL always-loaded projection — 98,529 → 33,897 tokens (eager rule load + skill/command descriptions + MCP schemas, thin-flipped). Method: `agent-config benchmark` over the pinned token baseline; the baseline is the honest "what the user pays if everything loads eagerly", NOT a synthetic full-corpus strawman (council Q4). | quant | `internal/bench/reports/token-baseline.json#eager_rule_load` | ✅ |
 | On a weak host (claude-haiku-4-5) the package produces a significant, placebo-controlled discipline lift on scope/downstream traps; on a strong host the same measurement is a published null — the package transplants discipline a weak model lacks, not model intelligence. | quant | `docs/benchmark.md#weak-host-specific` | ✅ |
 | The non-coding domain skills (finance/founder/ops/content) are forged on TS/PHP and labeled unvalidated until they pass a sourced domain-truth fixture; no public prose implies proven domain correctness, and the validated count is CI-ratcheted. | qual | `src/scripts/domain_soundness_status.ts#checkRatchet` | ✅ |
 | On the READ-ONLY FAN-OUT slice family, tier-downshifted subagent dispatch (lite/haiku vs session-tier-proxy sonnet) nets a ≥30% USD-weighted token-cost reduction at held quality — measured 2026-07-08 (n=10 paired live dispatches, 20 telemetry lines): 10/10 exact-match on BOTH arms, 29.4% fewer raw tokens, 76.5% USD-weighted cost reduction at the 3x haiku↔sonnet price ratio. FAMILY-SCOPED — the mechanical-edit family is unmeasured and its downshift (incl. the deferred tier downgrades of existing units) stays gated. Negative control held: an open-ended synthesis/unknown slice never resolves below the session tier (inferSliceTier → medium/inherit, never lite). | quant | `internal/bench/routing-downshift/results-2026-07-08.md#FAMILY-SCOPED PROVE` | ✅ |
 | The lift-carrying essential cut (kernel + downstream-changes) keeps a significant weak-host discipline lift at a fraction of the full load's tokens, and the lift is FAMILY- and HOST-SCOPED — measured on three hosts: claude-haiku-4-5 (weak) shows the family-scoped lift (trapE 0.533→1.000, 7/7 discordant, corpus cost 1.71x); claude-sonnet-4-6 (strong) is a ceiling null; gpt-5-mini (non-Claude weak, codex prompt-prepend surface) FAILED replication with headroom (corpus Δ=+0.024 p=0.70, capability trend n.s. — no harm claimed, injection-surface confound documented). Therefore discipline_profile: auto enables the lift only where measured (vendor-granular unknown_defaults). Non-claims — the balanced router profile was removed after a NULL measurement (p=0.81, n=24); no full-tier recommendation exists; no cross-vendor lift is claimed. | quant | `docs/benchmark.md#REPLICATION FAILED` | ✅ |
 | Behavioural-eval coverage is measured per tier and CI-ratcheted so it can only rise; the current coverage and its gap are published, never implied as "264 evaluated skills". | qual | `src/scripts/skill_eval_coverage.ts#checkRatchet` | ✅ |
+| A hand-rolled, dependency-free BM25 + trigram lexical index resolves the "recalls but does not rank" gap: on the retrieval-precision corpus (9 keyword-overlapping-confuser tasks) it drives the mean top tie-set from 3.333 (the `_score` bucket scorer) to 1.0 — every needed decision uniquely top-ranked — with precision@1 and precision@5 unchanged at 1.0. Method: deterministic, model-free re-ranking of the SAME retrieved entry set; both scorers measured over the identical store via `measure_lexical_ranking.ts`. | quant | `internal/bench/reports/lexical-ranking.json` | ✅ |
 | The whole layer is compiled into host agents with zero runtime daemon. | qual | `docs/contracts/no-runtime-boundary.md#file-first, no-runtime suite` | ✅ |
-| 100 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
-| The second-brain substrate ships as continuity convenience; its cross-session task lift is unmeasured. A deterministic recall scorer + corpus exist (the rig), but no paired run has measured a lift, so no "second brain" capability claim is made until a backed lift entry exists. | qual | `docs/second-brain-scope.md#no measured task-lift` | ✅ |
+| 102 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| On a deterministic multi-session recall corpus, the memory substrate produces a measured, placebo-controlled recall lift — memory-on 27/27 vs no-memory 10/27 and vs equal-byte placebo 9/27 (claude-haiku-4-5, n=9 tasks x 3 seeds, sign test p=0.031 for BOTH pairings). Scoped honestly: this is the context-value upper bound (perfect retrieval on a one-fact-per-task corpus), not retrieval precision under a large store. | quant | `internal/bench/reports/second-brain-delta.json` | ✅ |
+| Removing the perfect-retrieval assumption, the substrate's REAL keyword retrieval recalls the needed decision into the top-5 under keyword-overlapping confusers (precision@5 9/9) and the model disambiguates it from the co-injected confusers — retrieval-on 27/27 vs no-memory 5/27 and vs equal-count placebo 5/27 (claude-haiku-4-5, 9 tasks x 3 seeds, sign test p=0.008 both). Named limit: retrieval RECALLS but does not RANK (mean tie-set 3.3, ties broken by store order, not relevance) — the discrimination gap that motivates the SQLite-FTS5 activation path (ADR-116) at larger scale. | quant | `internal/bench/reports/second-brain-retrieval.json` | ✅ |
+| Every artifact the package ships — source AND the condensed projection that reaches consumers — is machine-scanned in CI for hidden-Unicode, mixed-script-confusable, and instruction-smuggling payloads (the rules-file-backdoor class); a finding blocks the release before `npm publish`, not just the merge. | qual | `.github/workflows/publish-npm.yml#lint_agent_security` | ✅ |
 | 267 skills (README hero + feature list). | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | Removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries. | qual | `docs/contracts/install-layout.md#JSON-pointer` | ✅ |
 
-**12 backed claim(s)** — all evidence pointers resolve in CI.
+**16 backed claim(s)** — all evidence pointers resolve in CI.
 
 Artefact counts in public prose (skills, commands, governed rules,
 guidelines, personas) are **generated from source and CI-drift-checked**:
@@ -74,25 +78,36 @@ deliberately, not overnight.
 runway, RICE, incident command, messaging), but the skills are forged on
 TS/PHP — "promising, not proven" off those stacks. A disclaimer floor
 bounds *liability*, not *correctness*: a skill can be format-correct,
-disclaimered, and still embed a wrong domain assumption. Today **0 of 20**
+disclaimered, and still embed a wrong domain assumption. Today **5 of 20**
 default-surface domain skills carry a sourced `domain-truth` fixture
-(`./scripts-run src/scripts/domain_soundness_status`); all are labeled
-`unvalidated` and the validated count is CI-ratcheted. Authoring the
-answer keys needs domain competence (a cited method, not the skill's own
-output), so validation lands deliberately — the gap is published, never
-implied away.
-
-**Second-brain substrate — continuity convenience, task-lift unmeasured.**
-The memory substrate is built (working-memory continuity across
-compaction, promotable knowledge cards, contradiction surfacing), but
-whether it beats a no-memory baseline on a reproducible task is **not yet
-measured**. The measurement rig exists — a deterministic multi-session
-recall corpus + scorer (`./scripts-run src/scripts/second_brain_score
---dry-run`, no model-in-the-loop grading) — but the paired
-`memory-on`/`off`/`placebo` run is spend-bearing and pending. So no
-"second brain" capability claim is made anywhere; the substrate ships as
-continuity convenience until a paired run backs a lift. Boundary vs a
-human PKM is stated in [`docs/second-brain-scope.md`](second-brain-scope.md).
+(`./scripts-run src/scripts/domain_soundness_status`); the rest are labeled
+`unvalidated` and the validated count is CI-ratcheted. The fixtures landed
+so far are the **deterministic** targets (runway, unit-economics, DCF,
+forecasting, scenario band/sensitivity), whose answer keys are computed
+from cited standard formulas — never the skill's own output; the
+**rubric** targets (incident command, messaging, fundraising, editorial)
+need domain-competent grounding and remain unvalidated, so validation
+lands deliberately — the gap is published, never implied away.
+
+**Second-brain substrate — measured recall lift, honestly bounded.** On a
+deterministic multi-session recall corpus, the memory substrate beats a
+no-memory baseline AND an equal-byte placebo: memory-on **27/27** vs
+no-memory **10/27** vs placebo **9/27** (claude-haiku-4-5, 9 tasks × 3
+seeds, sign test **p = 0.031** for both pairings) — a real,
+placebo-controlled lift (`internal/bench/reports/second-brain-delta.json`).
+Scoped, not oversold: this is the context-value upper bound (perfect
+retrieval on a one-fact-per-task corpus), NOT retrieval precision under a
+large store; the lift concentrates exactly where memory is the only source
+and ties where the prompt self-contains the fact. Boundary vs a human PKM,
+and why the Obsidian export stays declined, are in
+[`docs/second-brain-scope.md`](second-brain-scope.md).
+
+A follow-up removed the perfect-retrieval assumption: against a store of
+keyword-overlapping confusers the REAL retrieval recalls the needed
+decision into the top-5 (9/9) and the model disambiguates it — retrieval-on
+**27/27** vs no-memory **5/27** and vs placebo **5/27** (p=0.008 both). The
+honest limit: the keyword scorer recalls but does not rank (mean tie-set
+3.3), which is the SQLite-FTS5 activation signal (ADR-116) at scale.
 
 ## 3. Known limits (published, witness-tested)
 

package/docs/second-brain-scope.md

@@ -9,35 +9,70 @@
 > Roadmap: `road-to-second-brain-delta-proof`. Verdict of record:
 > `agents/settings/contexts/second-brain-delta-verdict.md` (council 2026-07-07).
 
-## The honest status (2026-07-08)
+## The honest status (2026-07-09 — measured PASS, bounded)
 
 The substrate is **built** (typed knowledge dirs, INDEX generator, retrieval
 protocol, `hot_context_hook` working-memory continuity across compaction,
-`fold_intake`, contradiction surfacing). What is **not yet measured** is the
-*delta*: whether agent-facing memory beats a no-memory baseline on a
-reproducible multi-session task.
+`fold_intake`, contradiction surfacing), and the cross-session recall *delta*
+is now **measured** — a real, placebo-controlled lift, honestly scoped.
 
-- **The measurement rig exists** — a deterministic multi-session recall corpus
+- **The measurement rig** — a deterministic multi-session recall corpus
   (`internal/bench/second-brain/corpus/`) + a scorer
-  (`src/scripts/second_brain_score.ts`) with no model-in-the-loop grading. It
-  dry-runs correctly and discriminatingly on hand-written transcripts.
-- **The paired run does not** — the 3-arm `memory-on` / `memory-off` /
-  `placebo` measurement (Phase 2) is spend-bearing and has not been run. So
-  there is **no measured task-lift**, and therefore **no "second brain"
-  capability claim** is made anywhere in public prose. This is the
-  falsifiability lock: the marker never outruns the evidence.
+  (`src/scripts/second_brain_score.ts`) with no model-in-the-loop grading.
+- **The paired run (Phase 2)** — `memory-on` / `memory-off` / `placebo` on a
+  fixed host (claude-haiku-4-5), 9 tasks × 3 seeds (81 calls). Result:
+  memory-on **27/27**, no-memory **10/27**, equal-byte placebo **9/27**;
+  memory-on beats BOTH, sign test **p = 0.031** for each pairing → **PASS**.
+  Full report: `internal/bench/reports/second-brain-delta.json`
+  (claim `second-brain-recall-lift`).
+- **Where the lift lives** — it concentrates on the retrieval-accuracy tasks
+  where the prior fact is available ONLY from memory (memory-on 3/3, baseline
+  0/3). It **ties** on the three tasks whose k+1 prompt already self-contains
+  the signal (a correction stated in-prompt, or a contradiction the prompt
+  names) — exactly where memory is not the only source. memory-on never loses.
 
-Until the paired run backs a lift, the substrate is documented as **continuity
-convenience** — it carries working memory across sessions and compaction — not
-a proven task-accuracy multiplier.
+### The scoping caveat (stated, not buried)
 
-## What it IS (by design; task-lift unmeasured)
+The Phase-2 delta is the **context-value upper bound**: the corpus is
+one-fact-per-task, so memory-on injects the exact fact (perfect retrieval). It
+shows that **the right prior fact, surfaced, lets the model answer — and that
+this beats both no memory and equal-byte noise** (the placebo isolates mechanism
+from mere extra context).
+
+**The retrieval-precision follow-up removed the perfect-retrieval assumption**
+(2026-07-09, claim `second-brain-retrieval-precision`,
+`internal/bench/reports/second-brain-retrieval.json`). Against a populated store
+whose distractors deliberately share query keywords with the needed decision,
+the REAL `memory_lookup` retrieval recalls the needed decision into the top-5 in
+**9/9** cases, and the model disambiguates it from the co-injected confusers —
+**retrieval-on 27/27 vs no-memory 5/27 and vs equal-count placebo 5/27**
+(sign test p=0.008 both). **Named limit (honest):** the keyword scorer
+**recalls but does not rank** — mean tie-set 3.3 entries share the top score,
+ties broken by store order, not relevance. So recall into the top-k holds *at
+this scale*; once more than k entries share a keyword it would degrade — which
+is exactly the discrimination gap the SQLite-FTS5 activation path (ADR-116)
+exists to close. The public claims are scoped to exactly this.
+
+**Second named limit (separator recall, found 2026-07-10 in a labelled replay
+of real maintainer queries):** `_score()` matches raw substrings, so a query
+key whose token separator differs from the stored field misses entirely —
+`ai_council`, `roadmap-progress`, `force-push` score 0 against space-normalized
+`key` fields that spaced variants (`ai council`) hit at 0.8. The precision
+measurement above did not probe this class (its confusers share exact
+keywords), so it is scoped OUT of the precision claim. Deliberately not
+hot-fixed: naive scoring is locked until the scale tripwire (the archived
+retrieval-economy roadmap's D5), and the FTS5 unicode61 tokenizer splits on
+separators, closing this structurally at activation time. Reproduce:
+`memory_lookup --types product-rules --key "ai_council"` vs `--key "ai council"`
+against any populated store.
+
+## What it IS (measured lift, bounded as above)
 
 | Capability | What it does | Evidence status |
 |---|---|---|
-| Working-memory continuity | `hot_context_hook` re-injects a bounded, deterministic cache across session boundaries and Claude Code compaction | mechanism shipped; task-lift **unmeasured** |
-| Promotable knowledge cards/pages | typed dirs + INDEX + retrieval protocol, with redaction + team-share gate | mechanism shipped; task-lift **unmeasured** |
-| Contradiction surfacing | a session that contradicts a prior decision is flagged on promote | mechanism shipped; catch-rate **unmeasured** |
+| Working-memory continuity | `hot_context_hook` re-injects a bounded, deterministic cache across session boundaries and Claude Code compaction | mechanism shipped; recall lift **measured (bounded PASS)** |
+| Promotable knowledge cards/pages | typed dirs + INDEX + retrieval protocol, with redaction + team-share gate | mechanism shipped; recall lift **measured (bounded PASS)** |
+| Contradiction surfacing | a session that contradicts a prior decision is flagged on promote | mechanism shipped; ties in-prompt, lift where memory is the only source |
 
 ## What it is NOT
 
@@ -52,15 +87,23 @@ a proven task-accuracy multiplier.
   link-density, hybrid human-facing retrieval — is a *different product* for a
   *different consumer* (a person, not an agent). This package writes
   agent-facing memory; it does not serve a human graph browser.
-- **Not a measured accuracy multiplier** — see the honest status above.
+- **Not an unbounded accuracy multiplier** — the recall lift is measured but
+  scoped to the context-value upper bound (see honest status), not proven
+  retrieval precision under a large store.
 
-## Interop, not competition (gated on a measured lift)
+## Interop, not competition (export declined, on the record)
 
-If — and only if — the Phase-2 paired run shows a real lift, the sanctioned
-next step is a **one-way export** (promoted cards → plain Obsidian-compatible
-Markdown + wikilinks), positioning agent-config as the *writer* and a human PKM
-as the *reader*: complementary, never a replacement. Absent a measured lift,
-the exporter is not built.
+The Phase-2 paired run did show a real (bounded) lift, which unlocks the
+optional one-way export (promoted cards → Obsidian-compatible Markdown). It is
+**deliberately not built**: the delta-verdict of record
+(`agents/settings/contexts/second-brain-delta-verdict.md`, council 2026-07-07)
+**rejected** Obsidian compatibility — the dual-write hazard (an external edit
+that never commits silently diverges the INDEX + recurrence counters) outweighs
+the browsing convenience, and the measured lift is a bounded context-value
+result, not a retrieval-precision proof that would justify a new external
+surface. If a human-PKM bridge is ever wanted, the sanctioned path is a
+read-only static render, not an editable vault. Positioning stays: agent-config
+writes agent-facing memory; it does not replace a human PKM.
 
 ## Verify
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "8.8.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,

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/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;
+}