@klhapp/skillmux 1.11.2 → 1.13.0

package/docs/sdd/cli-surface-consistency/think.md

@@ -0,0 +1,149 @@
+# CLI surface consistency: the "target" vocabulary
+
+Status: proposal. Nothing implemented yet.
+
+## The problem
+
+The word "target" carries four unrelated meanings across 587 occurrences in
+`src/`. The clearest single demonstration:
+
+```sh
+skillmux target list --json
+{"target":"local","data":{"targets":[{"name":"claude-code",...}]}}
+```
+
+The outer `"target"` means "local versus a remote server". The inner
+`"targets"` means "directories skills get delivered into". Same word, same
+payload, unrelated concepts.
+
+### The four meanings
+
+1. **A delivery target.** A named directory recorded as `[targets.<name>]` in
+   the vault manifest. This is what `skillmux target` manages, what
+   `project --target <name>` references, what `sync` writes into, and what the
+   `.skillmux` marker records as `role: "target"`.
+   Types: `Target`, `ConfirmedTarget`, `AdoptTargetResult`,
+   `ResolvedBuiltInTarget`, `SyncTargetResult`, `SyncTargetOptions`,
+   `SyncTargetParams`, `SyncTargetSummary`, `SyncProjectTargetsParams`.
+
+2. **The execution destination.** Local process versus remote admin server,
+   selected by `--context`/`--server`.
+   Types: `TargetAdapter`, `TargetAdapterOptions`, `createTargetAdapter`,
+   `CommandTargetSupport`, `COMMAND_TARGET_SUPPORT`, the JSON envelope's
+   `target` field, `renderTargetBanner`, `LocalAdapter`'s `targetName: "local"`.
+
+3. **A file being scanned.** `ScanContentTarget` and `ResolvedScanTargets` in
+   `scan.ts`. Internal only, never user-facing.
+
+4. **An output file path.** `eval promote --target <path>`. User-facing.
+
+### Root cause
+
+This is not four independent mistakes. Meaning 2 was already being renamed to
+"context" in PR #163, and that rename stopped after `context.ts`. Everything
+downstream still says target:
+
+```
+src/context.ts:20    export type ResolvedContext           renamed
+src/adapters.ts:52   export interface TargetAdapter        not renamed, same concept
+src/cli.ts:281       let resolvedTarget: ResolvedContext   variable and type disagree
+src/cli.ts:97        COMMAND_TARGET_SUPPORT                not renamed
+```
+
+`cli.ts:281` is the clearest symptom: a variable named `resolvedTarget` holding
+a `ResolvedContext`. The codebase has been sitting mid-rename since #163.
+
+## Decision
+
+**Meaning 1 keeps the word "target".** It is the correct English use: the
+destination a sync writes into. Everything else borrowed it.
+
+Renaming `[targets.<name>]` to `[agents.<name>]` was considered and rejected.
+Agents and targets are many-to-one, not one-to-one, and the manifest would
+start asserting things that are false. Evidence:
+
+```sh
+skillmux init --agent opencode --agent github-copilot --agent windsurf --yes
+# produces exactly one target:
+#   agent-skills:
+#     dir: ~/.agents/skills
+#     agents: opencode, github-copilot, windsurf
+
+skillmux target add my-scratch --dir ~/scratchdir --yes
+#   my-scratch:
+#     agents: (custom)
+```
+
+`agent-skills` is not an agent, it is one shared directory serving three of
+them. `my-scratch` belongs to no agent at all. Each target already carries its
+own `agents` list as a field, so renaming the section would collide with that.
+
+## Plan
+
+### Step 1: finish the #163 rename (meaning 2 becomes "context")
+
+Mostly mechanical, mostly internal.
+
+| From | To |
+|---|---|
+| `TargetAdapter` | `ContextAdapter` |
+| `TargetAdapterOptions` | `ContextAdapterOptions` |
+| `createTargetAdapter` | `createContextAdapter` |
+| `CommandTargetSupport` | `CommandContextSupport` |
+| `COMMAND_TARGET_SUPPORT` | `COMMAND_CONTEXT_SUPPORT` |
+| `renderTargetBanner` | `renderContextBanner` |
+| `resolvedTarget` (variable) | `resolvedContext` |
+| `emitSuccess({ target })` param | `emitSuccess({ context })` |
+
+Critical constraint: meaning 1 also uses the identifier `targetName`, in
+`init.ts`, `project.ts`, and `sync.ts`, where it means a delivery target name.
+Those must not be touched. Only `adapters.ts`'s `targetName: "local"` belongs
+to meaning 2. A blind find-and-replace on this codebase would corrupt the
+manifest layer, which is exactly the disease being cured.
+
+### Step 2: the JSON envelope field, additively
+
+The envelope's `target` field is public API and documented in `docs/cli.md`.
+Renaming it outright is breaking, and the project is releasing 1.11.0, a minor.
+
+Emit `context` alongside `target` with identical content, mark `target`
+deprecated in code and docs, and remove it at the next major. This mirrors
+what PR #177 did for the `init` envelope.
+
+### Step 3: rename meaning 3
+
+`ScanContentTarget` becomes `ScanContentFile`, `ResolvedScanTargets` becomes
+`ResolvedScanFiles`. Internal only, so no compatibility concern.
+
+### Step 4: `eval promote --target` becomes `--out`
+
+A destination file path is defensible English on its own, but inside this CLI
+"target" is a first-class noun you can `target list`. A `--target` that takes a
+file path and cannot be listed, attached, or synced is the odd one out.
+
+Add `--out <path>`, keep `--target` as a deprecated alias, remove the alias at
+the next major.
+
+## End state
+
+- **target** means a delivery directory, and nothing else.
+- **context** means local versus remote.
+- `scan` uses its own internal vocabulary.
+- `eval promote` writes to `--out`.
+
+## Compatibility summary
+
+| Change | Breaking? | Path |
+|---|---|---|
+| Steps 1 and 3 | No | Internal identifiers only |
+| Step 2 | No | Additive, `target` deprecated |
+| Step 4 | No | `--out` added, `--target` aliased |
+
+## Out of scope
+
+Carried over from the earlier surface review, unchanged and still open:
+
+- `scan --format json` bypasses the documented envelope.
+- `install` is the only mutating command with no confirmation gate.
+- `sync`, `install`, `update`, and `outdated` document none of their flags.
+- The top-level help's `init` line omits `--show-mcp-setup`/`--register-mcp`.

