savant-code 0.0.19 → 0.0.20

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

@@ -1,255 +0,0 @@
-# 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

@@ -1,169 +0,0 @@
-# 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

@@ -1,162 +0,0 @@
-# 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).