@klhapp/skillmux 1.11.2 → 1.13.0

package/docs/sdd/fetch-outcome-flywheel/spec.md

@@ -0,0 +1,185 @@
+<!-- plane_project: SMX -->
+<!-- plane_module: fetch-outcome-flywheel -->
+
+# Spec: Fetch-outcome routing quality flywheel
+
+## Goal
+
+Skillmux records what it proposed and never what the agent took. `resolve_skill`
+writes an audit row (`src/router-core.ts:406`, `src/db.ts:292`) holding the
+query, retrieval capability, candidates, and latency. `fetch_skill` writes
+nothing. Every quality number the project can produce today comes from the
+hand-curated holdout set in `eval/queries.json`.
+
+Close the loop. Log fetch outcomes, correlate each one to the resolve that
+produced it, and turn real traffic into two things that do not exist yet: a
+measured acceptance signal in `skillmux report`, and a path to grow the eval set
+from observed behavior instead of hand authorship.
+
+Because that correlation joins raw user queries to the skills people actually
+opened, the audit store also gets its own file, a retention window, and a
+cleanup path in this same change.
+
+## Storage
+
+Audit data moves out of `index.sqlite3` and into `audit.sqlite3`, in the same
+`state_dir`. Both files sit under the directory operators already persist
+(`docs/deployment.md:292`), so deployment and backup instructions gain a file
+rather than a procedure.
+
+The split is cheap because audit data is already self-contained. The only read
+is a plain `SELECT ... FROM audit` (`src/stats.ts:150`) with no join to `skills`
+or `vectors`, and `computeStats` derives per-skill counts from the stored
+candidates JSON rather than from the index. The resolve-to-fetch join added here
+is audit-to-audit, so both tables live in the new file and never reach across.
+
+Separating the files buys four things that motivate doing it now rather than
+later:
+
+1. Copying or backing up the derived index no longer carries raw user queries.
+2. Retention and file permissions can differ between telemetry and index state.
+3. Reclaiming space after a prune no longer locks the index. The new file is
+   created with `PRAGMA auto_vacuum = INCREMENTAL`, which the existing file
+   cannot be given without a full rewrite.
+4. Audit writes stop contending with an index rebuild for the single WAL writer.
+
+Paths resolve as they do today: `~/.local/state/skillmux/audit.sqlite3` for a CLI
+install (`src/config.ts:111`), `/data/audit.sqlite3` in a container
+(`src/config.ts:255`).
+
+## Acceptance Criteria
+
+### Storage and migration
+
+1. Audit data is read and written in `audit.sqlite3` under `state_dir`, opened
+   separately from `index.sqlite3`, with WAL journaling and
+   `auto_vacuum = INCREMENTAL` set at creation.
+2. On first open after upgrade, existing `audit` rows in `index.sqlite3` are
+   copied into `audit.sqlite3` within a single transaction and the old table is
+   dropped. The migration is idempotent: a second run finds nothing to move and
+   changes nothing.
+
+### Correlation
+
+3. A `resolve_skill` response carries a `request_id` string, unique per request,
+   in both the text content and `structuredContent`. The audit row written for
+   that resolve stores the same value.
+4. Audit rows written before this feature, which have no `request_id`, still
+   load, report, and render without error.
+5. `fetch_skill` accepts an optional `request_id`. When it names a known resolve,
+   the recorded fetch links to that resolve's audit row.
+6. `fetch_skill` called without a `request_id` succeeds and records an
+   uncorrelated fetch.
+7. `fetch_skill` called with an unknown or malformed `request_id` succeeds and
+   records an uncorrelated fetch. Skill delivery never fails because telemetry
+   could not correlate.
+8. Each recorded fetch stores timestamp, `skill_id`, `request_id` or null,
+   originating audit row id or null, and `rank_at_resolve`. `rank_at_resolve` is
+   the fetched skill's rank in that resolve's shortlist, or null when the fetch
+   is uncorrelated or the skill was absent from that shortlist.
+
+### Reporting
+
+9. `skillmux report` reports `acceptance_rate`, `observed_mrr`, and
+   `top1_acceptance_rate` over resolves that returned at least one candidate. A
+   resolve counts as accepted when at least one correlated fetch exists.
+   `observed_mrr` uses the reciprocal rank of the first fetched candidate.
+10. When a window contains no correlated fetches, `report` marks the acceptance
+    signal unavailable rather than printing `0.000`, and states how many
+    uncorrelated fetches it saw.
+11. `report` lists the top queries that returned candidates and received no
+    correlated fetch, as a list distinct from the existing empty-shortlist list.
+
+### Retention and cleanup
+
+12. Configuration exposes `audit.retention_days`, defaulting to 90. A value of
+    `0` disables pruning and retains rows indefinitely. Invalid values are
+    rejected at config load in the existing error style.
+13. Pruning deletes resolve rows and fetch rows older than the window, each by
+    its own timestamp. A fetch whose resolve row has been pruned reports as
+    uncorrelated rather than erroring, reusing the path that already exists for
+    fetches that carried no `request_id`.
+14. Pruning runs once at server startup and at most once per 24 hours while the
+    server runs. It never blocks readiness and never blocks a resolve.
+15. `skillmux audit prune [--older-than <window>] [--dry-run] [--yes] [--json]`
+    prunes on demand and reports rows removed per table. `--dry-run` performs no
+    writes and reports what would be removed. `--older-than` accepts the window
+    syntax already used by `--since` (`src/stats.ts:4`).
+16. After a prune, incremental vacuum reclaims file space, and the operation
+    never takes a lock on `index.sqlite3`.
+
+### Eval promotion
+
+17. `skillmux eval promote --since <window> --yes` writes eval cases shaped
+    `{ query, split: "observed", relevant_skill_ids }`, where the skill ids are
+    those actually fetched, deduplicated by normalized query. It writes to a path
+    other than `eval/queries.json` unless one is given explicitly, and warns that
+    promoted cases contain raw user queries. Output validates under
+    `parseEvalCases` (`src/eval.ts:15`).
+18. `eval promote` never rewrites an existing case. A query already present in
+    the target file is skipped and counted in the summary.
+
+### Cross-cutting
+
+19. `report`, `audit prune`, and `eval promote` honor `--json` against the
+    documented output schema. Existing exit-code behavior is unchanged.
+
+## Scope
+
+- A separate `audit.sqlite3` store with an `openAudit(stateDir)` entry point
+  beside `openIndex`, and a one-time transactional migration of existing rows.
+- `request_id` generation, storage, and wire exposure on `resolve_skill`.
+- Optional `request_id` input on `fetch_skill` (`src/server.ts:112`) and a fetch
+  audit table, following the migration pattern already in `src/db.ts:52`.
+- New quality metrics in `StatsResponse` (`src/stats.ts:23`), the text renderer,
+  and the JSON output.
+- `audit.retention_days` configuration, automatic pruning, and a
+  `skillmux audit prune` subcommand.
+- `skillmux eval promote` producing `EvalCase` records.
+- Contract and docs updates: `docs/schema.json`, `docs/mcp-routing.md` (tool
+  contract, recommended agent behavior, audit data), `docs/cli.md` (report, the
+  new audit command, eval), and `docs/deployment.md` (the second state file).
+
+## Out of Scope
+
+- **Time-window heuristic correlation.** Correlation is by explicit `request_id`
+  only. Guessing which resolve a bare fetch belongs to manufactures signal that
+  reads as measurement, which is worse than a stated gap.
+- **Query redaction and targeted deletion.** Retention is age-based only. There
+  is no facility to delete one user's queries or to hash queries at rest.
+- Any use of observed data to change ranking automatically. No retraining, no
+  threshold tuning, no reweighting. This feature measures and proposes, and a
+  human promotes.
+- Per-client or per-context routing profiles.
+- Changes to the retrieval pipeline, fusion, or reranker behavior.
+- Exporting audit data to an external log or metrics pipeline.
+- Any dashboard or web view. `report` and `--json` are the surface.
+
+## Tasks
+
+Ordered so that later slices land in the new store rather than being moved
+twice.
+
+1. **Split the audit store.** Add `openAudit(stateDir)`, create `audit.sqlite3`
+   with WAL and incremental auto-vacuum, migrate existing rows out of
+   `index.sqlite3` transactionally, and repoint `src/stats.ts` and
+   `src/router-core.ts` at the new handle.
+2. **`request_id` on resolve.** Add the column, generate the id in
+   `router-core`, thread it into the audit insert and both response channels,
+   and update `docs/schema.json`.
+3. **Fetch outcome logging.** Add the fetch table and insert helper, the optional
+   `request_id` on the `fetch_skill` input schema, a correlation lookup that
+   degrades to uncorrelated on any miss, and rank resolution against the stored
+   candidates.
+4. **Retention and cleanup.** Add `audit.retention_days`, the prune routine with
+   incremental vacuum, the startup and daily triggers, and the
+   `skillmux audit prune` subcommand.
+5. **Quality metrics in report.** Extend `computeStats`, the renderer, and the
+   JSON shape with acceptance rate, observed MRR, top-1 acceptance, unused
+   shortlist queries, and the signal-unavailable case.
+6. **`skillmux eval promote`.** Window parsing reusing `parseSince`, case
+   construction, dedupe against the target file, the `--yes` gate, `--dry-run`,
+   and `--json`.
+7. **Docs pass.** MCP routing contract and audit section, CLI report, audit and
+   eval sections, deployment note on the second state file, and the standing note
+   that `fetch_skill` remains usable without a prior resolve.