package/docs/sdd/config-authority-rerank-resilience/plan.md

@@ -0,0 +1,338 @@
+# Skillmux Routing Reliability Plan
+
+Status: approved for specification and implementation
+
+## Goal
+
+Give Skillmux a predictable OSS configuration contract, a bounded ranking
+pipeline, and visible inference failures. Measure routing behavior before adding
+policy machinery. Ship one foundation release, then adopt it in Bifrost through
+one infra change.
+
+## Problem
+
+Skillmux accepts generic environment variables such as `EMBED_MODEL`. A parent
+process can set the same name for another purpose. The inherited value then
+overrides Skillmux's TOML file.
+
+Skillmux also reranks the full lexical and vector union. With
+`k_lexical = 15` and `k_vector = 15`, one request can send 30 documents to the
+reranker. The current code catches inference errors and timeouts, then returns a
+degraded retrieval result without the failure reason.
+
+The production incident on 2026-08-17 demonstrated both failures. Bifrost's
+`EMBED_MODEL` replaced the model in Skillmux's TOML file, so Infinity returned
+HTTP 400. After environment isolation restored embeddings, a 10-second timeout
+expired before the reranker finished. Infra PRs #45 and #46 restored production
+with child-environment sanitization, smaller recall lanes, and a 30-second
+timeout. Those changes remain safeguards until Bifrost adopts the release from
+this plan.
+
+A live reranked request also exposed a separate problem. For a bounded DNS
+command, the semantic reranker placed the broad `cloudflare` mission skill above
+the direct `infra-cli` executor. The result was relevant by topic but wrong by
+operational ownership. This plan measures that failure class before deciding
+whether Skillmux needs routing contracts.
+
+## Target Ranking Pipeline
+
+The intended pipeline is:
+
+1. Resolve an exact skill ID or exact title match.
+2. Retrieve lexical and vector candidates.
+3. Fuse both ranked lists with reciprocal rank fusion (RRF).
+4. Send only the top `k_rerank` fused candidates to the semantic reranker.
+5. Apply routing-contract eligibility if the evidence gate justifies it.
+6. Apply calibrated decision thresholds and return `matched`, `ambiguous`, or
+   `no_match`.
+
+RRF is the cheap candidate-generation stage. The reranker performs the more
+expensive semantic comparison. `k_rerank` controls reranker input, while the
+ambiguous candidate limit controls response output. They are separate budgets.
+
+The foundation release stops after step 4 and improves the visibility of step
+6. Step 5 belongs to a later release unless the evaluation report proves that
+ranking quality alone cannot enforce skill ownership.
+
+## Configuration Contract
+
+Skillmux uses this precedence when environment overrides are enabled:
+
+```text
+CLI flags
+SKILLMUX_* environment variables
+TOML configuration
+defaults
+```
+
+Skillmux must stop using generic `EMBED_*` and `RERANK_*` variables. The 1.x
+line emits migration warnings. Skillmux 2.0 removes support.
+
+Add this TOML policy:
+
+```toml
+[config]
+environment_overrides = true
+```
+
+`true` remains the OSS default. `false` makes TOML authoritative for behavioral
+settings. Skillmux must still read:
+
+- `SKILLMUX_CONFIG`, which locates the TOML file
+- secret variables named by `api_key_env`
+- process variables required by the runtime, such as `HOME` and `PATH`
+- explicit CLI flags for the current invocation
+
+`SKILLMUX_CONFIG_READONLY` keeps its current meaning. It prevents admin API
+writes to configuration managed outside Skillmux. It does not control
+precedence.
+
+## Rerank Budget
+
+Add `recall.k_rerank`:
+
+```toml
+[recall]
+k_lexical = 15
+k_vector = 15
+k_rerank = 5
+```
+
+Skillmux retrieves each lane, fuses the results, truncates the fused list to
+`k_rerank`, and sends that list to the reranker. Decision thresholds run on the
+reranked list.
+
+Validation rules:
+
+- `k_lexical`, `k_vector`, and `k_rerank` are positive integers.
+- `k_rerank` does not exceed `k_lexical + k_vector` after configuration loads.
+- The default supports existing installations without an invalid config.
+- The generated example and JSON schema state the default and limits.
+
+Benchmark `k_rerank` values of 5, 10, 15, and 20. Choose the smallest OSS
+default that meets the candidate-recall and latency gates. Bifrost must set the
+measured value in TOML instead of copying an arbitrary value from the incident
+mitigation.
+
+The current `[thresholds].candidate_limit` name is vague because it controls
+only the candidates returned for an ambiguous result. Introduce
+`[output].ambiguous_candidate_limit` and keep the old key as a deprecated 1.x
+alias. Remove the alias in 2.0 with the other configuration migrations.
+
+## Degraded Retrieval Contract
+
+Keep safe fallback behavior. Add structured degradation metadata when a later
+retrieval stage fails:
+
+```json
+{
+  "outcome": "ambiguous",
+  "retrieval": "hybrid",
+  "degraded_from": "reranked",
+  "degradation_reason": "reranker_timeout",
+  "candidates": []
+}
+```
+
+Use stable reason codes:
+
+- `embedding_timeout`
+- `embedding_unavailable`
+- `embedding_protocol_error`
+- `reranker_timeout`
+- `reranker_unavailable`
+- `reranker_protocol_error`
+
+Return safe codes through MCP. Write detailed errors to service logs. Add one
+metric counter labelled by stage and reason. Audit rows must retain the safe
+reason without storing credentials, response bodies, or endpoint URLs that may
+contain credentials.
+
+## Implementation Work
+
+### Change 1: Configuration authority
+
+Update the config types, defaults, TOML loader, environment override layer,
+configuration provenance, JSON schema, CLI documentation, deployment examples,
+and migration notes.
+
+The loader must distinguish three inputs:
+
+1. Namespaced behavioral overrides such as `SKILLMUX_EMBED_MODEL`.
+2. Deprecated generic aliases such as `EMBED_MODEL`.
+3. Secret variables named by an `api_key_env` field.
+
+When `environment_overrides = false`, the loader ignores category 1, warns for
+category 2 during the 1.x migration window, and resolves category 3 at request
+time. `config show --sources` and `doctor` must report the policy and the source
+of each effective behavioral value.
+
+### Change 2: Bounded reranking
+
+Add `k_rerank` to the recall type and schema. In `retrieveAndRerank`, fuse the
+lexical and vector results, then slice the fused list before building reranker
+documents. Preserve each candidate's skill ID, title, description, and score.
+
+Calibration and evaluation must use the same cap as runtime. Dataset generation
+must record the effective recall and rerank settings so a calibration run cannot
+move between configurations without an error.
+
+### Change 3: Failure visibility
+
+Replace broad inference catches with classification that maps
+`RemoteInferenceError.kind`, timeouts, and transport failures to stable reason
+codes. Preserve fallback. Return the degradation fields, write one structured
+log entry, increment metrics, and store the safe code in the audit row.
+
+Do not expose raw exception text through MCP.
+
+### Change 4: Routing evidence gate
+
+Build a sequential labelled corpus that includes direct execution,
+investigation, cross-system correlation, and non-match prompts. For every case,
+record the fused rank, reranked rank, final outcome, latency, effective ranking
+settings, and degradation state.
+
+The foundation is acceptable when:
+
+- the expected skill enters the reranker pool for direct and investigative
+  prompts
+- at least 99 percent of evaluation cases complete without degraded retrieval
+- p95 latency stays within the published service budget
+- non-match prompts do not become confident false matches
+
+If the expected skill reaches the reranker but loses on ownership despite
+matching the topic, classify the case as an ownership failure. That result opens
+the routing-contract phase. Retrieval misses, fusion-order errors, and reranker
+errors remain ranking work.
+
+### Change 5: Routing contracts, gated follow-up
+
+Do not implement this change in the foundation release. If the evidence gate
+opens the phase, write a separate specification for generic skill metadata such
+as:
+
+```yaml
+routing:
+  accepts: [bounded_execution]
+  rejects: [investigation, cross_system_correlation]
+```
+
+Apply eligibility after semantic reranking and before decision thresholds. If
+the request intent is uncertain, return `ambiguous` instead of forcing a match.
+The specification must define intent extraction, schema validation, conflicting
+contracts, metadata provenance, audit output, and compatibility for skills with
+no routing metadata. It must not encode provider names or special cases in the
+Skillmux engine.
+
+## Acceptance Criteria
+
+1. A generic `EMBED_MODEL` cannot change the effective model without a 1.x
+   deprecation warning. Skillmux 2.0 rejects or ignores it according to the
+   published migration contract.
+2. `SKILLMUX_EMBED_MODEL` overrides TOML when
+   `config.environment_overrides = true`.
+3. TOML wins when `config.environment_overrides = false`.
+4. `api_key_env` resolves its named secret under both policies.
+5. `config show --sources` and `doctor` identify the override policy and each
+   behavioral value's source.
+6. Runtime sends no more than `k_rerank` documents to the reranker.
+7. Lexical and vector retrieval still use their configured lane sizes before
+   fusion and truncation.
+8. Calibration and runtime use the same `k_rerank` value.
+9. An embedding failure returns lexical retrieval with the correct safe reason.
+10. A reranker timeout returns hybrid retrieval with
+    `degraded_from = "reranked"` and `reranker_timeout`.
+11. Successful inference returns `retrieval = "reranked"` without degradation
+    fields.
+12. Logs, metrics, and audit rows record the failure class without secret data.
+13. Existing installations with no new settings load a documented default.
+14. The full unit, CLI, MCP, doctor, calibration, and Docker smoke suites pass.
+15. Evaluation output records each candidate's fused rank, reranked rank, final
+    outcome, latency, ranking settings, and degradation state.
+16. Routing contracts cannot enter the foundation release. A separate
+    specification starts only when the evidence gate identifies ownership
+    failures.
+17. `ambiguous_candidate_limit` controls ambiguous response output and the old
+    `candidate_limit` alias emits the documented 1.x migration warning.
+
+## Test Plan
+
+Add focused tests before each behavior change:
+
+- config precedence matrix for TOML, namespaced environment, generic aliases,
+  strict policy, and CLI flags
+- secret resolution under both environment policies
+- provenance and doctor output
+- `k_rerank` validation and request-document count
+- ambiguous output-limit migration and behavior
+- calibration metadata compatibility
+- timeout, availability, and protocol fallback codes
+- MCP response, audit row, structured log, and metric output
+- Docker smoke coverage with a polluted parent environment
+- ownership-versus-relevance fixtures where executor and mission skills share a
+  provider topic
+
+Use fake inference clients for deterministic unit tests. Add one HTTP adapter
+integration test that verifies cancellation and timeout classification.
+
+## Compatibility and Release
+
+Ship the foundation work in reviewable PRs, then publish one release:
+
+1. Configuration authority and migration warnings.
+2. Rerank budget and calibration metadata.
+3. Degradation responses, logs, metrics, and audit data.
+4. Documentation, examples, and release notes.
+5. Sequential evaluation report and selected defaults.
+
+Do not publish an intermediate GHCR image for Bifrost. Merge the full set,
+release one Skillmux version through GitHub Actions, and verify the image digest
+and smoke tests before changing infra.
+
+Routing contracts use a second release. Start that work only after the
+foundation is running in Bifrost and the evidence report passes the gate.
+
+## Bifrost Adoption
+
+Create one follow-up PR in `klhq/infra` after the GHCR release:
+
+- update the pinned Skillmux GHCR version
+- set `config.environment_overrides = false`
+- restore `k_lexical = 15` and `k_vector = 15`
+- set `k_rerank` to the measured value from the foundation evaluation
+- retain `timeout_ms = 30000` for the first deployment
+- set `SKILLMUX_CONFIG_READONLY=true`
+- remove unused `SKILLMUX_EMBED_KEY`
+- keep wrapper sanitization for one release as defense in depth
+
+Deploy through the Bifrost Forgejo workflow and Komodo. Verify the child
+environment, `doctor`, one live reranked request, and the sequential training
+corpus. Keep wrapper sanitization until strict config mode has production
+evidence, then remove it in a later infra change.
+
+Classify the sequential report before opening more implementation work:
+
+- retrieval, fusion, or reranker failures return to the ranking pipeline
+- ownership failures open the routing-contract specification
+- a clean report freezes a fresh v2 held-out corpus for later regression tests
+
+## Out of Scope
+
+- New embedding or reranker models
+- Threshold calibration for the infra routing corpus
+- Mission-skill renames
+- Removal of generic aliases before the documented major release
+- Provider-specific ownership rules hard-coded in Skillmux
+- Routing-contract implementation inside the foundation release
+
+## Handoff
+
+Implement the foundation work in `klhq/skillmux`. Keep configuration authority,
+bounded reranking, failure visibility, and evaluation support in separate
+commits or PRs. Publish one foundation release. Do not edit `klhq/infra` until
+Skillmux publishes that release and its GHCR smoke tests pass.
+
+After Bifrost produces the sequential report, apply the evidence gate. If it
+shows ownership failures, create a separate routing-contract specification and
+release plan. Do not fold that design into the foundation implementation.

