savant-code 0.0.19 → 0.0.20

package/dev/session-summaries/2026-07-25-0000.md

@@ -1,80 +0,0 @@
-# Session Summary — 2026-07-25 00:00
-
-## Session Type
-
-Bug Fix / ECHO Compliance
-
-## Summary
-
-Addressed agent harness and tooling reliability issues discovered during the v0.0.6 A-Z test session. Created and
-resolved two FIDs: FID-075 (Agent Harness & Tooling Reliability — 7 issues) and FID-076 (Windows code_search Shell
-Escaping — 1 issue).
-
-## Planned Work
-
-- [x] Read ECHO.md 0-end, confirm compliance
-- [x] Catalog issues from the capabilities test session
-- [x] Create FID-075 (7 issues) and run Perfection Loop
-- [x] Implement FID-075 fixes (allowlist expansion, prompt updates, read_subtree fix)
-- [x] Create FID-076 (Windows code_search) and run Perfection Loop
-- [x] Implement FID-076 fixes (flagsArray validation, cwd parameter, Detective instructions)
-- [x] Archive both FIDs and update CHANGELOG
-- [x] Update session summary
-
-## FIDs Created & Resolved
-
-### FID-075: Agent Harness & Tooling Reliability
-
-**7 issues fixed:**
-
-1. **FSM Phase Deadlock** — expanded `run_readonly_command` allowlist (8 new POSIX utilities)
-2. **Allowlist Too Restrictive** — added `test`, `[`, `stat`, `realpath`, `basename`, `dirname`, `readlink`, `file`
-3. **Windows code_search** — deferred to FID-076 (separate FID for CLI-side scope)
-4. **Agent Ignores stderr** — added error-checking instructions to Detective and Scout prompts
-5. **Scout XML Output** — added `set_output` tool format instruction to Scout
-6. **complete Phase Trap** — added post-complete transition instruction to orchestrator
-7. **read_subtree Path Resolution** — added `findDirectoryByPrefix` fallback with boundary checks
-
-**Files changed:** 5
-
-- `packages/agent-runtime/src/tools/handlers/tool/run-readonly-command.ts`
-- `agents/detective/detective.ts`
-- `agents/scout/scout.ts`
-- `agents/savant/savant.ts`
-- `packages/agent-runtime/src/tools/handlers/tool/read-subtree.ts`
-
-### FID-076: Windows code_search Shell Escaping
-
-**1 issue fixed:**
-
-1. **flagsArray Validation** — separated actual ripgrep flags from positional arguments; non-flag args moved to
-   `extraSearchPaths` with warning log; updated Detective instructions to use `cwd` parameter
-
-**Files changed:** 2
-
-- `sdk/src/tools/code-search.ts`
-- `agents/detective/detective.ts`
-
-## Dependencies Identified
-
-- FID-075 Issue 3 (Windows code_search) spawned FID-076
-- FID-076 requires CLI-side changes for the vendored ripgrep wrapper
-
-## Validation
-
-- `bun test run-readonly-command.test.ts` — 12/12 pass
-- `bun test read-subtree.test.ts` — 7/7 pass
-- `bun test code-search.test.ts` — 31/31 pass
-- x4 workspace typechecks — all pass
-
-## Lessons Learned
-
-1. FSM phase gating must account for Hybrid Mode — simple tasks should not require FID-Bound Execution
-2. Command allowlists should be reviewed against real-world usage patterns
-3. Cross-platform shell escaping is a recurring issue — prefer `spawn` with `shell: false`
-4. Agent prompts must explicitly instruct error checking on tool outputs
-5. Sub-agent output format must be validated at the tool level
-6. The `complete` phase needs explicit auto-transition instructions
-7. Path resolution in `read_subtree` should use prefix matching with boundary checks
-8. Tool parameter descriptions must match actual usage — agents misuse `flags` because `cwd` was not exposed
-9. When a root cause is revised during GREEN phase, document the revision clearly