package/docs/sdd/npm-native-binaries/review.md

@@ -0,0 +1,103 @@
+# Review — npm-native-binaries
+
+Branch `feat/npm-native-binaries`, 7 commits, 24 files, +1243/-79.
+Fan-out: compliance, security, correctness, performance, tests, build, suite.
+
+## Verdict
+
+Spec 15/15. `bunx tsc --noEmit` clean. Suite 954/954.
+
+## AC Status
+
+| Issue | Criterion | Status | Notes |
+|---|---|---|---|
+| SMX-142 | build:binaries compiles five targets through the sharp stub | ✅ Done | `tests/build-binaries.test.ts` builds all five |
+| SMX-143 | build:npm-packages emits platform packages with os, cpu, bin, 0o755 | ✅ Done | `tests/package-npm-binaries.test.ts` |
+| SMX-144 | Platform packages carry onnxruntime libraries, darwin-x64 exempt | ✅ Done | Verified against the real payload, not a fixture |
+| SMX-145 | Root package.json points bin at the launcher and pins five optional deps | ✅ Done | Verified from a packed tarball |
+| SMX-146 | Polyglot shebang runs under bun-only and node-only | ✅ Done | Both directions covered with PATH narrowed |
+| SMX-147 | Launcher resolves the package, forwards argv, exit code and signals | ✅ Done | Also verified in both global install layouts |
+| SMX-148 | Launcher injects the library path so local inference works | ✅ Done | `embeddings: 1 backfilled` from the packaged binary |
+| SMX-149 | SKILLMUX_BINARY overrides the resolved executable | ✅ Done | |
+| SMX-150 | Missing platform package fails loudly | ✅ Done | |
+| SMX-151 | Dockerfile entrypoint is the binary, healthcheck drops bun and node | ✅ Done | |
+| SMX-152 | full ships libonnxruntime.so.1, slim stays lexical | ⚠️ Manual-verify | Verified on linux/arm64 only; amd64 needs CI |
+| SMX-153 | docker-smoke.sh passes for slim and full on amd64 and arm64 | ⚠️ Manual-verify | Both arm64 lanes pass locally. amd64 verified only as far as the cross-compiled executable running under emulation; the full lane needs CI |
+| SMX-154 | npm pack ships bin/skillmux.js and not src/ | ✅ Done | |
+| SMX-155 | Release workflow publishes platform packages before the root | ✅ Done | Ordering asserted in `tests/release-workflow.test.ts` |
+| SMX-156 | All five executables attached to the GitHub Release | ✅ Done | Added mid-implementation, see back-edge below |
+
+Issue keys are listed so `sdd-cleanup` does not have to match criteria to
+issues by title. Use this column rather than the titles.
+
+The post-review run posted the two MANUAL-VERIFY verdicts and none of the
+thirteen PASS ones. That was first read as a title-matching failure, which
+was wrong. The comment timestamps show only two writes, two seconds apart,
+both successful, so it was not a rate limit either; and SMX-152 matched
+despite its criterion text not being a substring of its title, while SMX-149
+went uncommented despite being a clean substring. The discriminator was the
+verdict value, not the text: the recipe skipped every PASS row. Fixed in
+sdd-cleanup on 2026-09-14, along with a verdict-line format violation and a
+missing Plane rate-limit guard.
+
+## Findings
+
+### Accepted and fixed
+
+**`bun run build` produced an executable that cannot embed.** The root `build`
+script still ran a raw `bun build --compile`, which skips the sharp stub, so the
+executable it produced silently lost local inference. `ci.yml` and `README.md`
+both invoke it. `build` now routes through `scripts/build-binaries.ts host`.
+
+The review reported this as "the test will fail", which was not true: the suite
+was green before and after, because the script string still matched its
+assertion. The defect was real; the stated symptom was not.
+
+### Rejected
+
+**`SKILLMUX_BINARY` is spawned without validation** (security, Medium). Not a
+vulnerability. An attacker who can set environment variables for your shell can
+already run code as you; `PATH` and `NODE_OPTIONS` are the same shape. esbuild
+ships `ESBUILD_BINARY_PATH` with identical semantics. Validating it would remove
+the escape hatch the troubleshooting docs point at without closing any path.
+
+**The launcher misses the package under a global install** (correctness, High).
+Tested rather than argued. Installed the packed tarball into a temporary npm
+prefix and placed the platform package in both layouts npm produces, then ran
+the launcher from `/` so the working directory could not contribute:
+
+```
+佈局 A  hoisted, lib/node_modules/@klhapp/skillmux-darwin-arm64   -> 1.12.0
+佈局 B  nested,  .../skillmux/node_modules/@klhapp/...            -> 1.12.0
+```
+
+`require.resolve` with `paths: [here]` walks every ancestor `node_modules`, which
+covers both. The finding also reviewed a stale diff, since the `build` fix was
+still uncommitted when the pass ran.
+
+## Needs decision
+
+**`bin` in the platform packages.** Discovered while testing the global install:
+installing a platform package globally alongside the root package fails with an
+`EEXIST` on `$PREFIX/bin/skillmux`, because both declare `bin.skillmux`. The
+normal flow never hits this, since npm links bins only for the package being
+installed, not its dependencies.
+
+esbuild declares `bin` in its platform packages so a package manager can link the
+native executable directly and skip the JavaScript shim on machines without
+Node. Our polyglot shebang already removes that need, so the field buys little
+and can conflict. Removing it contradicts the spec, which names `bin` explicitly
+in AC2, so this is left as written pending a decision.
+
+## Back-edge to spec
+
+One, recorded during implementation. The launcher's missing-package message
+sends every platform to the releases page, but only the two Linux executables
+were attached there. The spec gained an acceptance criterion for attaching all
+five before the change was made, rather than widening scope silently.
+
+## Test flake
+
+One run of the suite reported a single failure that did not recur across three
+subsequent clean runs, and the failing test name was not captured. Unresolved
+and unattributed. Worth watching on CI rather than assuming it is gone.

