savant-code 0.0.17 → 0.0.19

package/dev/fids/archive/FID-2026-0803-010-database-llm-providers-low-fixes.md

@@ -0,0 +1,255 @@
+# FID: Database + LLM-Providers LOW Fixes
+
+**Filename:** `FID-2026-0803-010-database-llm-providers-low-fixes.md`
+**ID:** FID-2026-0803-010
+**Severity:** low
+**Status:** verified (archived)
+**Created:** 2026-08-03
+**Author:** Savant
+
+**Summary:**
+Implement the 6 LOW findings from the database + llm-providers audit track
+(DB-A..C, LLM-A..C), plus one bonus dead-file removal (LLM-D) surfaced by the
+same evidence pass. All findings are correctness-consistency and cleanup items
+on code that already carries the FID-0803-002 hardening — no behavioral change
+is expected, and both packages' test suites (db 11/11, llm 57/57) must stay
+green.
+
+---
+
+## RED — Evidence
+
+| # | Location | Issue (summary) |
+|---|---|---|
+| DB-A | `database/src/service.ts:252` | `getMessage(messageId)!` — sole `!` assertion, bypasses `requireRow` read-back pattern |
+| DB-B | `database/src/index.ts:46-51` | `agent_configs` table dead — zero service functions, zero consumers |
+| DB-C | `database/src/service.ts` (20 sites) | fresh `db.prepare()` per call, hot-loop functions included |
+| LLM-A | `chat/openai-compatible-chat-language-model.ts:395-665` + `chat/stream-transform.test.ts` | test simulates its own copy of the inline transform — cannot catch regressions |
+| LLM-B | `chat/openai-compatible-chat-language-model.ts:120-134` | `parseProviderOptions` awaited twice on the same key (default path) |
+| LLM-C | `chat/` vs `completion/` helpers ×2 | byte-identical duplicate files (`diff` exit 0 on both pairs) |
+| LLM-D (bonus) | `openai-compatible/internal/index.ts` | dead barrel file — zero importers (Law 4) |
+
+### Finding details
+
+**DB-A** — `createMessage` returns `getMessage(messageId)!` (`service.ts:252`),
+the only non-null assertion in the file. FID-0803-002 DB-5 established the
+`requireRow` read-back pattern (`service.ts:65-72`) precisely for this
+"get-after-create" purpose, and it is used at `:87`, `:169-172`, `:211`. The
+`!` bypasses it, so a write that silently fails surfaces a confusing TypeError
+instead of the labeled error. Safe today (INSERT OR IGNORE + FK enforcement),
+inconsistent with stated hardening intent.
+
+**DB-B** — `agent_configs` (`index.ts:46-51`) has FK refs to `sessions` and
+`agent_templates` but zero consumers repo-wide: `rg` over `packages/database`,
+`cli/src`, `sdk/src` and a full-tree `-g '*.ts'` sweep both return nothing; the
+CREATE TABLE is the only occurrence. Pre-rebrand legacy.
+
+**DB-C** — every service function prepares its statement per invocation (20
+`db.prepare(...)` sites, e.g. `:82`, `:91`, `:118`, `:247`, `:256`).
+`bun:sqlite` `Statement`s are reusable; `createMessage`/`getMessage`/
+`getSession` run per-message/per-turn in the hot loop.
+
+**LLM-A** — the real streaming transform (parse-failure handling, raw-chunk
+emit, usage/tool-call accumulation, stale-fragment checks, flush close-out) is
+inline in the model's `TransformStream`. `stream-transform.test.ts`
+re-implements its own simulated copy ("Simulate the transform logic from
+openai-compatible-chat-language-model.ts") with zero imports from the
+implementation — it cannot catch regressions in the most-FID'd code in the
+repo (0801-007/008/010/011).
+
+**LLM-B** — `getArgs` awaits `parseProviderOptions` twice with the same schema.
+`providerOptionsName` = `config.provider.split('.')[0]` (`:95-97`) —
+`'openai-compatible'` in the default case — so the second call re-parses the
+identical key: duplicate zod validation plus a redundant await per request.
+
+**LLM-C** — `chat/get-response-metadata.ts` = `completion/get-response-
+metadata.ts` and `chat/map-openai-compatible-finish-reason.ts` =
+`completion/map-openai-compatible-finish-reason.ts` (`diff` exit 0 on each
+pair). Same drift class as LLM-A: a fix to one copy silently bypasses the
+other.
+
+**LLM-D** — `openai-compatible/internal/index.ts` re-exports chat helpers but
+has zero importers (the only `internal` hits repo-wide are the image model's
+`_internal?:` config, unrelated). Law 4 dead code.
+
+---
+
+## GREEN — Fixes
+
+| # | Fix (minimal) |
+|---|---|
+| DB-A | `return requireRow(getMessage(messageId), 'read back message ' + messageId + ' after insert')` |
+| DB-B | Delete the `agent_configs` CREATE TABLE block (`index.ts:46-51`) and its comment |
+| DB-C | Module-level lazy statement cache + `prepare(sql)` helper; replace all 20 `db.prepare(`X`)` sites |
+| LLM-A | Extract inline transform to shared `chat/stream-transform.ts`; model + test both import it |
+| LLM-B | Reuse the base parse when `providerOptionsName === 'openai-compatible'`, else parse the custom key |
+| LLM-C | Keep `chat/` copies; delete `completion/` duplicates; retarget the 2 completion imports to `../chat/` |
+| LLM-D | Delete `openai-compatible/internal/index.ts` |
+
+### Fix details and rejected alternatives
+
+**DB-A** — one-line change matching the pattern at `:87`/`:169`/`:211`.
+Rejected: keep the `!` (inconsistent with DB-5); throw inline (duplicates
+`requireRow`).
+
+**DB-B** — fresh DBs stop creating the table; existing DBs keep an unused table
+(harmless). Rejected: keep + document as reserved (the pre-rebrand caution was
+about live agent definitions — this is dead schema with zero consumers and no
+migration path ever observed); add service functions for it (wiring, not
+removal — out of scope).
+
+**DB-C** — helper is lazy (not import-time), so it avoids any coupling with the
+fail-open `initDatabase` (`index.ts:79-105`) and the `:memory:` test escape
+hatch: `const statementCache = new Map<string, ReturnType<typeof db.prepare>>()`
+plus `function prepare(sql: string)` that memoizes per SQL string. Rejected:
+one module constant per statement (20 named constants, larger diff, import-time
+coupling); leave as-is.
+
+**LLM-A** — the factory closes over per-request state (`isFirstChunk`, text/
+reasoning activity, `toolCalls`, `usage`, `requiredToolKeys`,
+`metadataExtractor`, `finishReason`). Preserve behavior exactly: stale-fragment
+handling, tool-input close-out, flush. Rejected: delete the simulation and rely
+on the 549-line model test (loses targeted unit coverage on the riskiest code);
+keep the simulation (known drift).
+
+**LLM-B** — `const providerOptionsResult = this.providerOptionsName ===
+'openai-compatible' ? baseOptionsResult : await parseProviderOptions({...})` —
+the non-default path (custom provider name) still parses its own key, behavior
+preserved. Rejected: always single-parse (drops the custom-provider key);
+module-level cache (wrong — options are per-request).
+
+**LLM-C** — two small edits in the completion model's import block; no behavior
+change. Rejected: keep duplicates (drift); move both to a third shared dir
+(larger diff, same result).
+
+**LLM-D** — 5-line delete, zero dangling imports. Rejected: keep the dead
+barrel (Law 4 violation).
+
+---
+
+## AUDIT — Verification Plan
+
+1. **Typecheck (HARD GATE ×2):** `cd packages/database && bun run typecheck`
+   and `cd packages/llm-providers && bun run typecheck` — both exit 0.
+2. **Tests (HARD GATE):** `bun test` in both packages — db 11/11, llm 57/57
+   must hold. No test edits expected; `stream-transform.test.ts` continues to
+   pass against the extracted module.
+3. **Static greps (double audit):**
+   - No `getMessage(messageId)!` remains in `service.ts`; `requireRow` used.
+   - No `agent_configs` in `packages/database/src` or any consumer.
+   - No `db.prepare(` remains in `service.ts` (only `prepare(`).
+   - `stream-transform.test.ts` imports the extracted module (no simulation).
+   - `parseProviderOptions` appears once in `getArgs` (plus conditional reuse).
+   - `completion/` duplicates deleted; completion imports resolve via `../chat/`.
+   - `internal/index.ts` gone; zero dangling imports.
+4. **Lint:** `bun x eslint` on changed files in both packages,
+   `--max-warnings 0`.
+5. **Repo hygiene:** full-tree grep for `agent_configs` and `internal/index` —
+   zero hits.
+
+**Runtime risk:** minimal — no behavior change; LLM-A is the only structural
+move and its test suite validates it directly.
+
+---
+
+## Rejected Alternatives (recorded)
+
+- **DB-B:** wiring `agent_configs` into the service layer — pre-rebrand legacy
+  with zero consumers; wiring is explicitly out of scope.
+- **LLM-A:** deleting `stream-transform.test.ts` — the simulation is flawed but
+  the real transform deserves targeted coverage once extracted.
+- **DB-C:** module-level constants per statement — import-time coupling with the
+  fail-open DB init makes the lazy cache strictly safer.
+
+---
+
+## Perfection Loop Status
+
+- **RED:** evidence cataloged above (all line numbers verified against the
+  working tree).
+- **GREEN:** minimal fixes defined, rejected alternatives recorded.
+- **AUDIT:** verification plan complete (gates + static double-audit).
+- **COMPLETE → IMPLEMENT:** approved by user, implemented, verified.
+- **Status:** `verified` — archived.
+
+---
+
+## Resolution
+
+**Approved:** 2026-08-03 (user). **Implemented + verified:** 2026-08-03.
+
+### Changes landed
+
+| # | Change | Files |
+|---|---|---|
+| DB-A | `requireRow` read-back replaces the `!` assertion in `createMessage` | `database/src/service.ts` |
+| DB-B | `agent_configs` CREATE TABLE removed | `database/src/index.ts` |
+| DB-C | lazy statement cache + `prepare()` helper, 20 sites converted | `database/src/service.ts` |
+| LLM-A | inline transform extracted to shared `chat/stream-transform.ts`; model + test both use the real factory | `llm-providers/.../stream-transform.ts` (new), `openai-compatible-chat-language-model.ts`, `stream-transform.test.ts` |
+| LLM-B | single parse when `providerOptionsName === 'openai-compatible'` | `openai-compatible-chat-language-model.ts` |
+| LLM-C | completion/ duplicates deleted, imports retargeted to `../chat/` | completion model + 2 deleted files |
+| LLM-D | dead `internal/index.ts` deleted (+ empty dir removed) | deleted file |
+
+### Scope corrections (documented per review)
+
+1. **DB-B test teardown** — the RED-phase "zero consumers" evidence was
+   partially wrong: the table had ONE consumer — `service.test.ts`'s
+   `beforeEach` teardown (`DELETE FROM agent_configs;`). Production consumers
+   are zero (verified with `grep`, not the missing `rg` binary that silently
+   returned nothing during the RED pass). Corrected consumer count
+   (pre-removal): **0 production consumers + 1 test-teardown consumer**. The
+   teardown line was removed with the table — the AUDIT plan's "no test edits
+   expected" was therefore amended to exactly one teardown line.
+2. **LLM-A test backpressure** — the rewritten test initially hung: a
+   `TransformStream` readable side has high-water mark 1, so writing before
+   reading stalls on backpressure. The helper now drains concurrently (mirror
+   of the real `pipeThrough` consumer).
+
+### Audit results
+
+- Typecheck ×2: `packages/database` and `packages/llm-providers` — both exit 0.
+- Tests: database **11/11 pass** (32 expect); llm-providers **58 pass / 0 fail**
+  (112 expect) — baseline 57, minus 2 simulated transform tests, plus 3 tests
+  driving the real transform.
+- ESLint on both packages: `--max-warnings 0` — clean (import/order auto-fixed).
+- Static double-audit: no `getMessage(messageId)!` (requireRow in place); no
+  `db.prepare(` outside the cache helper; `agent_configs` and `internal/index`
+  zero hits repo-wide; completion imports resolve via `../chat/`;
+  `parseProviderOptions` = 1 call + conditional reuse.
+- Independent review: no correctness issues. One nit applied —
+  `OpenAICompatibleChatTokenUsage` no longer exported (internal to
+  `stream-transform.ts`).
+
+**Runtime risk realized:** the LLM-A test hang (backpressure) was caught during
+verification and fixed before merge — the shared-module test is now strictly
+stronger than the old simulation.
+
+---
+
+## Evidence Amendment (post-archive re-verification, 2026-08-03)
+
+DB-B's removal was re-verified repo-wide with `grep` (the RED pass's `rg`
+usage is what silently reported zero hits — `rg` is not on PATH in this repo's
+bash). Commands and results:
+
+| Command | Result |
+|---|---|
+| `grep -rn 'agent_configs' packages cli sdk common agents evals scripts --include='*.ts'` | exit 1 — **zero source hits** |
+| `grep -rn 'agent_configs' packages cli sdk common agents evals scripts` (all files) | hits ONLY in stale build artifacts: `cli/bin/index.js.map` + `cli/bin/savant-code.exe`, `cli/bin/savant-free.exe` — compiled bundles embedding the PRE-removal source (they also embed pre-0803-002 code like `createAgentConfig`); not consumers |
+| `grep -rn 'agentConfig|agent-config|AgentConfig' ... --include='*.ts'` | hits are local variable names in `sdk/src/impl/database.ts:280-308` (published-agent path) — unrelated to the `agent_configs` table |
+| `grep -rln 'agent_configs' dev/fids/archive dev/session-summaries CHANGELOG.md dev/LEARNINGS.md` | only docs describing the removal |
+
+**Corrected consumer count (DB-B):**
+
+- Pre-removal: **0 production consumers** (no service functions — the old
+  `createAgentConfig`/`getAgentConfig` were already removed in FID-0803-002;
+  no CLI/SDK/agent-runtime/agents references) + **1 test-teardown consumer**
+  (`service.test.ts` `beforeEach`).
+- Post-removal: **zero `agent_configs` references in any source file**.
+
+**Follow-up note (corrected 2026-08-03 by FID-2026-0803-011):** the earlier
+wording "committed .exe binaries" was wrong — `cli/bin/` is gitignored (root
+`.gitignore:42-43` + `cli/.gitignore` `bin`) and `git ls-files cli/bin/` is
+empty, so nothing was ever tracked. The real issue is ~360 MB of stale LOCAL
+build artifacts (Jul 28-31) that consumers existence-check only. Handled by
+FID-2026-0803-011: stale artifacts purged + a `clean` script added.