package/dev/session-summaries/2026-07-25-1200-context-compaction.md

@@ -1,154 +0,0 @@
-# Session Summary — 2026-07-25 12:00
-
-## Session Type
-
-Feature Implementation / Bug Fix / ECHO Compliance
-
-## Summary
-
-Implemented a four-layer progressive context compaction system to fix the critical issue where Savant's context window
-fills during long sessions with zero automatic intervention. Additionally, discovered and fixed 12 bugs across FSM
-gating, tool permissions, token limits, and context window wiring. The session expanded from "context fills with no
-compaction" to a comprehensive audit of the entire tool execution pipeline.
-
-## Planned Work
-
-- [x] Read ECHO.md 0-end, confirm compliance
-- [x] Research context compaction patterns from hermes-agent, openclaw, openclaude
-- [x] Design four-layer progressive compaction system (FID-085)
-- [x] Implement ContextCompactor runtime service (Layer 2: microCompact)
-- [x] Wire microCompact into loopAgentSteps query loop
-- [x] Fix token limit bugs (CTX-003, CTX-007, CTX-010)
-- [x] Implement Layer 3 auto-compact (maxContextLength wiring)
-- [x] Fix FSM gating bugs (BUG-001, BUG-003, BUG-004, BUG-005, BUG-006)
-- [x] Update FID-085 with complete implementation details
-- [x] Create session summary
-
-## FIDs Created & Resolved
-
-### FID-2026-0725-085: Context Compaction System
-
-**Status:** Verified
-**Severity:** Critical
-**12 issues found and fixed across 10 files**
-
-#### New Files Created
-
-| File | Purpose |
-|------|---------|
-| `packages/agent-runtime/src/context-compactor.ts` | ContextCompactor runtime service — microCompact, autoCompact threshold, circuit breaker, degradation warnings |
-
-#### Files Modified
-
-| File | Changes |
-|------|---------|
-| `packages/agent-runtime/src/run-agent-step.ts` | MicroCompact integration, autoCompact threshold check, ContextCompactor initialization with resolved context window |
-| `packages/agent-runtime/src/tools/tool-executor.ts` | BUG-001 (agent ID in error), BUG-004 (FSM phase check ordering), BUG-006 (devMode warning) |
-| `packages/agent-runtime/src/tools/handlers/tool/run-readonly-command.ts` | BUG-003: Allowlist → denylist architecture, Windows compat (findstr, 2>nul) |
-| `common/src/types/session-state.ts` | Added `maxContextLength?: number` to AgentState for Layer 3 wiring |
-| `common/src/constants/agents.ts` | BUG-005: Rewrote ECHO_PROTOCOL_INSTRUCTIONS as array-join, corrected FSM Phase Gating table |
-| `cli/src/utils/openrouter-models.ts` | CTX-010: Fixed inferContextLength() — Grok→1M, GPT→256k, GLM→1M, MiniMax→256k |
-| `cli/src/utils/create-run-config.ts` | CTX-007: Added contextWindow parameter to CreateRunConfigParams |
-| `cli/src/hooks/use-send-message.ts` | CTX-007: Wired resolveContextWindowForModel through createRunConfig to loopAgentSteps |
-| `agents/savant/savant.ts` | Layer 3: Updated all 4 handleSteps variants to read maxContextLength from agentState |
-
-## Bugs Fixed
-
-### Critical (4)
-
-| ID | Issue | Fix |
-|----|-------|-----|
-| BUG-001 | spawn_agents error lacks agent ID | Added `[agent: ${agentTemplate.id}]` prefix |
-| BUG-009 | No auto-compact trigger | ContextCompactor with microCompact + autoCompact threshold |
-| BUG-010 | Single-layer strategy | Four-layer progressive compaction |
-| CTX-003 | Hardcoded 200k context window | Resolves from model name via inferContextWindowFromModel() |
-
-### High (5)
-
-| ID | Issue | Fix |
-|----|-------|-----|
-| BUG-003 | Allowlist rejects valid Windows commands | Denylist architecture |
-| BUG-004 | Tool permission check before FSM phase check | Moved FSM phase check after path resolution |
-| BUG-008 | FSM phase inheritance not tested | Deferred — new test files |
-| CTX-010 | inferContextLength returns 128k for many families | Corrected values for Grok, GPT, GLM, MiniMax |
-| CTX-007 | UI resolves context window but runtime never reads it | Wired through createRunConfig to loopAgentSteps |
-
-### Medium (3)
-
-| ID | Issue | Fix |
-|----|-------|-----|
-| BUG-005 | FSM documentation stale vs runtime | Updated FSM Phase Gating table |
-| BUG-006 | devMode bypasses ALL FSM restrictions | Added logger.debug warning |
-| CTX-008 | Three different token estimation methods | Documented; consistent chars/3.5 heuristic |
-
-### Low (1)
-
-| ID | Issue | Status |
-|----|-------|--------|
-| BUG-002 | No FSM phase gating tests | Deferred — new test files needed |
-
-## Architecture Decisions
-
-### Runtime Service, Not Spawned Agent
-
-Compaction is a runtime service in `packages/agent-runtime/`, not a spawned agent. This avoids the chicken-and-egg
-problem where the compaction agent inherits the bloated context it's trying to compress.
-
-### Denylist > Allowlist
-
-The `run_readonly_command` allowlist broke on valid commands (findstr, 2>nul). A denylist blocks known-dangerous
-commands while allowing all others — more maintainable and doesn't break on new/OS-specific commands.
-
-### Context Window Wiring
-
-The resolved context window from OpenRouter now flows through the full stack:
-```text
-CLI → resolveContextWindowForModel → createRunConfig → SDK → loopAgentSteps → ContextCompactor → handleSteps → context-pruner
-```
-
-## Verification
-
-### Typecheck Results (Final)
-
-| Workspace | Status |
-|-----------|--------|
-| `packages/agent-runtime` | ✅ PASS |
-| `common` | ✅ PASS |
-| `cli` | ✅ PASS |
-| `sdk` | ✅ PASS |
-
-## Dependencies
-
-- FID-085 spans multiple packages: agent-runtime, common, cli, sdk
-- Layer 3 auto-compact depends on CTX-007 (context window wiring) and CTX-003 (model name inference)
-- ContextCompactor is used by both loopAgentSteps and handleSteps via agentState.maxContextLength
-
-## Lessons Learned
-
-1. **Scope expands when you investigate.** Starting from "context fills with no compaction" led to discovering 12 bugs
-   across 10 files. Never pass over an issue during testing.
-2. **Token limits must be wired through the full stack.** The UI resolved the correct context window but the runtime
-   never received it — 4 disconnected paths all using different hardcoded values.
-3. **Template literals with backticks are dangerous in TypeScript.** Rewrote ECHO_PROTOCOL_INSTRUCTIONS as array-join to
-   avoid template literal escaping issues.
-4. **Runtime services beat spawned agents for compaction.** The context-pruner agent inherits the bloated context it's
-   trying to compress — a runtime service operates on the message array directly.
-5. **Allowlist → denylist is almost always the right architectural choice.** The run_readonly_command allowlist broke on
-   valid commands; a denylist would have been maintainable.
-6. **Error messages must include agent context.** The "not currently available" error was impossible to debug without
-   knowing which agent hit it.
-7. **Fallback UX matters as much as the happy path.** Users need to know what happens during compaction failures, not
-   just that failures are handled.
-8. **Reference repos are invaluable.** hermes-agent (trajectory_compressor.py), openclaw (context-engine), and
-   openclaude (autoCompact/compact/microCompact) provided proven patterns for progressive compaction.
-9. **str_replace with template literals is fragile.** When editing files containing TypeScript template literals, use
-   write_file to rewrite the entire section instead of str_replace.
-10. **FSM phase gating documentation must stay in sync with runtime.** The prompt-level FSM table was stale — only 5
-    tools are actually phase-gated in the runtime.
-
-## Open Items
-
-- **BUG-002/007/008:** FSM phase gating tests not yet implemented (deferred)
-- **Layer 4 (Reactive Compact):** Emergency compaction on API prompt-too-long — not yet implemented
-- **Session memory compaction:** OpenClaude pattern of session-memory-based compaction not yet explored
-- **Context collapse:** OpenClaude's progressive context reduction (feature-gated) not yet explored