package/docs/sdd/npm-native-binaries/spec.md

@@ -0,0 +1,148 @@
+## Goal
+
+Ship Skillmux as native per-platform executables on npm so that `npm install`,
+`npx`, and `bun add -g` all work with no runtime prerequisite, while keeping
+local ONNX embedding inference working on every platform that has an
+onnxruntime build.
+
+## Acceptance Criteria
+
+- [ ] `bun run build:binaries` compiles five executables into `dist/bin/` for
+  `bun-darwin-arm64`, `bun-darwin-x64`, `bun-linux-x64`, `bun-linux-arm64`,
+  and `bun-windows-x64`, each built through a bundler plugin that resolves
+  `sharp` to `scripts/stubs/sharp.ts`.
+- [ ] `bun run build:npm-packages` emits `dist/npm/@klhapp/skillmux-<platform>-<arch>/`
+  for each target, where `<platform>` is `process.platform` (`win32`, not
+  `windows`), each containing a `package.json` whose `version` equals the root
+  `version` and which declares `os`, `cpu`, and `bin`, plus the executable at
+  mode `0o755`.
+- [ ] Each platform package except `@klhapp/skillmux-darwin-x64` also contains
+  that platform's onnxruntime runtime libraries; `darwin-x64` ships without
+  them because `onnxruntime-node` publishes no `darwin/x64` artifacts.
+- [ ] Root `package.json` sets `bin` to `{ "skillmux": "./bin/skillmux.js" }`
+  and lists all five platform packages under `optionalDependencies` pinned to
+  the exact root version.
+- [ ] `bin/skillmux.js` starts with a `#!/bin/sh` polyglot line that execs
+  whichever of `bun` or `node` exists, and runs correctly with neither `node`
+  nor `bun` absent from `PATH` in turn.
+- [ ] The launcher resolves the platform package via `require.resolve` against
+  `__dirname`, `dirname(process.argv[1])`, and `process.cwd()`, forwards
+  `process.argv.slice(2)` with `stdio: "inherit"`, mirrors the child exit code,
+  and forwards `SIGINT` and `SIGTERM`.
+- [ ] The launcher prepends the platform package's library directory to
+  `DYLD_FALLBACK_LIBRARY_PATH` on darwin, `LD_LIBRARY_PATH` on linux, and
+  `PATH` on win32, so that `skillmux index` against a local-inference config
+  reports `embeddings: N backfilled` rather than a dlopen failure.
+- [ ] `SKILLMUX_BINARY` overrides the resolved executable path.
+- [ ] With no matching platform package installed, the launcher exits non-zero
+  with a message naming the missing package and the standalone download
+  procedure, and never falls back to a partially working mode silently.
+- [ ] `Dockerfile` sets `ENTRYPOINT ["/usr/local/bin/skillmux"]`, keeps
+  `CMD ["serve", "--transport", "http"]`, and its `HEALTHCHECK` probes
+  `http://127.0.0.1:3000/health/ready` without invoking `bun` or `node`.
+- [ ] The `full` stage ships `libonnxruntime.so.1` with `LD_LIBRARY_PATH` set;
+  the `slim` stage does not ship it, preserving `retrieval_capability`
+  `hybrid` for full and `lexical` for slim.
+- [ ] `bash tests/docker-smoke.sh` passes unchanged for both `slim` and `full`
+  on `linux/amd64` and `linux/arm64`.
+- [ ] `npm pack --dry-run` on the root package lists `bin/skillmux.js` and does
+  not list `src/`.
+- [ ] The release workflow publishes all five platform packages before the root
+  package, and GitHub Release assets keep the existing `skillmux-linux-amd64`
+  and `skillmux-linux-arm64` names.
+- [ ] All five executables are attached to the GitHub Release, not only the two
+  Linux ones. The launcher's missing-package message sends users of every
+  platform to that page, so a macOS or Windows reader must find something
+  there.
+
+## Scope
+
+The binary build and packaging scripts, the launcher, the `sharp` build-time
+stub, root `package.json` metadata, the `Dockerfile` migration to the compiled
+binary, `tests/package-metadata.test.ts` and `tests/dockerfile.test.ts`
+updates, release workflow changes, and installation documentation in
+`README.md`, `docs/getting-started.md`, `docs/deployment.md`, and
+`docs/troubleshooting.md`.
+
+## Out of Scope
+
+Porting the codebase off Bun to Node. Changing retrieval, routing, config, or
+CLI behavior. Restoring local inference on `darwin-x64`. Publishing
+`win32-arm64`, which `bun build --compile` does not target. Changing the
+remote-inference or reranker paths. Altering the GHCR and Docker Hub tagging
+scheme.
+
+## Tasks
+
+1. Add the `sharp` stub and `scripts/build-binaries.ts`, with a test asserting
+   all five executables are produced and the host one reports the root version.
+2. Add `scripts/package-npm-binaries.ts` and the platform-package layout test,
+   including the onnxruntime library payload and `darwin-x64` exemption.
+3. Write `bin/skillmux.js` and its launcher tests: runtime selection, argv and
+   exit-code forwarding, signal forwarding, library-path injection, override,
+   and the missing-package error.
+4. Switch root `package.json` to the launcher and update
+   `tests/package-metadata.test.ts`.
+5. Migrate the `Dockerfile` to the compiled binary and update
+   `tests/dockerfile.test.ts`; verify both smoke lanes.
+6. Extend the release workflow to build and publish the platform packages.
+   This must also keep the root `optionalDependencies` pins in step with the
+   version Release Please writes, or every release ships a root package
+   pointing at the previous release's platform packages. The pins are exact,
+   and `tests/package-metadata.test.ts` fails when they drift, so a stale pin
+   turns the Release Please PR red rather than shipping quietly.
+7. Update the installation and troubleshooting documentation. This must state
+   which platforms get local inference and which fall back to lexical recall,
+   and must say why `darwin-x64` is the exception, including that the exception
+   is expected to be temporary. See "darwin-x64 is an upstream regression"
+   below.
+
+## Verified Constraints
+
+These were established empirically on 2026-09-13 against Skillmux 1.12.0 with
+Bun 1.4.2 and Node v24.21.0. They are the reason the design looks the way it
+does; re-deriving them costs an hour.
+
+- A bun-compiled binary cannot load `onnxruntime-node` unaided. The `.node`
+  addon is embedded and extracted to a temp path, but its dylib is not, and
+  `@rpath/libonnxruntime.1.24.3.dylib` then resolves to that temp directory.
+  Pointing `DYLD_FALLBACK_LIBRARY_PATH` at the real library directory fixes it.
+- `--external` does not help. A compiled binary performs no `node_modules`
+  resolution at runtime; an external specifier fails as
+  `Cannot find package '<name>' imported from /$bunfs/root/<binary>`. The same
+  applies to a nested bare import reached through an absolute-path dynamic
+  import.
+- `@huggingface/transformers` eagerly requires `sharp`, which text embedding
+  never uses. Replacing it with a throwing stub at bundle time is what makes
+  `models download` and `index` succeed in the compiled binary.
+- `bun install` honours `os` and `cpu` for registry packages; installing
+  `esbuild` pulls only `@esbuild/darwin-arm64`. `npm` rejects a mismatched
+  platform package with `notsup`.
+- `bun add -g` symlinks the `bin` JS file directly, so a `#!/usr/bin/env node`
+  shebang fails on a Bun-only machine. The `#!/bin/sh` polyglot line runs under
+  bun-only, node-only, and both.
+
+## darwin-x64 is an upstream regression, not a permanent limit
+
+`onnxruntime-node` 1.24.3 ships `bin/napi-v6/darwin/arm64` but no `darwin/x64`
+directory at all, which is why that target needs the `onnxruntime-node` stub to
+compile and loses local inference. This is not a deliberate platform drop.
+It is tracked upstream as a packaging regression introduced in the 1.23.x
+series, where the Intel macOS artifact is still built in CI but does not reach
+the npm tarball:
+
+- https://github.com/microsoft/onnxruntime/issues/27961
+- https://github.com/huggingface/transformers.js/issues/1634
+
+`onnxruntime-node` 1.23.2 is the last release that carries the Intel macOS
+binding.
+
+`hasNativeOnnxruntime` probes the filesystem rather than consulting a hardcoded
+list, so if a future `onnxruntime-node` restores `darwin/x64`, that target stops
+being stubbed and starts carrying its library payload with no code change. Keep
+it that way. The alternative, vendoring the 1.23.2 binding into the darwin-x64
+package alone, mixes ONNX Runtime versions across platforms and should only be
+considered if the upstream regression proves permanent.
+
+<!-- plane_project: SMX -->
+<!-- plane_module: npm-native-binaries -->