package/dev/fids/archive/FID-2026-0803-011-build-artifact-hygiene.md

@@ -0,0 +1,169 @@
+# FID: Build Artifact Hygiene (stale `cli/bin/` artifacts)
+
+**Filename:** `FID-2026-0803-011-build-artifact-hygiene.md`
+**ID:** FID-2026-0803-011
+**Severity:** low
+**Status:** analyzed
+**Created:** 2026-08-03
+**Author:** Savant
+
+**Summary:**
+The stale-artifact follow-up flagged in FID-2026-0803-010's amendment was
+re-investigated with git-aware evidence, which **corrected the premise**: the
+`cli/bin/` artifacts are **gitignored, not committed** — so there is no
+repo-pollution problem and no "prevent future commits" work needed. The real
+issues are (1) ~360 MB of stale local build artifacts embedding pre-session
+source that consumers silently use, (2) no way to clean them in one command,
+and (3) an inaccurate note in the FID-0803-010 amendment that must be
+corrected for audit-trail honesty.
+
+---
+
+## RED — Evidence
+
+| # | Location | Issue (summary) |
+|---|---|---|
+| BH-1 | `FID-2026-0803-010` amendment, "Follow-up note" | Says "committed .exe binaries" — false: `cli/bin/` is gitignored (root `.gitignore:42-43`, `cli/.gitignore` `bin`) and `git ls-files cli/bin/` is empty |
+| BH-2 | `cli/bin/` (working tree) | ~360 MB stale artifacts (Jul 28-31): `savant-code.exe` 143 MB, `savant-free.exe` 143 MB, `index.js.map` 21 MB, `savant-code-win32-x64.tar.gz` 52 MB, `tree-sitter.wasm`, `env.json` — embed pre-session source (`createAgentConfig`, old `getSession(id)!`) |
+| BH-3 | `cli/package.json` scripts + `cli/scripts/build-binary.ts` | No `clean` script; every build drops a 21 MB `index.js.map` sibling (bun quirk — emitted despite `--sourcemap=none`) that the release tarball doesn't ship and nothing references |
+
+### Finding details
+
+**BH-1 (docs correction)** — the amendment's follow-up note states "`cli/bin/
+index.js.map` + the committed `.exe` binaries are stale build artifacts". The
+repo-wide grep that found them did not respect `.gitignore`. Git-aware checks:
+`git ls-files cli/bin/` → empty; root `.gitignore:42-43` comments "Compiled CLI
+binaries and their sibling artifacts" with `/cli/bin/`; `cli/.gitignore` has
+`bin`. The only tracked binary in the repo is the intentional vendored
+`cli/../sdk/vendor/ripgrep/x64-win32/rg.exe`. The note must be rewritten to say
+"local stale build artifacts (gitignored — nothing tracked)".
+
+**BH-2 (stale local artifacts)** — the working tree carries ~360 MB of
+Jul 28-31 build output. Consumers only existence-check: the e2e harness
+(`savant-free/e2e/utils/binary-helpers.ts`) resolves `cli/bin/savant-free` and
+`requireSavantFreeBinary()` throws only when missing; `scripts/tmux/tmux-start.
+sh` defaults to `cli/bin/savant-code`; `cli/package.json` bin entry points at
+`./bin/savant-code`. A stale binary therefore runs silently in e2e/tmux/dev.
+All artifacts are regenerable: `bun run build:binary` (cli), `bun savant-free/
+cli/build.ts <version>` (free variant), and root `bun run ci` → `build:savant-
+free`. Deleting them is safe and self-healing.
+
+**BH-3 (no clean path + unwanted build byproduct)** — `cli/package.json`
+scripts (`dev`, `prebuild:agents`, `build:binary`, `release`, `test`,
+`test:tmux-poc`, `typecheck`) have no `clean`. Verified during
+implementation: every build drops a 21 MB `index.js.map` sibling in
+`cli/bin/` even though `build-binary.ts` passes `--sourcemap=none` (bun
+1.3.11 quirk — the file is emitted regardless, timestamped fresh). The
+release tarball ships only `<binary>`, `tree-sitter.wasm`, and `env.json`
+(`.github/workflows/build-release-binaries.yml`), nothing references the map,
+and nothing ever cleaned it. Fix: (a) a `clean` command purging `cli/bin/`,
+and (b) a post-compile removal of the unwanted map in `build-binary.ts`.
+
+---
+
+## GREEN — Fixes
+
+| # | Fix (minimal) |
+|---|---|
+| BH-1 | Rewrite the FID-0803-010 amendment "Follow-up note" with the corrected facts (gitignored, not committed; verified empty via `git ls-files`) |
+| BH-2 | Delete the stale `cli/bin/` artifacts (whole dir — gitignored, regenerated by `build:binary` / `savant-free/cli/build.ts`) |
+| BH-3 | Add `cli/scripts/clean.ts` + `"clean"` script in `cli/package.json`; remove the unwanted `index.js.map` after every compile in `build-binary.ts` |
+
+### Fix details and rejected alternatives
+
+**BH-1** — one paragraph rewrite in the archived FID, preserving the rest of
+the amendment. Rejected: leaving the inaccurate note (violates audit-trail
+honesty — the same standard that drove the DB-B evidence correction).
+
+**BH-2** — `rm -rf cli/bin` (safe: gitignored, nothing tracked, all files
+regenerated by existing build commands). Rejected: "refresh" by rebuilding —
+the binaries are per-version release artifacts; a stale local build serves no
+purpose and the CI workflow builds its own. Rejected: `.gitignore` additions —
+already covered by root `.gitignore:42-43` + `cli/.gitignore`.
+
+**BH-3** — tiny typed script + package.json script; plus a 3-line post-compile
+`rmSync` of `index.js.map` in `build-binary.ts` (unwanted dead weight —
+`--sourcemap=none` is already requested, and neither the tarball nor any code
+ships/references it). Rejected: `rm -rf bin` as a raw script value (not
+portable to cmd on Windows); making `build:binary` clean the WHOLE output dir
+first (would delete the sibling savant-free binary on alternating builds);
+wiring clean into `ci` (CI builds from clean checkouts anyway).
+
+---
+
+## AUDIT — Verification Plan
+
+1. `git ls-files cli/bin/` — still empty after the purge (nothing tracked was
+   ever lost).
+2. Regenerate proof: `bun savant-free/cli/build.ts 0.0.0-dev` — the exact
+   command CI and e2e guidance use — must rebuild `cli/bin/savant-free.exe` +
+   `env.json` + `tree-sitter.wasm` cleanly (proves self-healing).
+3. `cd cli && bun run typecheck` — exit 0 (covers `clean.ts`).
+4. `bun x eslint cli/scripts/clean.ts --max-warnings 0` — clean.
+5. `bun run lint:md` — exit 0 (FID + amended FID-0803-010).
+6. Rebuild re-check: `cli/bin/` contains only `<binary>.exe`, `env.json`,
+   `tree-sitter.wasm` — no `index.js.map`.
+7. Forbidden-name sweep on new/edited docs.
+
+**Runtime risk:** none — deletion is gitignored/regenerable; the only code
+change is a new clean script.
+
+---
+
+## Rejected Alternatives (recorded)
+
+- **BH-2 "refresh"** — rebuilding locally reproduces per-version release
+  binaries that nothing needs; CI builds its own per release.
+- **BH-3 auto-clean in `build:binary`** — alternating savant-code/savant-free
+  builds would clobber each other's output.
+- **Any `.gitignore` change** — the ignore rules already exist and are
+  verified effective.
+
+---
+
+## Perfection Loop Status
+
+- **RED:** evidence cataloged above (git-aware; premise corrected from the
+  original follow-up note).
+- **GREEN:** minimal fixes defined, rejected alternatives recorded.
+- **AUDIT:** verification plan complete (git-state + regeneration + gates).
+- **COMPLETE → IMPLEMENT:** approved for direct implementation ("proceed w/
+  coding"); implemented, verified.
+- **Status:** `verified` — archived.
+
+---
+
+## Resolution
+
+**Implemented + verified:** 2026-08-03.
+
+### Changes landed
+
+| # | Change | Files |
+|---|---|---|
+| BH-1 | FID-0803-010 amendment note corrected — artifacts are gitignored (`git ls-files cli/bin/` empty), not committed | `dev/fids/archive/FID-2026-0803-010-...md` |
+| BH-2 | ~360 MB stale `cli/bin/` artifacts purged (regenerable, nothing tracked lost) | `cli/bin/` (working tree) |
+| BH-3 | `cli/scripts/clean.ts` + `"clean"` script; post-compile `index.js.map` removal in `build-binary.ts` | `cli/scripts/clean.ts` (new), `cli/package.json`, `cli/scripts/build-binary.ts` |
+
+### Premise corrections during implementation
+
+1. **Not committed** — the FID's origin was the 0803-010 follow-up note
+   claiming "committed .exe binaries". Git-aware evidence showed `/cli/bin/`
+   is gitignored (root `.gitignore:42-43` + `cli/.gitignore` `bin`) with zero
+   tracked files; the original note was corrected (BH-1).
+2. **`index.js.map` is regenerated every build, not an orphan** — bun
+   1.3.11 emits the 21 MB map despite `--sourcemap=none`. It is unshipped
+   dead weight (tarball = binary + wasm + env.json only), so it is now
+   removed post-compile.
+
+### Audit results
+
+- `git ls-files cli/bin/` — 0 tracked (nothing lost in the purge).
+- Regeneration proof: `bun savant-free/cli/build.ts 0.0.0-dev` — exit 0;
+  `cli/bin/` now contains exactly `env.json`, `savant-free.exe`,
+  `tree-sitter.wasm` (no `index.js.map`).
+- `cd cli && bun run typecheck` — exit 0 (covers `clean.ts` + `build-binary.ts`).
+- ESLint on both changed scripts: `--max-warnings 0` — clean.
+- `bun run lint:md` — exit 0. Forbidden-name sweep — clean.
+- Independent review: no issues; one non-actionable nit (clean.ts has no
+  guard against a future path re-point, acceptable — dir is generated).

package/dev/fids/archive/FID-2026-0803-012-release-readiness-audit.md

@@ -0,0 +1,162 @@
+# FID: Release-Readiness Audit (bloat trim, doc alignment, eval run + tracking)
+
+**Filename:** `FID-2026-0803-012-release-readiness-audit.md`
+**ID:** FID-2026-0803-012
+**Severity:** medium
+**Status:** verified
+**Created:** 2026-08-03
+**Author:** Savant
+
+**Summary:**
+Release-readiness pass over the v0.0.16 tree. RED uncovered one critical
+correctness break — the **12 benchmark eval fixture JSONs are deleted in the
+working tree but still tracked in git**, so the benchmark runner (`main.ts` →
+`run-benchmark.ts`) cannot run at all — plus two broken entrypoints that
+reference a fixture that never existed (`eval-savant-code.json`), a stale
+Chinese README, and gitignored test-report temp dirs. Operator decisions on
+scope: **keep** root `LEARNINGS.md` (it is the agent learnings library),
+**regenerate** `README.zh-CN.md`, and run the eval in **baseline + evaluate**
+modes with results tracked in reports.
+
+---
+
+## RED — Evidence
+
+| # | Location | Issue (summary) |
+|---|---|---|
+| RR-1 | `evals/benchmark/eval-{codebuff,manifold,plane,saleor}[-hard|-2].json` (12 files) | **Deleted in working tree** but still tracked in git (`D` status) — benchmark fixtures gone, runner cannot run. Restorable via `git restore` (last commit `efc2ee7` v0.0.6) |
+| RR-2 | `evals/benchmark/main.ts:13`, `main-single-eval.ts:9` | Reference `eval-savant-code.json` which **never existed in git** (`git log` empty) — the default entrypoint is broken regardless of RR-1; `main-hard-tasks.ts` correctly references the real `eval-*2.json` fixtures |
+| RR-3 | `evals/v2/tests/.test-reports-md-*` (6 dirs) | Gitignored temp report artifacts from v2 test runs (`git check-ignore` confirms) — dead weight, safe to remove |
+| RR-4 | `README.zh-CN.md` | **Completely stale**: pre-rebrand structure (sections "SavantCode", "Star 历史", "为什么选 SavantCode") — 11 sections vs current README's 12, none matching by name; last updated pre-v0.0.15 |
+| RR-5 | `evals/v2/` harness + reports | Baseline report is stale (3 tasks; `add-fix` task `savant-v2-pure-add-001` exists in `tasks/pure_coding/add-fix/` but is **not in the report**) — needs a fresh run covering all 4 tasks; evaluate mode needs `SAVANT_CODE_API_KEY` (unset) |
+| RR-6 | root `LEARNINGS.md` | Flagged as duplicate earlier — **operator reversal: KEEP** (the agent learnings library; all canonical refs already point to `dev/LEARNINGS.md`, but the root file is the persistent knowledge layer). No action |
+
+### Finding details
+
+**RR-1 (CRITICAL — eval broken)** — `git status` shows all 12 fixture JSONs
+as `D` (deleted, unstaged). `git ls-files evals/benchmark/` confirms they are
+tracked; `git cat-file -e HEAD:evals/benchmark/eval-codebuff.json` succeeds
+(RESTORABLE). `main.ts` / `main-hard-tasks.ts` / `main-single-eval.ts` all
+reference fixtures that are absent on disk, so `bun --cwd evals run-benchmark`
+fails immediately. The v2 harness does not depend on these (self-contained
+tasks), which is why only the v1 benchmark is affected. Fix: `git restore`
+the 12 files from HEAD.
+
+**RR-2 (entrypoint bug)** — `main.ts:13` and `main-single-eval.ts:9` point at
+`eval-savant-code.json`, which has **no git history** (`git log --all` empty,
+`git show HEAD:...` empty). The default entrypoint would still crash after
+RR-1. `main-hard-tasks.ts` is the canonical entry (real `eval-*2.json`
+fixtures). Fix: retarget `main.ts`/`main-single-eval.ts` to the real
+`eval-codebuff.json` fixture (or the `-2` variant).
+
+**RR-3 (temp dirs)** — six `.test-reports-md-*` dirs under
+`evals/v2/tests/` (timestamps 1785017084465..1785017360747) are gitignored
+test output; harmless but bloat. Remove.
+
+**RR-4 (stale translation)** — `README.zh-CN.md` describes a pre-rebrand
+product ("SavantCode", "Star 历史" GitHub-star section, "参与贡献"). The
+current `README.md` is 446 lines with 12 sections (Get Started in 30 Seconds,
+Overview, Key Technologies, Features, Repo Map, Quick Start, CLI Commands,
+ECHO Protocol, Configuration, Validation, Documentation, License). Operator
+decision: **regenerate** the translation to match the current README.
+
+**RR-5 (eval run + tracking)** — v2 baseline mode (no API key; applies golden
+patch, verifies deterministically) + evaluate mode (real agent via
+`SavantCodeClient`, needs `SAVANT_CODE_API_KEY`; operator decision: wire from
+the available `OPENCODE_GO_API_KEY` env var). The stale report omits
+`savant-v2-pure-add-001`. Baseline should cover all 4 tasks; evaluate covers
+the same tasks against the live agent. Results tracked in
+`evals/v2/reports/{report.json,report.md}` + a dated entry in
+`docs/reports/`.
+
+**RR-6 (no-op, documented)** — root `LEARNINGS.md` (345 lines, sections:
+Repository Architecture, ECHO Protocol Core Mechanics, Coding Standard,
+Documentation Patterns, Dev Folder Conventions, Future-Avoidance Notes,
+Environment Baseline, Related Docs) is the cross-session agent knowledge
+library. Operator decision overrides the earlier "delete" vote: **keep as-is.**
+
+---
+
+## GREEN — Solution
+
+1. **RR-1:** `git restore evals/benchmark/eval-*.json` (12 files from HEAD).
+2. **RR-2:** Point `main.ts:13` + `main-single-eval.ts:9` at
+   `eval-codebuff.json` (real, restored fixture) with a comment noting
+   `main-hard-tasks.ts` is the hard-profile entry.
+3. **RR-3:** `rm -rf` the six `.test-reports-md-*` dirs under
+   `evals/v2/tests/`.
+4. **RR-4:** Regenerate `README.zh-CN.md` — full translation of the current
+   `README.md` (same 12-section structure, current v0.0.16 feature set, ECHO
+   Protocol, repo map, validation gates).
+5. **RR-5:** Run `harness:v2` baseline (all 4 tasks, no key) → capture
+   `report.json`/`report.md`; then evaluate mode with
+   `SAVANT_CODE_API_KEY=$OPENCODE_GO_API_KEY` (4 tasks, live agent). Write a
+   dated results doc into `docs/reports/` and note counts in the FID
+   Resolution.
+6. **RR-6:** No change to `LEARNINGS.md` (documented).
+
+## AUDIT — Verification
+
+- `git status` clean on `evals/benchmark/` (fixtures restored, no `D`).
+- `bun --cwd evals typecheck` exit 0.
+- `bun --cwd evals test:v2` (v2 harness suite) exit 0.
+- Baseline report contains **4/4 tasks** (incl. `savant-v2-pure-add-001`).
+- Evaluate report written; failures (if any) documented with cause.
+- `bun x eslint evals/benchmark/main.ts evals/benchmark/main-single-eval.ts --max-warnings 0` clean.
+- `bun run lint:md` exit 0.
+- `README.zh-CN.md` section parity with `README.md` (12 sections, names match).
+- Forbidden-name sweep on new/changed docs (Savant only).
+
+## Resolution — IMPLEMENTED (operator-approved scope: keep LEARNINGS.md, regenerate zh-CN, baseline + evaluate)
+
+### Implemented
+
+1. **RR-1** — `git restore` the 12 deleted eval fixtures (tracked in HEAD;
+   last commit `efc2ee7`). `git status` clean on `evals/benchmark/`.
+2. **RR-2** — `main.ts` and `main-single-eval.ts` retargeted from the
+   never-existing `eval-savant-code.json` to the real `eval-codebuff.json`
+   (`main-single-eval.ts` task id → `filter-system-history`).
+3. **RR-3** — six gitignored `.test-reports-md-*` dirs removed from
+   `evals/v2/tests/`.
+4. **RR-5a (bonus find)** — `add-fix` golden patch had a stale single-line
+   pre-image for the multi-line `add.js`; regenerated → baseline now 4/4.
+5. **RR-5b (bonus find)** — v2 evaluate mode passed **no `agentDefinitions`**,
+   so every run failed instantly with `Invalid agent ID: "savant". Available
+   agents: `. Wired `loadLocalAgents` through `cli.ts → RunnerConfig →
+   SavantAgentRunner → client.run()` (mirrors `evals/benchmark/
+   run-benchmark.ts`).
+6. **RR-5c (bonus find)** — `writeJsonReport` crashed on cyclic provider
+   error objects (`TypeError: Converting circular structure to JSON`); added
+   a circular-safe replacer that flattens `Error` instances.
+7. **RR-4** — `README.zh-CN.md` fully regenerated: complete Chinese
+   translation of the current v0.0.16 `README.md` (same 12-section structure,
+   current feature set; stale pre-rebrand content removed).
+8. **RR-5d** — eval run + tracking: baseline **4/4 PASS** (all tasks incl.
+   `savant-v2-pure-add-001`); evaluate mode proven end-to-end but
+   0/4 due to environmental credential limits (free-tier provider 429
+   rate-limiting + BYOK key rejection; `injectFault` is a documented MVP
+   no-op for the error_recovery task). Results tracked in
+   `docs/reports/savant-code-benchmark-v2-2026-08-03.md` + raw artifacts in
+   `evals/v2/reports/`.
+9. **RR-6** — root `LEARNINGS.md` untouched (operator decision: keep).
+
+### Verification
+
+- evals typecheck exit 0 · v2 test suite **69 pass / 0 fail** (67 baseline
+  + 2 new regression tests: circular-safe `writeJsonReport` RR-5c,
+  `agentDefinitions` forwarding RR-5b) · baseline 4/4 PASS · evaluate
+  harness runs end-to-end (reports written, real model calls, tool
+  execution, trace capture)
+- `bun x eslint evals/v2/src evals/benchmark/main.ts evals/benchmark/main-single-eval.ts --max-warnings 0` clean
+- `bun run lint:md` exit 0
+- `README.zh-CN.md` section parity with `README.md` (12 sections, names match)
+- Forbidden-name sweep on new/changed docs (Savant only)
+
+### Deferred (documented, out of scope)
+
+- Evaluate mode needs a **valid Savant backend key** for a meaningful pass
+  (current env key routes to OpenRouter free tier → 429/BYOK rejection).
+- `injectFault` MVP no-op (`v2/src/runners/savant.ts`) — the
+  error_recovery task cannot pass until fault injection is wired.
+- `cli/release-staging` intentionally retains the "Codecane" display name
+  for staging identification (noted, not changed).