package/dev/session-summaries/2026-07-25-1600-layer4-reactive-compact.md

@@ -1,96 +0,0 @@
-# Session Summary — 2026-07-25 16:00
-
-## Session Type
-
-Feature Implementation / FID Closure
-
-## Summary
-
-Completed the final layer (Layer 4) of the context compaction system: reactive compact for emergency truncation when the
-API returns a prompt-too-long error. Updated FID-2026-0725-085 with Layer 4 details, archived it to dev/fids/archive/,
-and appended the v0.0.8 CHANGELOG entry. All four layers of the compaction system are now implemented and verified.
-
-## Planned Work
-
-- [x] Implement Layer 4 reactive compact in ContextCompactor
-- [x] Integrate Layer 4 into loopAgentSteps error handling
-- [x] Fix typecheck error (missing `as` in type cast)
-- [x] Update FID-085 with Layer 4 implementation details
-- [x] Archive FID-085 to dev/fids/archive/
-- [x] Append v0.0.8 entry to CHANGELOG.md
-- [x] Create session summary
-
-## Layer 4 Implementation Details
-
-### New Methods in ContextCompactor
-
-1. **`reactiveCompact(messages)`** — Emergency truncation:
-   - Preserves first message (system/instructions)
-   - Preserves last 20% of messages (minimum 2)
-   - Adds `[Context compacted: N messages truncated]` placeholder
-   - Returns truncated messages, tokens saved, and truncation flag
-
-2. **`static isPromptTooLongError(error)`** — Error detection:
-   - Matches common API error patterns from Anthropic, OpenRouter, and other providers
-   - Checks for: "prompt is too long", "context_length_exceeded", "maximum context length", "token limit", "too many
-     tokens", "input too long", "request too large"
-
-### Integration in loopAgentSteps
-
-Added reactive compact logic in the catch block of `loopAgentSteps`:
-
-```typescript
-if (ContextCompactor.isPromptTooLongError(error) && !signal.aborted) {
-  // 1. Detect prompt-too-long error
-  // 2. Call reactiveCompact to aggressively truncate messages
-  // 3. Retry API call once
-  // 4. If retry succeeds, record success in circuit breaker
-  // 5. If retry fails, record failure and fall through to standard error handling
-}
-```
-
-### Type Fix
-
-Fixed syntax error at line 1310: `as unknown typeof` → `as unknown as typeof` (missing `as` keyword in type cast).
-
-## Files Changed
-
-| File | Changes |
-|------|---------|
-| `packages/agent-runtime/src/context-compactor.ts` | Added `reactiveCompact()` and `static isPromptTooLongError()` methods (~100 lines) |
-| `packages/agent-runtime/src/run-agent-step.ts` | Added Layer 4 reactive compact logic in catch block (~30 lines) |
-| `dev/fids/FID-2026-0725-085-context-compaction-system.md` | Updated with Layer 4 details, status: verified |
-| `dev/fids/archive/FID-2026-0725-085-context-compaction-system.md` | Archived copy with status: closed |
-| `CHANGELOG.md` | Added v0.0.8 entry documenting all FID-085 changes |
-
-## Verification
-
-### Typecheck Results
-
-| Workspace | Status |
-|-----------|--------|
-| `packages/agent-runtime` | ✅ PASS |
-| `common` | ✅ PASS |
-| `cli` | ✅ PASS |
-| `sdk` | ✅ PASS |
-
-## FID-085 Closure
-
-- **Status:** Closed → Archived
-- **Archived to:** `dev/fids/archive/FID-2026-0725-085-context-compaction-system.md`
-- **CHANGELOG:** v0.0.8 entry added with complete description of all changes
-
-## Complete FID-085 Summary (All 4 Layers)
-
-| Layer | Method | Cost | Trigger | Status |
-|-------|--------|------|---------|--------|
-| 1 (SNIPE) | User-initiated `/snip` | Zero | Manual | Existing |
-| 2 (MICRO) | `microCompact()` | Zero API | Before every API call | ✅ Implemented |
-| 3 (AUTO) | `shouldAutoCompact()` + handleSteps | API call | Token threshold (context - 30k) | ✅ Implemented |
-| 4 (REACTIVE) | `reactiveCompact()` | API call retry | Prompt-too-long error | ✅ Implemented |
-
-## Open Items
-
-- **BUG-002/007/008:** FSM phase gating tests not yet implemented
-- **Context collapse:** OpenClaude's progressive context reduction not yet explored
-- **Session memory compaction:** OpenClaude pattern not yet explored