package/docs/sdd/ranked-shortlist-2/pr3-calibration-removal.md

@@ -0,0 +1,56 @@
+# PR 3 private implementation packet: calibration removal
+
+This file is internal, ignored, and must never be staged or committed.
+
+## Goal
+
+Remove Skillmux's obsolete threshold-calibration product surface and all code
+used only to implement it. Ranking evaluation remains. Existing
+`calibrate.sqlite3` files on operator disks are never opened, migrated, edited,
+or deleted by the new code.
+
+## Required behavior
+
+1. `skillmux calibrate ...` is removed from command dispatch, help, Docker
+   command policy, completions, and public adapter interfaces. Invoking it must
+   fail non-zero with a concise 2.0 migration message that says threshold
+   calibration was removed and points users to `skillmux eval` for ranking
+   evaluation.
+2. Remove calibration from local/remote capability types and responses. Delete
+   calibration admin endpoint declarations and handlers rather than returning
+   501 placeholders. Requests to the old routes follow the server's ordinary
+   unknown-route behavior.
+3. Remove calibration-only implementation: dataset generator, dataset decision
+   parser, optimizer, certification gates, resume/checkpoint/persistence,
+   calibration timing/retry plumbing, apply/config mutation, and calibration
+   fingerprints or watchers that have no non-calibration consumer.
+4. Remove decision-threshold code that has no remaining runtime consumer.
+   Do not alter ranked resolution, retrieval, reranking, evaluation, audit
+   reporting, or skill delivery behavior.
+5. Remove `inference.calibration` from accepted configuration. A legacy
+   `[inference.calibration]` block must fail with an actionable message saying
+   it is obsolete in 2.0 and should be deleted. Existing obsolete threshold
+   errors remain actionable.
+6. Remove calibration-only source files and tests. Update shared tests rather
+   than weakening unrelated assertions. Ranking-evaluation tests remain.
+7. Remove calibration references from current CLI help, completions, server
+   capabilities, generated public schema, configuration examples, and focused
+   command/API documentation required for truthful current surfaces. Leave the
+   broad documentation rewrite and migration guide to PR 4 unless a statement
+   would otherwise advertise a command or endpoint that no longer exists.
+8. Do not unlink, rename, migrate, truncate, or write any existing
+   `calibrate.sqlite3`. Add a regression test proving startup/doctor/eval leaves
+   a sentinel calibration database byte-for-byte unchanged.
+9. Do not stage or commit anything under `docs/sdd/`. Preserve all ignored
+   local artifacts.
+
+## Verification
+
+- Start with failing public-interface tests for the removed command,
+  capabilities/routes, legacy config error, and untouched sentinel database.
+- Work in red-green-refactor cycles and commit each logical cycle.
+- Search tracked source, tests, schemas, examples, CLI help, and completions for
+  stale executable calibration surfaces.
+- Run `bun test`, `bun x tsc --noEmit`, `npm run build`, and `git diff --check`.
+- Return commits, deleted files, verification totals, and any intentionally
+  deferred documentation references.