package/docs/sdd/config-authority-rerank-resilience/review.md

@@ -0,0 +1,124 @@
+# Review: Configuration Authority and Rerank Resilience
+
+Verdict: Code findings resolved. Release evidence remains pending.
+
+## Remediation
+
+The 2026-08-17 fix pass resolved findings 1 through 4 and finding 6:
+
+- evaluation now uses the production retrieval, RRF, reranker, degradation,
+  and decision functions
+- fused and reranked ranks come from the same execution that produces the
+  recorded outcome
+- degradation logs no longer contain the raw query
+- calibration evidence persists effective recall settings, and doctor marks a
+  run stale when those settings drift
+- doctor receives and reports behavioral configuration provenance
+- strict mode tests cover `SKILLMUX_CONFIG` and `SKILLMUX_CONFIG_READONLY`
+
+Finding 5 is release evidence, not a code defect. Run the sequential corpus at
+`k_rerank` values 5, 10, 15, and 20 against the deployed inference service.
+Select the default only after candidate recall, p95 latency, degradation rate,
+and non-match safety meet the gates in the approved plan.
+
+Reviewed `main...feat/config-authority-rerank-resilience` against `spec.md` and
+the approved routing reliability plan. Runtime tests pass, but the evaluation
+contract and several observability requirements are incomplete.
+
+## Findings
+
+### 1. High: Evaluation output does not execute the runtime ranking pipeline
+
+`src/eval.ts:99` builds lexical and vector results itself. It never calls the
+configured reranker or the decision function. At `src/eval.ts:126`, every case
+is recorded as `outcome: "ambiguous"` and `retrieval: "hybrid"` regardless of
+the real result. `reranked_rank` is declared but never populated, and
+degradation fields cannot be produced by this path.
+
+This does not satisfy AC 4.1 and cannot distinguish a retrieval miss, reranker
+failure, threshold error, or ownership failure. Reuse the production retrieval
+and decision path, or extract one shared instrumented pipeline that returns
+fused rank, reranked rank, outcome, latency, and degradation data.
+
+### 2. High: Degradation logs copy the raw user query
+
+`src/router-core.ts:558` and `src/router-core.ts:585` write `input.query` into
+service logs when inference fails. A query may contain a credential, signed
+URL, customer data, or other sensitive input. This conflicts with AC 3.3's safe
+sanitization requirement and creates a new disclosure path outside the audit
+store.
+
+Remove the raw query from these warning records. Log a request or audit ID,
+stage, safe reason code, and timing instead. If query logging is a supported
+operator feature, it needs an explicit redaction and retention policy.
+
+### 3. Medium: Calibration evidence omits the effective ranking settings
+
+The branch adds `recall_settings` only to `src/eval.ts`. The calibration and
+dataset evidence paths contain no `k_lexical`, `k_vector`, or `k_rerank`
+metadata. This leaves AC 2.3 incomplete and permits a calibration artifact to be
+applied under a different candidate budget without detecting the mismatch.
+
+Persist the effective recall settings with calibration and dataset evidence.
+Reject or mark stale any run whose settings differ from runtime.
+
+### 4. Medium: Doctor reports policy but not value provenance
+
+`src/doctor.ts:111` adds one `config_authority` check. It does not report the
+source of each behavioral value as required by AC 1.5. `config show --sources`
+has a source map, but doctor does not expose equivalent provenance.
+
+Share the effective-source map with doctor and report at least every supported
+behavioral override. Include `server.allowed_origins`, which is recognized by
+`isEnvMasked` but absent from the source-map key list at
+`src/config-service.ts:146`.
+
+### 5. Medium: The foundation evidence gate and selected default are absent
+
+The approved plan requires benchmarks for `k_rerank` values 5, 10, 15, and 20,
+a sequential labelled evaluation report, and a selected default backed by the
+candidate-recall and latency gates. The branch hard-codes a default of 10 and
+contains no benchmark or sequential report.
+
+Complete the evaluation implementation first. Then check in the reproducible
+report or release evidence that selects the OSS default.
+
+### 6. Low: Strict-mode exempt controls lack combined coverage
+
+The suite tests `SKILLMUX_CONFIG` and `SKILLMUX_CONFIG_READONLY` in other
+contexts, but it does not verify that both remain effective when
+`config.environment_overrides = false`. Add one strict-mode integration test
+covering these exemptions.
+
+## Verification
+
+- `bun test`: PASS, 644 passed and 0 failed
+- `git diff --check main...HEAD`: PASS
+- Build check: SKIPPED, no build command was supplied to the review recipe
+- Performance pass: no finding
+- Security, correctness, and compliance delegated passes hit a temporary model
+  rate limit and were completed manually
+
+## AC Status
+
+| Criterion | Status | Notes |
+|---|---|---|
+| AC 1.1 Precedence and policy | ✅ Done | Namespaced environment overrides follow the configured policy. |
+| AC 1.2 Strict TOML mode | ✅ Done | Behavioral overrides are ignored in strict mode. |
+| AC 1.3 Exempt variables | ✅ Done | Strict mode covers config location, read-only control, and secret resolution. |
+| AC 1.4 Generic environment and deprecated keys | ✅ Done | Migration warnings and aliases are implemented. |
+| AC 1.5 Provenance and diagnostics | ✅ Done | Config show and doctor report behavioral value sources. |
+| AC 1.6 Output candidate limit | ✅ Done | New output key controls ambiguous results with a legacy alias. |
+| AC 2.1 Schema and validation | ✅ Done | `k_rerank` is typed, defaulted, and bounded against both lanes. |
+| AC 2.2 Runtime fusion and truncation | ✅ Done | The fused list is truncated before reranker input. |
+| AC 2.3 Calibration and evaluation alignment | ✅ Done | Calibration evidence stores recall settings and doctor detects drift. |
+| AC 3.1 Stable error codes | ✅ Done | Error classes map to the specified codes. |
+| AC 3.2 Safe fallback and metadata | ✅ Done | Embedding and reranker failures preserve a surviving lane. |
+| AC 3.3 MCP and safe sanitization | ✅ Done | Failure logs contain safe stage and reason fields without the raw query. |
+| AC 4.1 Evaluation case output | ✅ Done | Evaluation uses production ranking and records actual ranks, outcome, and degradation. |
+
+## Security Escalation
+
+A dedicated security review is recommended before shipping because the change
+touches remote network egress, credentials referenced through environment
+variables, public MCP response fields, and persistent audit data.