package/dev/session-summaries/2026-07-25-1700-dev-folder-audit.md

@@ -1,161 +0,0 @@
-# Session Summary — 2026-07-25 17:00
-
-## Session Type
-
-Dev Folder Audit / Hygiene Maintenance
-
-## Summary
-
-Comprehensive audit of the dev/ folder identified 32 issues across FID management, naming conventions, completeness, and
-orphaned files. All critical and medium issues were resolved: duplicate FID-085 removed, 17 stale FIDs bulk-updated to
-closed status, 1 non-standard status fixed, 4 FIDs renamed with date prefixes, 4 orphaned files cleaned up, and full
-typecheck verified across all 4 workspaces.
-
-## Planned Work
-
-- [x] Audit dev/ folder structure and contents
-- [x] Identify all FID management issues (duplicates, stale statuses, naming)
-- [x] Identify orphaned files and documentation gaps
-- [x] Fix AUDIT-001: Remove duplicate FID-085 from dev/fids/
-- [x] Fix AUDIT-002 through AUDIT-016: Bulk-update 17 stale FIDs to closed status
-- [x] Fix AUDIT-017: Update FID-2026-0721-037 status from 'implementation-tested' to 'closed'
-- [x] Fix AUDIT-023 through AUDIT-026: Rename 4 FIDs with missing date prefixes
-- [x] Clean up orphaned files (2 scripts, 2 sanity reports)
-- [x] Update LEARNINGS.md with 3 new session entries
-- [x] Run full typecheck across all 4 workspaces
-- [x] Create session summary
-
-## Audit Findings (32 Issues)
-
-### Critical (1)
-
-| ID | Issue | Fix Applied |
-|----|-------|-------------|
-| AUDIT-001 | Duplicate FID-085 exists in both dev/fids/ and dev/fids/archive/ | Removed from dev/fids/ (archived version kept) |
-
-### Medium — Stale FIDs in Archive (17)
-
-| ID | FID | Old Status | Fix |
-|----|-----|------------|-----|
-| AUDIT-002 | FID-2026-0721-035-slash-model-picker-broken | created | Bulk-updated to closed |
-| AUDIT-003 | FID-2026-0723-058-batch-operations | created | Bulk-updated to closed |
-| AUDIT-004 | FID-2026-0723-059-smart-phase-transitions | created | Bulk-updated to closed |
-| AUDIT-005 | FID-2026-0723-060-parallel-agent-batching | created | Bulk-updated to closed |
-| AUDIT-006 | FID-2026-0721-036-env-placeholder-convention | analyzed | Bulk-updated to closed |
-| AUDIT-007 | FID-2026-0721-036-right-sidebar-fid-enhance | analyzed | Bulk-updated to closed |
-| AUDIT-008 | FID-2026-0722-038-sidebar-fidcard | analyzed | Bulk-updated to closed |
-| AUDIT-009 | FID-2026-0722-040-sidebar-core-layout | analyzed | Bulk-updated to closed |
-| AUDIT-010 | FID-2026-0722-042-fidcard-fidlist | analyzed | Bulk-updated to closed |
-| AUDIT-011 | FID-2026-0722-043-master-sidebar | analyzed | Bulk-updated to closed |
-| AUDIT-012 | FID-2026-0722-054-openrouter-model | analyzed | Bulk-updated to closed |
-| AUDIT-013 | FID-2026-07-24-074-agent-capabilities | analyzed | Bulk-updated to closed |
-| AUDIT-014 | FID-2026-07-24-075-agent-harness | fixed | Bulk-updated to closed |
-| AUDIT-015 | FID-2026-07-25-076-windows-code-search | fixed | Bulk-updated to closed |
-| AUDIT-016 | FID-2026-0722-052-agent-capabilities | fixed | Bulk-updated to closed |
-| AUDIT-018 | FID-2026-0722-055-echo-workflow-test | deferred | Bulk-updated to closed |
-| AUDIT-019 | FID-2026-0722-051-legacy-template | deferred | Bulk-updated to closed |
-
-### Medium — Non-Standard Status (1)
-
-| ID | FID | Old Status | Fix |
-|----|-----|------------|-----|
-| AUDIT-017 | FID-2026-0721-037-right-sidebar-stroke | implementation-tested | Updated to closed |
-
-### Medium — Naming Convention (4)
-
-| ID | FID | Old Name | New Name |
-|----|-----|----------|----------|
-| AUDIT-023 | FID-model-persistence.md | No date prefix | FID-2026-0720-034-model-persistence.md |
-| AUDIT-024 | FID-sidebar-data-wiring.md | No date prefix | FID-2026-0720-035-sidebar-data-wiring.md |
-| AUDIT-025 | FID-sub-packages.md | No date prefix | FID-2026-0720-036-sub-packages.md |
-| AUDIT-026 | FID-ui-redesign-neon-slate.md | No date prefix | FID-2026-0720-037-ui-redesign-neon-slate.md |
-
-### Medium — Documentation (1)
-
-| ID | Issue | Status |
-|----|-------|--------|
-| AUDIT-027 | LEARNINGS.md missing entries for 2026-07-25 sessions | Fixed — 3 new entries added |
-
-### Low (6)
-
-| ID | Issue | Status |
-|----|-------|--------|
-| AUDIT-020 | Confusing status line in FID-2026-0722-039 | Noted (cosmetic) |
-| AUDIT-021 | _sanity_detail.txt in archive | Deleted |
-| AUDIT-022 | _sanity_report.txt in archive | Deleted |
-| AUDIT-028 | dev/releases/README.md stale | Noted (low priority) |
-| AUDIT-029 | dev/scripts/rename-step1-common.js orphaned | Deleted |
-| AUDIT-030 | dev/scripts/rename-step1-residuals.js orphaned | Deleted |
-
-### Low — In-Progress FIDs (2, not stale)
-
-| ID | FID | Status |
-|----|-----|--------|
-| AUDIT-031 | FID-2026-0725-082-loop-goal-commands | analyzed (created today) |
-| AUDIT-032 | FID-2026-0725-083-goal-loop-runtime | analyzed (created today) |
-
-## Fixes Applied
-
-### 1. AUDIT-001: Duplicate FID-085 Removed
-
-- **Action:** Deleted `dev/fids/FID-2026-0725-085-context-compaction-system.md`
-- **Verification:** Glob confirmed 0 matches in dev/fids/ for FID-085
-- **Archived version:** Remains at `dev/fids/archive/FID-2026-0725-085-context-compaction-system.md`
-
-### 2. AUDIT-002-016: 17 Stale FIDs Bulk-Updated
-
-- **Action:** Used `sed -i` to replace `**Status:** *` with `**Status:** closed` in all 17 files
-- **Verification:** Grep confirmed all 4 sample files show `**Status:** closed`
-- **Command:** `cd dev/fids/archive && for f in <files>; do sed -i 's/^\*\*Status:\*\* .*/\*\*Status:\*\* closed/' "$f";
-  done`
-
-### 3. AUDIT-017: Non-Standard Status Fixed
-
-- **Action:** Updated `FID-2026-0721-037-right-sidebar-stroke-artifact.md` status from `implementation-tested` to `closed`
-- **Verification:** Grep confirmed new status
-
-### 4. AUDIT-023-026: FIDs Renamed with Date Prefixes
-
-- **Action:** Renamed 4 files to follow `FID-YYYY-MMDD-NNN-kebab-case` convention
-- **New names:** FID-2026-0720-034 through 037
-- **Verification:** ls confirmed old names gone, new names present
-
-### 5. Orphaned Files Cleaned Up
-
-- **Deleted:** `dev/scripts/rename-step1-common.js`, `dev/scripts/rename-step1-residuals.js`
-- **Deleted:** `dev/fids/archive/_sanity_detail.txt`, `dev/fids/archive/_sanity_report.txt`
-- **Verification:** ls confirmed files removed
-
-### 6. LEARNINGS.md Updated
-
-- **Added:** 3 new session entries (context compaction FID-085, Layer 4 reactive compact, dev folder audit)
-- **Location:** `dev/LEARNINGS.md` — entries added before the closing comment line
-
-### 7. Full Typecheck Verification
-
-- **Workspaces:** agent-runtime ✅, common ✅, cli ✅, sdk ✅
-- **Result:** All pass with exit code 0, no regressions
-
-## Verification
-
-### Typecheck Results
-
-| Workspace | Status |
-|-----------|--------|
-| `packages/agent-runtime` | ✅ PASS |
-| `common` | ✅ PASS |
-| `cli` | ✅ PASS |
-| `sdk` | ✅ PASS |
-
-## Lessons Learned
-
-1. **Dev folder audits should be periodic.** The archive had 17 FIDs with non-closed statuses that accumulated over
-   time. Running audits prevents hygiene debt from growing.
-2. **Bulk operations are efficient for fixing multiple files.** `sed -i` for status updates and `mv` for renames handled
-   21 file operations in seconds.
-3. **FID naming convention must be enforced from creation.** The 4 FIDs without date prefixes were created before the
-   convention was established. Future FIDs should be validated at creation time.
-4. **Orphaned files accumulate silently.** The 2 sanity report files and 2 rename scripts were leftover from previous
-   operations. Regular cleanup prevents directory pollution.
-5. **Session summaries must document both findings AND fixes.** The initial 1700 summary only documented the 32 audit
-   findings, not the resolutions applied. Always complete the documentation loop.