package/docs/sdd/refactor-builtin-target-paths/spec.md

@@ -0,0 +1,41 @@
+## Goal
+
+Make deterministic built-in target directories an application rule rather than
+duplicated absolute paths in the Skillmux manifest.
+
+## Acceptance Criteria
+
+- [ ] `agent-skills`, `claude-code`, and `codex` targets resolve their native
+  directories from their names when syncing, managing projects, or rendering
+  target information.
+- [ ] New or rewritten manifest entries for those built-in targets omit `dir`.
+- [ ] Existing manifests that contain a built-in target `dir` remain readable
+  and continue to resolve the built-in native directory, without using a
+  non-standard persisted path as an override.
+- [ ] A custom target requires `dir`, and its configured directory remains the
+  path used by all target operations.
+- [ ] The CLI exposes a deliberate migration path that removes redundant
+  built-in `dir` fields without changing target markers, managed links, or
+  project pins.
+- [ ] Tests cover built-in resolution, legacy manifest compatibility, custom
+  target behavior, and migration idempotence.
+
+## Scope
+
+Manifest parsing, serialization, target-directory resolution, relevant CLI
+output and operations, documentation, and migration tests.
+
+## Out of Scope
+
+Changing native directory conventions, moving target directories or markers,
+retargeting skills, changing custom target paths, or automatically mutating a
+manifest during ordinary sync.
+
+## Tasks
+
+1. Define the manifest and target-resolution contract, including compatibility
+   with legacy built-in `dir` fields.
+2. Add tests for resolution and an explicit idempotent migration command.
+3. Route target, sync, init, and project operations through the shared
+   resolver and update manifest serialization.
+4. Document the built-in/custom distinction and migration workflow.

package/docs/sdd/runtime-resource-hardening/review.md

@@ -0,0 +1,86 @@
+# Review: Runtime Resource Hardening
+
+Branch `feat/runtime-resource-hardening` vs `main`, 5 commits (a6ec66a, 933315c, 8b7d66b, ac27004,
+654974c — the last is the post-review fix described below).
+Reviewed manually — `goose run --recipe sdd-review` hit the same 24h Bifrost token-quota
+exhaustion seen during slice 1 (`token limit exceeded (279006/250000, resets every 24h)`);
+fell back to the skill's documented manual path (sequential focus passes + native test/build runs).
+
+## Test Execution
+
+`bun test`: **787 pass, 0 fail, 2006 expect() calls** (58 files, 24.14s) at initial review; **792 pass, 0 fail, 2013 expect() calls** after the post-review fix commit (5 new unit tests for `releaseOnStreamClose`).
+
+## Build Check
+
+`bunx tsc --noEmit`: **clean**, exit 0.
+
+## Compliance
+
+| Criterion | Status | Notes |
+|---|---|---|
+| AC1: default bounds (1 MiB body, 100 concurrent) apply with no `[server]` config | ✅ Done | `?? DEFAULT_MAX_BODY_BYTES` / `?? DEFAULT_MAX_CONCURRENT_REQUESTS`; the 413-default test runs against a config with no `[server]` section at all, confirming this is the true zero-config path, not an overridden one. |
+| AC2: oversized body → 413 before full buffering | ✅ Done | Native `Bun.serve` `maxRequestBodySize`; verified empirically earlier this session (413 returned pre-handler). |
+| AC3: once `max_concurrent_requests` in-flight, next request → 503 | ✅ Done | Fixed post-review (commit 654974c): `releaseOnStreamClose` now defers the release until the response body stream actually drains or is cancelled, so long-lived SSE connections hold their slot for their real duration. See Correctness finding below for detail and why HTTP-level round-trip coverage wasn't added. |
+| AC4: both bounds configurable via `[server]` | ✅ Done | zod schema + wiring; tested with `max_body_bytes = 100`, `max_concurrent_requests = 0`. |
+| AC5: `allowed_hosts` unset → embedding/reranker unaffected | ✅ Done | `assertHostAllowed` no-ops on `undefined`/`[]`; covered by the unset-allowlist reranker test and pre-existing embedding tests. |
+| AC6: disallowed embedding host → `RemoteInferenceError(configuration)` pre-fetch | ✅ Done | Tested; asserts zero requests reached the mock fetch. |
+| AC7: disallowed reranker host → same | ✅ Done | Tested; asserts zero requests reached the mock fetch. |
+| AC8: allowed host → proceeds unchanged | ✅ Done | Tested for both embedding and reranker. |
+
+No schema.json exists for this feature (config-shape-only change, not a new API surface) — consistent with the spec's own scope.
+
+## Security
+
+- Host-allowlist reuse (`assertHostAllowed`/`extractHost`) is unmodified from slice 1 (already reviewed then); no new bypass surface — exact-match on `URL.hostname`, so userinfo tricks (`http://evil@allowed.example.com/`) and suffix tricks (`allowed.example.com.evil.com`) don't bypass it.
+- Reranker's host check is skipped when `docs.length === 0` (early return before the check) — harmless, since that path never reaches `fetch` either.
+- Concurrency/body-size checks run before CORS, rate-limiting, and auth — correct ordering for resource protection (cheapest, most attacker-facing check first).
+- The SSE connection-exhaustion gap (the "hold the connection open" attack a concurrency bound is meant to stop) had a real security dimension — see Correctness below; it's now fixed.
+
+## Correctness — Resolved (was Needs Decision)
+
+User chose option 1 (wrap the stream body to release on close/cancel). Implemented in commit
+654974c as `releaseOnStreamClose` (`src/concurrency-limiter.ts`), wired into the fetch handler's
+try/catch in place of the immediate `finally`-release. Verified with 5 new unit tests
+(`tests/concurrency-limiter.test.ts`): held-while-open, released-on-full-drain,
+released-on-cancel, no-body short-circuits immediately, release-at-most-once (idempotent).
+
+An HTTP-level round-trip regression test (open a real SSE stream via the MCP transport, assert
+503 while held, cancel, assert 200 after) was attempted and abandoned: Bun's own `fetch()` client,
+called from the same process as the server under test, does not resolve with response headers
+until the first body chunk is enqueued — so a deliberately-idle open SSE stream (no data pushed)
+never lets the client-side `fetch()` promise resolve, and the test hangs. Confirmed via a minimal
+Bun.serve probe that a real out-of-process client (`curl`) *does* receive headers immediately for
+the same handler shape — this is a same-process test-harness limitation specific to Bun's `fetch()`,
+not a gap in production behavior. Retained to Hindsight (`infra` bank) as a gotcha for future
+streaming-endpoint tests in this repo.
+
+**Original finding (for the record): concurrency slot released on Response construction, not stream closure, for SSE responses.**
+
+`src/server.ts`'s wrapper:
+```ts
+if (!concurrencyLimiter.tryAcquire()) { ... }
+try {
+  return await handleHttpRequest(req, server);
+} finally {
+  concurrencyLimiter.release();
+}
+```
+`handleHttpRequest` resolves as soon as it returns a `Response` — including a `Response(readableStream, { headers: {"Content-Type": "text/event-stream"} })` from the MCP SDK's `webStandardStreamableHttp.js` (used for both the GET SSE notification channel and POST streaming replies). The `finally` fires at that point, not when the stream is actually drained/canceled by the client disconnecting. Net effect: `max_concurrent_requests` bounds the *synchronous handling* portion of a request, not the *lifetime of an open streaming connection* — the code's own comment ("protects against connection exhaustion") oversells what's implemented, and an attacker opening many SSE streams isn't actually capped by this bound.
+
+This wasn't caught by tests because the added HTTP-level test for AC3 deliberately uses `max_concurrent_requests = 0` (a synchronous-rejection check) rather than a real concurrent-streaming scenario — a reasonable choice to avoid a flaky test, but it means the streaming gap has no regression coverage either.
+
+**Options** (design decision, not auto-fixed):
+1. Wrap the returned `Response`'s body (when it's a `ReadableStream`) so `release()` fires on stream `cancel()`/close instead of on `Response` construction — closes the real gap, adds complexity to the wrapper.
+2. Accept current behavior as "bounds concurrent request-*processing* work, not connection lifetime," and correct the comment/docs to say so precisely, deferring true streaming-connection bounding to a later slice.
+3. Add a separate, explicit cap on concurrent SSE streams (distinct from the request-processing counter) if connection exhaustion is the primary threat model for this transport.
+
+## Test Coverage (static)
+
+Adequate. `releaseOnStreamClose` is covered directly at the unit level (5 tests); the wiring itself
+(`res.body → releaseOnStreamClose(res.body, () => concurrencyLimiter.release())`) is a single line
+verified by `tsc --noEmit` and the unchanged 413/503 HTTP tests staying green (buffered-body
+responses drain through the wrapper almost instantly, so existing behavior is unaffected).
+
+## Performance
+
+No concerns — `ConcurrencyLimiter.tryAcquire`/`release` are O(1) synchronous counter ops; `maxRequestBodySize` is native to Bun with no manual buffering.