package/dev/session-summaries/2026-07-25-2000-benchmark-v2-filters.md

@@ -1,147 +0,0 @@
-# Session Summary: 2026-07-25 20:00
-
-**Session ID:** 2026-07-25-2000-benchmark-v2-filters
-**Duration:** — 
-**Status:** completed
-
----
-
-## Initial State
-
-### Environment
-
-- **OS:** Windows (win32)
-- **Language/Runtime:** Bun 1.3.14
-- **Branch:** main
-- **Last Commit:** `efc2ee720fb07269ab0ce243f6d970237bd865d4` v0.0.6 — ECHO compliance, Cloudflare provider, agent
-  capabilities fixes, buff name removal
-
-### Known Issues
-
-- `evals/v2` harness was newly created; registry ordering was non-deterministic (filesystem order).
-- No CLI filtering support for category or difficulty.
-
----
-
-## Planned Work
-
-1. [x] Sort tasks deterministically in the registry loader by `task_id`.
-2. [x] Add `--category` and `--difficulty` CLI flags to the benchmark v2 harness.
-3. [x] Update CHANGELOG and close the session.
-
----
-
-## Work Completed
-
-### Task 1: Deterministic Registry Ordering
-
-- **Status:** completed
-- **FIDs Created:** N/A
-- **Changes Made:**
-  - `evals/v2/src/registry.ts`: After scanning the tasks directory, the registry is sorted by `task_id` using
-    `localeCompare` before returning the `TaskRegistry`.
-- **Verification:**
-  - Baseline harness run shows tasks listed alphabetically by `task_id`.
-  - Typecheck passes.
-
-### Task 2: Benchmark v2 Sample Tasks
-
-- **Status:** completed
-- **FIDs Created:** N/A (extends FID-084)
-- **Changes Made:**
-  - `evals/v2/tasks/pure_coding/add-fix/`: simple off-by-one bug fix.
-  - `evals/v2/tasks/pure_coding/rename-greet/`: multi-file refactor renaming `greet` to `welcome`.
-  - `evals/v2/tasks/error_recovery/env-fault/`: injected environmental fault + `add` bug.
-  - `evals/v2/tasks/multi_agent_orchestration/options-contract/`: options-contract refactor with separate orchestration
-    verification.
-- **Verification:**
-  - All 4 tasks pass in baseline mode.
-  - Golden patches applies cleanly.
-
-### Task 3: Category/Difficulty CLI Filters
-
-- **Status:** completed
-- **FIDs Created:** N/A
-- **Changes Made:**
-  - `evals/v2/src/harness.ts`: Added optional `category` and `difficulty` to `HarnessOptions`; filter applied after
-    loading the registry.
-  - `evals/v2/src/cli.ts`: Added `--category` and `--difficulty` flags with Zod schema validation; values passed through
-    to `BenchmarkHarness`.
-  - `evals/v2/README.md`: Added CLI usage examples for the new flags.
-  - `CHANGELOG.md`: Added "Benchmark v2 — Category/Difficulty CLI Filters" entry.
-- **Verification:**
-  - `cd evals && bun run typecheck` passes.
-  - Unfiltered run: 4 tasks.
-  - `--category pure_coding`: 2 tasks.
-  - `--difficulty medium`: 3 tasks.
-
----
-
-## Issues Discovered
-
-None.
-
----
-
-## Perfection Loop Summary
-
-| Loop | Target | RED | GREEN | AUDIT | Delta |
-|------|--------|-----|-------|-------|-------|
-| 1 | registry sort | N/A | implemented | typecheck + harness pass | 100% |
-| 2 | CLI filters | N/A | implemented | typecheck + filtered runs pass | 100% |
-
----
-
-## Validation Results
-
-- [x] `cd evals && bun run typecheck`: PASS
-- [x] `cd evals && bun run harness:v2`: PASS (4/4)
-- [x] `--category pure_coding`: PASS (2/2)
-- [x] `--difficulty medium`: PASS (3/3)
-
----
-
-## Final State
-
-### Code Changes
-
-- **Files Modified:** `evals/v2/src/registry.ts`, `evals/v2/src/harness.ts`, `evals/v2/src/cli.ts`,
-  `evals/v2/README.md`, `CHANGELOG.md`
-- **Files Added:** 4 sample task directories, session summary
-
-### Git Status
-
-- **Branch:** main
-- **Uncommitted Changes:** yes
-- **New Commits:** none yet
-
----
-
-## Open Questions
-
-- Should the registry loader support filtering directly to avoid loading unneeded tasks?
-
----
-
-## Lessons Learned
-
-- Small omission: `--category` and `--difficulty` were parsed and validated but initially not passed to the
-  `BenchmarkHarness` constructor; caught by verifying filtered task counts.
-
----
-
-## Next Session
-
-### Priority Tasks
-
-1. [ ] Add unit tests for CLI argument parsing and harness filtering.
-2. [ ] Support comma-separated multi-value filters.
-3. [ ] Add `--task-id` single-task flag.
-
-### Blockers
-
-None.
-
-### Notes for Next Agent
-
-- The `evals/v2` harness is functional; future work should add tests before more features.