Animus_Ferric

KO | EN

gitlite — search

#hacktoberfest #react #go #android #machine-learning #rust #deep-learning #linux #macos #awesome #awesome-list #vue #openai #open-source

(★ 15)

Present State of the Animus Project: Animus Ferric — a Rust-native agentic coding harness purpose-built for small local models (1B-14B GGUF). Harness-owned constrained decoding, deterministic model-scale policies, trajectory-first observability.

Animus_Ferric Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Animus Ferric

A local-first agentic coding harness written in Rust, purpose-built for **small local models (1B–14B GGUF)**.

**Licensing information for all Animus Project components held at https://github.com/crussella0129/Animus/blob/main/LICENSE**

Ferric is the Rust synthesis of the Animus lineage — [Animus](https://github.com/crussella0129/Animus) (Python), [Animus_Prion](https://github.com/crussella0129/Animus_Prion) (Go), and [fev](https://github.com/crussella0129/fev) (Go) — built on three convictions:

1. **The harness should own decoding.** Constrained generation (JSON-Schema / regex / CFG grammars) is driven end-to-end in the agent loop, so malformed tool calls are *impossible* rather than repairable.
2. **Behavior should scale to the model, deterministically.** A pure function maps a model profile (params, quant, context, measured capability level) to a run policy (protocol, plan granularity, turn budgets, tool count). Small models get small steps.
3. **The trajectory is the source of truth.** Every session writes a versioned JSONL trace — full conversation, tool calls, untruncated tool output, execution chain — replayable and diffable. If it isn't in the trace, it didn't happen.

Rust is not an implementation detail: the visible, demonstrable chain of ownership over state and execution is part of how you verify you control the agent.

## Documentation

Full docs live in **[`docs/`](docs/README.md)**. They are also assembled into a
book (via [mdBook](https://rust-lang.github.io/mdBook/), like *The Rust Book*) —
run `mdbook serve --open` from the repo root, or read the same pages on GitHub
below. The book's reading order is defined in [`docs/SUMMARY.md`](docs/SUMMARY.md).

- **[Getting Started](docs/getting-started.md)** — install, prerequisites, and the external steps (engine install, `ferric server`) before your first run. Includes a no-model `--mock` quickstart.
- **[Demo Guide](docs/demo-guide.md)** — a copy-paste walkthrough of every feature, each marked *offline* or *needs a model*.
- **[Command Reference](docs/commands.md)** · **[Configuration](docs/configuration.md)** — every command/flag; `.ferric/config.toml`, `Animus.md`, `.ferricignore`, hooks.
- Deep dives: [llama.cpp engine](docs/llama-cpp.md) · [testbench](docs/testbench.md) · [ICM delegation](docs/icm.md) · [agentic cron](docs/cron.md) · [Ornstein research](docs/ornstein.md) · [multimodal](docs/multimodal.md).

## Workspace

| Crate | Responsibility |
|---|---|
| `ferric-core` | Shared types + the deterministic scale function (ModelProfile → RunPolicy) |
| `ferric-trace` | Versioned TraceEvent schema, flush-per-event JSONL sink, tolerant reader |
| `ferric-provider` | Async `Provider` trait (constraint-carrying) + deterministic mock; real backends behind feature flags |
| `ferric-guard` | Hardcoded security: workspace boundary, permission checker, deny lists |
| `ferric-tools` | Tool trait, registry chokepoint, builtin file tools |
| `ferric-cli` | The `ferric` binary |

## Build

You need a recent stable Rust toolchain (`rustup`, edition 2024). Inference backends are **feature-gated** — pick the one(s) you want:

```sh
git clone https://github.com/crussella0129/Animus_Ferric.git
cd Animus_Ferric

# Recommended: the OpenAI-compatible HTTP valve — the constrained-decoding path.
# Talks to llama.cpp (llama-server), Ollama, or vLLM.
cargo build --release -p ferric-cli --features backend-openai
```

The binary lands at `target/release/ferric` (`ferric.exe` on Windows). A build with no backend feature still supports the offline/mock workflows; commands that need a real model tell you to rebuild with `backend-openai`.

**Put `ferric` on your `PATH`** (the examples below assume it is). The portable way — identical on Windows, Linux, and macOS — is `cargo install`, which builds in release *and* drops the binary into `~/.cargo/bin` (rustup already adds that directory to your `PATH`):

```sh
cargo install --path crates/ferric-cli --features backend-openai --force
# or use the wrapper, which does exactly this:
#   Linux/macOS:  ./tools/install.sh
#   Windows:      .\tools\install.ps1
```

> [!IMPORTANT]
> `cargo install` copies a **snapshot**. After you `git pull` or edit source, re-run it — a plain `cargo build` refreshes `target/release/` but **not** the copy on your `PATH`, so the `ferric` you invoke can silently lag the code (this is how a months-old binary kept offering a `--backend` flag that source had already removed). `--force` re-installs even though the version string (`0.1.0`) never changes.

## Using Ferric

| Command | What it does |
|---|---|
| `ferric server up\|status\|doctor\|down` | Launch & manage the local OpenAI-compatible inference server (the HTTP valve), bound to `127.0.0.1` only. Registration happens only after the spawned process returns HTTP 200. |
| `ferric query "<prompt>"` | Run one workspace-scoped agent turn against a local model. |
| `ferric mcp` | Run an MCP-stdio server exposing one tool, `ferric_query`, to MCP clients (Claude Code, Cursor, an IDE). Workspace/backend/model are launch-time-fixed flags; each call runs the full constrained agent loop. *ADR-046.* |
| `ferric bench ltd` | Measure & diagnose tool-calling fire rate for a model (or a fleet — see below). |
| `ferric bench full` | Run the L0–L6 capability ladder and calibrate a model's `measured_level`. |
| `ferric bench autonomy` | Run the versioned 24-task internal repository-work baseline with retained traces, executable grading, and recovery evidence. |
| `ferric trace cat <file.jsonl>` | Render a session trace as a human-readable log. |

A typical loop — bring a server up, point Ferric at it, work, tear it down:

```sh
ferric server up --engine llama-server --model your.gguf
ferric server status                                        # prints base URL + health
ferric query "list the Rust files and summarize lib.rs"     # auto-discovers the server
ferric server down
```

> [!NOTE]
> If you run `ferric server up --tailscale` on a machine for the first time, you must authorize Tailscale Serve on your Tailnet. The command will output an authorization link that you must click to unblock the proxy and register the server globally.

`query` and `bench` **auto-discover** the running server from `.ferric/server.json` (or your global `APPDATA` directory) — no `--api-base` needed. To target a server you didn't launch (e.g. an already-running Ollama), pass `--api-base http://localhost:11434/v1`. By default `query` runs the **constrained** path, which is the reliable one for small models.

`server up` fails closed when a local/global registration already exists, the
target port is occupied, or a llama.cpp model/projector is not a regular file.
It keeps ownership of the child until the engine-specific health endpoint
returns HTTP 200; `status` also requires both a live registered PID and HTTP
health.

`ferric query` also takes workspace-local, guard-permitted files as input with `--file` (repeatable): text/code files fold into the prompt (works on any model), while image/audio/video attach as content parts when you declare `--modality` and the model can read them (Gemma 3n on the OpenAI valve). Attachments are bounded and pass through the same sensitive-path and `.ferricignore` checks as tool reads. See [docs/multimodal.md](docs/multimodal.md).

Streaming is on by default. Add `--no-stream` when a caller needs buffered output instead of live text and activity updates.

**Builtin model tools** (all workspace-scoped and security-checked through the guard). The always-on **core** (Ring 0) is `read_file`, `list_dir`, `write_file`, `make_dir`, `edit_file`, `delete_path`, `search_files`, `move_path`, and `copy_file`. **Ring 1** adds `find_files` and read-only `git_read`. **Ring 2** adds the structured mutation tools `multi_edit`, `apply_patch`, and `git_write`. Host `shell_exec` and `manage_task` controls are intentionally absent from every model grammar; the explicit `!cmd`/`/run` path in interactive chat is human-only. Tool vocabularies widen as a model proves it can call them reliably, and `ferric query --max-ring 0` pins any model to the smallest grammar (restrict-only; to widen, prove it with `ferric bench ltd` so `measured_level` promotes it).

Beyond the hardcoded guard, a project can drop a **`.ferricignore`** in the workspace root (gitignore-flavored — `secrets/`, `*.pem`, `data/private`) to put more paths off-limits to the agent. It is *additive-only*: it can only ever add denials on top of the hardcoded floor, never relax it (ADR-068), and the file is itself write-protected so the agent can't edit away its own restrictions.

## Test it with your own models

Ferric works with large and small models alike, but *how well* a small model drives the tools varies — so don't take it on faith, **measure it**. The testbench runs every tool many times, classifies *why* it misses, and grades the result, so you can dial a model down until quality drops.

**1. Bring a model.** Any of:

```sh
# llama.cpp — point the launcher at a GGUF on disk (needs `llama-server` on PATH):
ferric server up --engine llama-server --model /path/to/your-model.gguf [--mmproj mmproj.gguf] [--ctx 8192]
```

**2. Benchmark it** under the constrained path, and write a report:

```sh
ferric bench ltd --model <name> --protocol grammar --iterations 20 --report report.md
```

**3. Read the verdict.** `report.md` gives each tool a success rate, a **failure taxonomy** (`wrong_tool` / `malformed_args` / `no_action` / `parse_error`), and an acceptability band — **solid** (≥90%) / **marginal** (≥70%) / **unreliable** (<70%). Add `--protocol native` to compare the unconstrained path on the same model.

**4. Calibrate a whole fleet at once.** `--models <a,b,c>` benches each model and ranks them into one leaderboard, sorted best→worst — so you can pick the smallest model that's still *solid*:

```sh
ferric bench ltd --models qwen2.5-coder:7b,llama3.1:8b,llama3.2:1b --protocol grammar --report fleet.md
```

```
# Fleet Leaderboard
| Model              | Protocol        | Success | Rate   | Verdict |
|--------------------|-----------------|---------|--------|---------|
| qwen2.5-coder:7b   | ConstrainedJson | 50/50   | 100.0% | solid   |
| llama3.1:8b        | ConstrainedJson | 50/50   | 100.0% | solid   |
| llama3.2:1b        | ConstrainedJson | 50/50   | 100.0% | solid   |
```

That run is real: the constrained path holds at **100% down to a 1B model**, where the same model's *native* tool-calling collapses to 22% — which is the whole point of harness-owned decoding.

**5. Calibrate the rings.** `--calibrate-rings` benches a model **ring by ring** and reports the highest ring it reliably drives — the recommended `--max-ring` to run it at (`ferric bench ltd … --calibrate-rings`). It's the demonstrated-reliability promotion: a model *earns* a wider grammar by proving it on the bench. Full walkthrough: [docs/testbench.md](docs/testbench.md).

## Portability

CPU-first. The baseline target includes Raspberry Pi / Orange Pi class aarch64 hardware; CI gates `cargo check --target aarch64-unknown-linux-gnu`. CUDA (NVIDIA, Jetson) and AMD paths are planned as specialized backends.

## Status

Active development. The single inference backend used by Ferric:

- **`backend-openai`** — an OpenAI-compatible HTTP valve (`llama.cpp` / vLLM) that enforces a harness-authored JSON-Schema constraint server-side. This is the constrained-decoding thesis working for small GGUF models — out-of-process, with pure Rust on Ferric's side. **It's the default and the reliable path.**

The action protocol (`NativeTools` / `ConstrainedJson` / `TextXml`) is chosen from the backend's real capabilities. Development follows a sprint-loop protocol; see `decisions.md` for ADRs and `agent-tasks/` for the ledger.

## Development timeline

Ferric is built in **sprints** — a Research → Plan → Build → Test → Loop protocol. The durable record lives in `decisions.md` (the full ADR log) and `agent-tasks/` (the task ledger); this is the human-readable summary. *Newest last — append the next sprint here as it closes.*

- **Sprint 0 — Foundations** (2026-06-10). Cargo workspace + six crates; the deterministic scale function (ModelProfile → RunPolicy); versioned JSONL trace; hardcoded security (workspace boundary, deny lists); builtin file tools; CLI stub. *ADR-001–009.*
- **Sprint 1 — The agent loop** (2026-06-11). Turn loop with policy budgets, a structured task-complete terminator, a repetition guard, and retry backoff; a command structure with no chat catch-all. *ADR-010–014.*
- **Sprint 2 — Action grammar & calibration** (2026-06-13). The unified `ActionProtocol` grammar; per-tier output-token budgets; the `bench` L0–L6 capability ladder as the sole producer of `measured_level`. The server-side constrained-decoding **hang** surfaces and is quarantined opt-in. *ADR-015–020.*
- **Sprints 3–6 — Exploration** (mid-June 2026). An embedded PyO3/PyTorch inference path and a first-generation toolbench. This era drifted from the *harness-owns-decoding* thesis — and set up the realignment.
- **Sprint 7 — The realignment** (2026-06-23). The PyO3/PyTorch backend removed; external engines reached only through the out-of-process HTTP valve. The constraint reinstated, capabilities made honest, and the `NativeTools` / `ConstrainedJson` / `TextXml` trichotomy chosen from each backend's *real* capabilities; toolbench rebuilt around the active protocol. *ADR-021–023.*
- **Sprint 8 — Launcher + testbench** (2026-06-23). The `ferric server` lifecycle manager (llama-server default, Ollama pluggable, runfile auto-discovery) and the diagnostic toolbench (failure taxonomy + verdict bands). **Thesis proven on a real model: constrained 100% vs native 0% on the same Ollama model.** *ADR-024.*
- **Sprint 9 — Fleet calibration** (2026-06-23). `ferric bench ltd --models` sweeps a fleet into one sorted leaderboard. **The constraint holds 100% down to a 1B model where native collapses to 22%** — it extends the usable model floor to 1B. A native-`content` fallback closes the "Ollama returns the call as text" gap; the mistral.rs 0.8.15 probe confirmed the hang is fixed upstream but the constraint still isn't enforced. *ADR-025.*
- **Sprint 10 — Multimodal "any file" input** (2026-06-24). `ferric query --file` takes any file: text/code folds into the prompt (any model); image/audio/video attach as OpenAI content parts, capability-gated by `--modality` + the backend's `supports_media` (the valve carries media; the in-process path doesn't). Additive `Message.media` (media-free messages serialize unchanged); a dependency-free base64 encoder. The pure pipeline is fully unit-tested; the live-media heartbeat (a real model reading a clip) is deferred until a multimodal server is stood up.

- **Sprint 11 — mistral.rs constrained-decoding spike** (2026-06-24). Settled an open question: `MistralRsProvider` had been *stripping* the decoding constraint since the s3 pivot, so the sprint-9 probe (ADR-025) had measured the stripped path, not enforcement. Wired the constraint through (`set_constraint`) and re-probed — mistralrs 0.8.15 **still hangs** llguidance on GGUF even for a trivial schema (5-minute engine timeout). The ADR-020 hang is *not* fixed; the wiring was reverted (no regression), mistral.rs stays text-only, and the HTTP valve remains the sole constrained path. *ADR-027.*

- **Sprint 12 — `search_files` tool** (2026-06-24). Added the missing content-search primitive a small coding agent leans on most: a workspace-scoped, guard-checked, dependency-free substring search (`relpath:lineno:line`, sorted + capped, binary/noise-dir skipping) gated at `Nano` so every model gets it. Mirrors the `list_dir` pattern; six temp-workspace tests.

- **Sprint 13 — complete Ring 0** (2026-06-24). Added the two missing core tools — `edit_file` (surgical replace) and `delete_path` (guard-scoped, `recursive`-gated) — then re-ran the toolbench to *measure* that the full navigate/mutate core still fires reliably. Introduces the **tool-rings** model: a curated core that widens as a model proves itself, with the active rings = the grammar.

- **Sprint 14 — formalize the rings** (2026-06-24). Made the tool-rings model real: every tool declares a `ring` (0 = the navigate/mutate core), `ring_for_tier` sets the capability ceiling (and honours `measured_level`, so reliability — not size — widens the set), and `tools_for_policy` **trims from the outer ring first** so the core is never dropped. Fixes the latent alphabetical `max_tools` cap. The active rings literally *are* the constrained grammar. *ADR-028.*

- **Sprint 15 — `--max-ring` override** (2026-06-24). The explicit "control exactly which rings" lever: `ferric query`/`bench ltd --max-ring N` caps the active rings independent of tier (`--max-ring 0` = the core-only grammar). Restrict-only — widening past a model's capability stays earned via `measured_level`. Proven end-to-end via the trace's offered-tools. *ADR-028 (amended).*

- **Sprint 16 — ring calibration** (2026-06-24). `bench ltd --calibrate-rings` sweeps a model ring-by-ring and reports the highest ring it reliably drives — the recommended `--max-ring`. Closes the rings loop: a model *earns* a wider grammar by proving it on the bench (the demonstrated-reliability promotion). *ADR-028.*

- **Sprint 17 — durable promotion** (2026-06-25). Closed the profile read-back loop: `model_profiles.json` was written by `bench full` but never read. Now `ferric bench ltd --calibrate-rings --profile-dir` *persists* the earned ring, and `ferric query --profile-dir` *reads the profile back* — a proven model auto-runs at its earned tier (`measured_level`) and ring (`calibrated_ring`), no manual flag. Safe no-op without a profile. *ADR-029.*

- **Sprint 18 — round out Ring 1** (2026-06-25). Added `find_files` (find by *name*, the companion to `search_files`' content search) and `copy_file` (the organize complement to `move_path`), making Ring 1 a coherent four-tool "find & organize" set. Both fire `solid` in the re-bench — growing the ring didn't cost reliability. *ADR-028 (amended).*

- **Sprint 19 — seed Ring 2** (2026-06-25). Added `multi_edit` (`ring: 2`) — an ordered, atomic batch of first-occurrence edits to one file (more than the Ring-0 `edit_file`, still reliably emittable vs a unified diff). Added `bench ltd --params-b` so calibration can bench at a chosen tier and reach Ring 2 (`--params-b 20` → Medium → rings 0–2). *ADR-028 (amended).*

- **Sprint 20 — the full agentic loop, validated on a real model** (2026-06-26). The L0–L6 ladder (`ferric bench full`) tests multi-turn *task completion*, but its runner could only reach `--mock` or the mistral GGUF backend (which hangs under constraint). Wired the openai backend through (`ferric bench full --backend openai`), fixed a verification bug it surfaced (the `task_complete` terminator wasn't credited), and ran it: **qwen2.5-coder:7b passes all of L0–L6 on the constrained path → `measured_level 6` (Small→Large)**. The first end-to-end validation that the constrained multi-turn loop completes real tasks, not just single tool calls — and the demonstrated-reliability promotion now runs on real data. *ADR-030.*

- **Sprint 21 — fleet agentic capability map** (2026-06-26). `bench full --models` runs the full L0–L6 loop across the fleet and prints a `measured_level` leaderboard. The map: **qwen2.5-coder:7b → 6 (Large); llama3.1:8b → 5 (Medium); llama3.2:1b → none (fails L0)**. The honest finding: a 1B fires single tool calls at 100% but **can't complete a multi-turn task** — single-shot reliability ≠ agentic capability; and the code-tuned 7B beats the larger general 8B. *ADR-030 (amended).*

- **Sprint 22 — why the 1B isn't an agent** (2026-06-26). Diagnosed (from the trace) *why* `llama3.2:1b` fails L0: **repeat-not-terminate** (it re-calls `list_dir` instead of `task_complete`) and **semantic flailing** (15 `make_dir`s, no progress). Sharpened the repetition nudge into a direct imperative — but it **didn't move the 1B** (still `measured_level: none`), so the ceiling is a real capability limit, not wording. The nudge ships anyway (helps mid-tier models, can't regress capable ones). *ADR-031.*

- **Sprint 23 — llama.cpp first-class** (2026-06-26). Validated Ferric on full **llama.cpp** (`llama-server`) for the first time — we have now fully removed inference from ollama and switched exclusively to `llama.cpp` due to speed. The constrained loop runs on it at **100% Ring-0 tool-call fire rate**, with a context window as wide as you want (`-c`), the multimodal path (`--mmproj`), and a single edge-ready binary (Jetson / Pi). Guide: [docs/llama-cpp.md](docs/llama-cpp.md). *ADR-032.*

- **Sprint 24 — multimodal goes live** (2026-06-26). Ran an image end-to-end for the first time (the marquee goal deferred since sprint 10): a generated red square → `ferric query --file --modality image` → `llama-server --mmproj` (SmolVLM-500M) → the vision encoder processed it, and the model correctly answered **"Red."** The `image_url`/base64 content-parts mapping is proven against real pixels; no Ferric code change needed. Caveat: a sub-1B VLM degrades under the JSON grammar (use a bigger VLM or an unconstrained describe). *ADR-033.*

- **Sprint 25 — Gemma 4 E4B is the reference model** (2026-06-27). The data shows a **~4B agentic floor** (1B → none, 7B → 6, 8B → 5), so the fix for small models isn't a workaround — it's a *capable* one. Validated **Gemma 4 E4B** (4B, multimodal, function-calling) on llama.cpp: **`measured_level 5`** (matches the 8B), Ring-0 toolbench **100% solid**, and it **describes an image *inside* the constrained agentic loop** (`task_complete("a solid red rectangle")`) — closing the ADR-033 caveat with no harness change. Edge-feasible q4. *ADR-035.* (Use a GPU build for speed — CPU timed out the simplest level.)

- **Sprint 26 — audio modality** (2026-06-27). Validated **audio** end-to-end (the other half of multimodal): a Windows-TTS speech clip → `ferric query --file speech.wav --modality audio` → `llama-server` (Gemma 4's Conformer encoder) → **`task_complete("The quick brown fox jumps over the lazy dog.")`** — an exact transcription *inside* the constrained agentic loop. So Ferric multimodal is now **vision + audio**, both live on the reference model. No Ferric code change (the `input_audio` mapping was already correct). *ADR-036.*

- **Sprint 27 — no-progress guard** (2026-06-27). Closed ADR-031's second, still-unguarded failure mode — **"semantic flailing"** (the model calls the same tool with *different* args every turn and never completes, grinding to `max_turns`). The repetition guard misses it by design (it hashes name **+ args**); the new `ProgressGuard` tracks the same-tool-**name** streak (arg-insensitive) and stops early with a precise `StopReason::NoProgress`. Honest scope: it bounds wasted compute on a stuck model and sharpens the bench diagnostic — it does not lift a model's capability ceiling. *ADR-037.*

- **Sprint 28 — repeated-failure guard** (2026-06-27). Completed the loop-hardening **guard family**. The repetition guard (identical calls) and no-progress guard (same tool name) both key off the *actions* a model emits; neither catches a model emitting a *different* tool every turn that *all error* (bad paths, denials) and never recovers — both reset, so it grinds to `max_turns`. The new `FailureGuard` keys off tool *results*: consecutive all-errored turns → an early stop with `StopReason::RepeatedFailure`. Same honest scope — it bounds wasted compute and sharpens the diagnostic, not a model's capability ceiling. *ADR-038.*

- **Sprint 29 — `apply_patch` rounds out Ring 2** (2026-06-27). Pivoted from loop guards back to the **tool rings**. Added the second Ring-2 ("plan & apply structured changes") tool: `apply_patch` applies a context-located unified diff to one file, atomically. Unlike `multi_edit` (which only hits the *first* occurrence), a hunk's surrounding context **disambiguates** which occurrence to edit — and unified diffs are a format models emit naturally. Medium-tier models now offer 12 tools (Ring 0+1 + `multi_edit` + `apply_patch`). *ADR-039.*

- **Sprint 30 — Ornstein, increment 1** (2026-06-27). Began the **Animus** direction by hardening the loop's research story. Built **Ornstein**'s heart (recovered from the s1 roadmap) — a **quarantined summarizer** (`ferric-research`): untrusted content → a model with **no tools, no memory**, constrained to a **data-only** schema → a typed, provenance-tagged `ResearchDigest`. The quarantine is *structural* — it reuses Ferric's constrained valve, so a prompt-injection in the content can only ever surface as quoted **data**, never an action. See [`docs/ornstein.md`](docs/ornstein.md). *ADR-040.*

- **Sprint 31 — Ornstein increment 2** (2026-06-27). Ornstein is *one funnel, many sources*: the s30 quarantine is the universal sink; research is now multi-source. Added the keystone **`Retriever`** trait (`plane`/`available`/`retrieve`, async for the later network planes) + the first source — a **Local-FS retriever** — and the `research()` pipeline that runs a query **source → quarantine → provenance-tagged digest**. Even local files are untrusted (a downloaded doc, a NAS share), so every source routes through the funnel. Build order: Local FS ✅ → Tailnet/NAS → Web+container. See [`docs/ornstein.md`](docs/ornstein.md). *ADR-041.*

- **Sprint 32 — Ornstein increment 3** (2026-06-28). The second source plane: a **Tailnet/NAS-FS retriever** that searches a *remote* tailnet device's filesystem over **Tailscale SSH** (`tailscale ssh` for Linux boxes, plain `ssh -p` for Termux), feeding matches to the same quarantine. The security core — `ssh` runs its command through the *remote* shell, so the research query is single-quote-escaped against **remote command injection** — is fully unit-tested; the live SSH E2E is deferred (no tailnet SSH target reachable at build time). Build order: Local FS ✅ → Tailnet/NAS ✅ → Web. See [`docs/ornstein.md`](docs/ornstein.md). *ADR-042.*

- **Sprint 33 — Ornstein research orchestrator** (2026-06-28). The "one funnel, many sources" payoff: `research_all(planes, provider, query)` runs a query across every available source plane at once, quarantines each chunk, **dedups by source before the model call** (a file reachable from two planes costs one inference, not two), and returns the aggregated digests plus a per-plane outcome report (what ran / was offline / counts). Composes the local + tailnet planes with zero pipeline change. See [`docs/ornstein.md`](docs/ornstein.md). *ADR-043.*

- **Sprint 34 — CaMeL-lite sink-policy primitive** (2026-06-28). Co-designed with the user: flow control on top of the quarantine. `TaintSet` marks a digest's text as tainted; `SinkPolicy::decide(permission, tainted)` decides whether a `Write`/`Execute` tool call whose args derive from tainted data may proceed — **all three enforcement modes ship** (`Deny` / `RequireApproval` / `Warn`, caller's choice). Pure primitive only — an end-to-end test proves it would `Deny` an injected write once wired; the live gate lands at the dispatch chokepoint with the research→loop wiring. See [`docs/ornstein.md`](docs/ornstein.md). *ADR-044.*

- **Sprint 35 — expert review + refactor** (2026-06-29). The first full-project audit: what does Ferric need to become an operational, competitive, safe product, staying efficient for edge/personal-compute deployment? Full findings (file:line cited) in `sprints/s35/sprint-research/research-report.md`; four immediately-effective fixes shipped — a **read-side sensitive-file guard** (`.env`/SSH keys/cloud credentials can no longer be read into the plaintext trace), **`ferric server` edge-tuning flags** (`--threads`/`--gpu-layers`/`--batch-size` for Jetson/RPi-class latency tuning), **`mistralrs` rev-pinned** (was floating on `branch = "master"`), and **`reqwest` switched to `rustls-tls`** (no native OpenSSL dependency for ARM cross-compilation). Everything larger (MCP, a new chat mode, shell/git tools, streaming, session resume) is explicitly deferred with reasons, not silently dropped. *ADR-045.*

- **Sprint 36 — `ferric mcp`** (2026-07-03). The "ADR-005 security call" that blocked ADR-012 since sprint 1 is answered, and the MCP-stdio server it unblocks is built. `ferric mcp` exposes **exactly one** MCP tool, `ferric_query` (`{prompt, files?}`) — never Ferric's individual builtins and never workspace/backend/model as per-call parameters (those are launch-time-fixed CLI flags, so the containment guarantee is *structural*: a client can't redirect the workspace or swap the model because the wire protocol has no field for it). Every `tools/call` runs the same constrained agent loop `ferric query` drives, inheriting the guard/permission checks, tool rings, and per-call tracing. Hand-rolled JSON-RPC 2.0 (no `rmcp` dependency); the mistral.rs in-process hang was explicitly dropped rather than re-chased. *ADR-046.*

- **Sprint 37 — streaming inference** (2026-07-03). Fills ADR-003's reserved `complete_stream` extension point. `ConstrainedJson` returns every turn's completion — including the final answer — as one opaque JSON object, so raw token deltas aren't human-readable; a small incremental scanner (`ConstrainedJsonScanner`) extracts exactly two live signals as text streams in: an early "which tool is being called" activity signal, and — only for the `task_complete` answer — the live-decoded `summary` text, handling JSON escape sequences correctly across arbitrary chunk boundaries. `Provider::complete_streaming` ships with a default implementation (every non-overriding provider behaves identically to `complete()`, zero code change); `OpenAiProvider` gets a real SSE implementation via `Response::chunk()` (no new dependency). `ferric query --stream` is opt-in this increment; the constrained-decoding guarantee is unchanged — buffering is for display only, dispatch still runs on the fully-parsed completion. *ADR-047.*

- **Sprint 38 — persistent configuration + `Animus.md`** (2026-07-04). User-chosen: "persistent config and Animus.md (much like claude.md but for Animus)". `ferric query`/`ferric mcp` now resolve their tunables (backend, model, params_b/quant/family/ctx/temperature, max_ring, profile_dir, stream) as **CLI flag > project `.ferric/config.toml` > user config > hardcoded default** — a bounded, named field list (never a generic key-value map), so config can't touch security/guard/denylist policy. A plan-critic pass caught (and this sprint fixed, before shipping) a subtle masking-hazard class: a config-only-set value silently invisible to the code deciding behavior — twice, beyond the field it was actually reviewing (`BackendOpts.backend`'s own leftover clap default, and the ADR-029 profile-lookup key `model_key`, which had to be re-derived from the *post-merge* value). `Animus.md` — a project-root, freeform, user-authored instructions file — is read (no parsing) and folded into the system prompt as a distinct block; trusted context, not Ornstein-quarantined. *ADR-048.*

- **Sprint 39 — session resume** (2026-07-04). User-chosen, scoped down mid-research to resuming an **interrupted, still-incomplete task** (process crashed/killed mid-loop; continue the SAME task with more turns, no new prompt needed) — not a chat-continuation mechanism. Two new/extended trace events close the reconstruction gaps: `Event::SessionPrompt` (the original system+user text was never recorded before) and the terminator's `ToolCall` traced in every protocol (closes a pre-existing `NativeTools` audit gap where a session's summary was recorded nowhere at all). `ferric-loop::replay()` reconstructs the in-memory turn history from a trace file — a real design correction surfaced only during implementation: `TurnEnd` is written *before* dispatch, so a turn is only safely committed once a *later* `TurnStart` confirms its dispatch actually finished. `ferric query --resume <path>` replays and continues; a trace that already reached any stop reason is rejected (`AlreadyStopped`) — that gate is the real ADR-011 boundary. The user's own mid-research pivot reframed the backlog's `--save-interval` into **context-budget compaction** (`RunPolicy.prompt_budget_tokens` is computed and traced but never enforced) — big enough to become its own dedicated **sprint 40**, not bundled here. *ADR-049.*

- **Sprint 40 — context-budget compaction** (2026-07-04). Carved out of sprint 39's research when the user reframed `--save-interval`, unprompted, into a real gap: `RunPolicy.prompt_budget_tokens` was computed and traced but never enforced. New `HistoryCompactor` (`crates/ferric-loop/src/compact.rs`) is an always-on, no-CLI-flag mechanism (mirrors the repetition/no-progress/failure guards' precedent) that folds older turns into one model-summarized message once a session's `input_tokens` crosses 85% of budget, always preserving the most recent 2 turns verbatim. A foreground plan-critic pass caught the sprint's riskiest arithmetic before it shipped: an originally-planned `turn_offset` re-keying scheme was replaced with direct absolute-turn-number tracking (`Vec<(u32, usize)>`) in both the compactor and `replay()`'s reconstruction — simpler, and it closed a real gap where `replay.rs` was discovered to discard the turn number entirely. `replay()` was extended (a required fix, not optional) so a `--resume` of a compacted-then-killed session reconstructs the SHRUNK history, not the full pre-compaction one — proven by a real compact→kill→replay→resume round-trip test, mirroring sprint 39's own C-010 precedent. The summarizer reuses the SAME provider (no second, cheaper model exists in Ferric's one-local-model architecture); a failed summarization is non-fatal (logs a Note, skips the fold). *ADR-050.*

- **Sprint 41 — container architecture** (2026-07-09). User picked chat mode, then reframed it into a platform-wide question: should Animus run containerized (Docker/k8s/n8n), with chat/Ornstein/MCP in **nested** containers via Docker-in-Docker? Research found a correction: literal DinD is a security anti-pattern for isolating untrusted content specifically (2026 practice — incl. Docker's own **Docker Sandboxes**, GA Jan 2026 — uses **microVM-class sandboxes** for that use case), while ordinary **sibling containers** handle deployment flexibility (one machine → datacenter) — two different tools for two different problems the framing had conflated. The user chose "container architecture only" (chat mode → sprint 42). Shipped: **ADR-051** (the correction + the topology decision); a **`ferric-core`** multi-stage Dockerfile co-locating the `ferric` binary — built with `--features backend-openai` — and a prebuilt `llama-server`, so ADR-005's loopback pin between harness and backend is preserved by keeping them in ONE container (never split across a container boundary); a `docker-compose.yml` skeleton (`ferric-core` real, Ornstein/chat as marked stubs). **Docker Desktop was installed mid-sprint**, clearing the multi-sprint "no containerizer" blocker (had stalled Ornstein's web-retriever increment since sprint 30) and upgrading validation from design-only to a live `docker build` + `docker compose config`. *ADR-051.*

- **Sprint 42 — raw chat mode** (2026-07-09). The ADR-011-revision's second half (after `ferric mcp`), motivated by Animus IDE sending natural-language change requests conversationally. The user chose the **hybrid talk + escalate** shape. `ferric chat` is a REPL: **talk mode** (the default) is the harness's FIRST unconstrained-completion path — a single `provider.complete()` with no tools and no constraint, output text-only, printed and appended to history, **never dispatched** (the safety is structural: the talk path lives in the CLI and never touches `ferric-loop::run()`, which stays always-constrained). **`/do <request>`** escalates a turn into the existing constrained agentic loop (`run_with_provider` + `ferric-guard` + guards + trace, exactly as `ferric query`), USER-initiated only — the model can never self-escalate into acting (ADR-005). A foreground plan-critic caught two load-bearing issues pre-lock: a fixed mock script can't drive a stdin-length-driven REPL (→ a fresh per-turn mock), and `run()`'s per-call `SessionStart..SessionEnd` envelope can't be nested (→ each `/do` gets its own agentic trace file, mirroring `ferric mcp`). The structural-safety guarantee is proven both by a unit test (`talk_request` has empty tools + no constraint) and a black-box test (a talk line that *looks* like a tool call dispatches nothing). *ADR-052.*

- **Sprint 43 — Animus Launch increment 1** (2026-07-09). The first slice of a named Animus-suite pillar (the GECK successor): a project bootstrapper. Research found GECK (`~/GECK`) is Python-only and does macro-prompt scaffolding but **no git bootstrapping** — so Launch's distinct value is the deterministic, **LLM-free** "interview → real git repo (main+dev) + a sprint-loop-ready skeleton" flow. The user chose to build **both** the scaffolder and the interactive interview this increment. A new **`animus-launch`** library crate: `scaffold(&LaunchSpec)` refuses-to-clobber (never over a non-empty dir / non-dir path), creates the dir + a seed skeleton (README from goal, `.gitignore`, `agent-tasks/` with goal-derived tasks, `decisions.md`), and runs `git` as a checked closed-subcommand sequence (init → commit with a fixed identity so CI-without-identity works → `branch -M main` → `branch dev`). A **`ferric launch`** subcommand drives it: supplied flags skip the matching interview question, anything missing is asked on stdin (prompts to stderr so stdout stays the report). The key architectural point: Launch is user-run and LLM-free, so `ferric-guard`'s agent-containment doesn't apply — the sole safety property is refuse-to-clobber. A foreground plan-critic caught the nested-`agent-tasks/`-dir and clobber-semantics gaps pre-lock. *ADR-053.*

- **Sprint 45 — Ornstein Web Retriever (Inc 4)** (2026-07-13). Built the Web Retriever plane for Ornstein. Added a highly restricted microVM-class Docker sandbox (`crates/ferric-research/src/sandbox.rs`) that drops all capabilities and routes traffic through an allowlist proxy (`docker/squid.conf`). Implemented `WebRetriever` using `wget` to safely fetch URLs into the quarantine, ensuring all untrusted external content remains isolated from Ferric's execution environment. *ADR-055.*

- **Sprint 46 — Loop Research-Phase Wiring & Sink Policy (Inc 5)** (2026-07-13). The final CaMeL wiring. Moved `sink.rs` to `ferric-guard` to form a true dependency tree (`ferric-tools` → `ferric-guard` → `ferric-core`). Wired `TaintSet` and `SinkPolicy` all the way down through `ferric-cli`'s `--research` and `--sink-action` flags into `registry.execute`. A tool call attempting a Write or Execute sink with tainted arguments is now intercepted and evaluated according to the chosen sink policy (`deny`, `warn`, `requireapproval`). *ADR-056.*

- **Sprint 47 — Testing System** (2026-07-13). Built the 4-tier testing system to provide regression safety for the fast-moving loop. Increment 1: **Golden Trace Testing** (`ferric trace verify`) reconstructs the `MockProvider` and checks a deterministic trace for event mismatches. Increment 2: **Containerized E2E Harness** (`tools/run-e2e.sh`) launches `ferric-core` inside Docker to execute a mock query. Increment 3: **Coverage Scripts** (`tools/run-coverage.sh`) leverages `tarpaulin` to enforce the 80% coverage threshold. *ADR-057.*

- **Sprint 48 — Animus Launch Increment 2** (2026-07-13). Extended `ferric launch` to natively support generating project skeletons based on an explicit project type (`Rust`, `Python`, `Web`, or `Empty`). After scaffolding the repository, it now features an auto-hand-off mechanism that prompts the user if they'd like to immediately begin execution with the Ferric agent using their goal as the prompt, eliminating the friction between bootstrapping a repo and starting the Sprint 1 loop. *ADR-058.*

- **Sprint 49 — Streamlining Streaming & Usability Assessment** (2026-07-13). Delivered `talk-mode` streaming for `ferric chat` and `ferric/streamDelta` JSON-RPC notifications for `ferric mcp` to solve laggy IDE UI feedback. Assessed project usability, concluding that it is functionally usable, natively LLM-free, and contained, but requires container operationalization and compaction tuning next. *ADR-059.*

- **Sprint 50 — Native Tailscale Integration** (2026-07-13). Added a `--tailscale` flag to `ferric server up`. Ferric now natively orchestrates Zero-Trust WireGuard tunneling by shelling out to `tailscale serve <port>` immediately after the engine (llama-server/Ollama) binds to loopback. This allows secure, authenticated, off-device access to the local inference API without exposing public firewall ports. *ADR-060.*

- **Sprint 51 — Skill Loader via MCP Prompts** (2026-07-13). Added dynamic Knowledge Skill loading. `ferric mcp` now scans `.ferric/skills/*/SKILL.md` and serves them via the MCP `prompts/list` and `prompts/get` protocols. Agents connected to Ferric (Cursor, Claude Code, etc.) can now discover and inject project-specific skills dynamically into their context. *ADR-061.*

- **Sprint 52 — Advanced File Tooling & ICM Adaptation** (2026-07-14). Adapted the file tooling to better support the Interpretable Context Methodology (ICM) across all tiers. Promoted `copy_file`, `move_path`, and `search_files` to Ring 0 (core) so Nano models can navigate workspace hierarchies, proportionally scaling up tier tool caps (e.g., Nano: 10, Small: 14) to accommodate. Implemented `start_line` and `end_line` pagination in `read_file` to allow small-context models to read large files safely. Validated with comprehensive tests across `ferric-core`, `ferric-cli`, and `ferric-tools`. *ADR-062.*

- **Sprint 54 — Ornstein Validation & IDE Integrations** (2026-07-14). Resolved `cargo clippy` warnings in `ferric-cli` and `ferric-loop` to pass CI. Validated the Ornstein `WebRetriever` using `--mock` to bypass local environment restrictions. Cloned and rebranded `Animus_IDE` to point to OpenVSX and stripped Microsoft telemetry to set up a clean, agentic-ready IDE fork.

- **Sprint 55 — `ferric mcp --resume` support** (2026-07-14). Added the `--resume <path>` flag to `ferric mcp` to allow resuming an interrupted task session over MCP. The resume state is verified, stored, and passed down directly into the first `ferric_query` `tools/call`.

- **Sprint 56:** Per-tier compaction tuning. `HistoryCompactor` triggers now scale natively per tier in `RunPolicy`.

- **Sprint 57 — Chat Mode Refinements** (2026-07-14). Integrated `rustyline` into `ferric chat` for robust REPL history and line editing, improving interactive workflow for conversation-driven escalations.

- **Sprint 59 — `shell_exec` tool & CaMeL wiring** (2026-07-15). Delivered the `shell_exec` tool (Ring 2) and addressed ADR-045's deferred requirements. Extended the `Tool` trait with `target_commands()` and added `ferric-guard::check_command` to screen commands against static denylists prior to child process execution. Wired the CaMeL sink policy `TaintSet` into the `Registry::execute` chokepoint to govern `Write` and `Execute` tool calls according to the user's `--sink-action` flag.

- **Mid-July engine hardening** (2026-07-16). A cluster of foundational improvements that landed in this window (their internal sprint numbers were reused later, so they're grouped here in chronological order): **CLI consolidation** — the `bench` and `toolbench` commands merged into `ferric bench ltd` / `ferric bench full`; a **multi-arch `ferric-core` container** (amd64 + arm64, dynamic `llama-server` asset resolution); **Plan Mode** — `ActionProtocol::Plan`, a read-only grammar-constrained protocol with a `submit_plan` terminator instead of `task_complete`; an **async `shell_exec` refactor** — `tokio::process::Command` under `block_in_place`, so runaway processes no longer block the executor thread or OOM on unbounded pipes; and **loop decoupling** — the monolithic ~400-line driver in `ferric-loop/src/run.rs` split into a testable `LoopState` with an async `step() -> TurnOutcome`.

- **Sprint 62 — Schema-Enforced Chain of Thought** (2026-07-16). Replaced the nested JSON schema representation for `action` with a flattened, highly stable wrapper that explicitly forces the `thought` field *before* tool parameters. Fixed a critical agent hallucination where the missing JSON schema `description` metadata (stripped by `llama-server`) caused the LLM to misuse `make_dir` repeatedly for file creation; explicitly injected `registry_tools` descriptions into the system prompt for constrained environments.

- **Sprint 63 — Real-Time Thought Streaming** (2026-07-16). Added real-time streaming of the model's scratchpad reasoning (the `thought` field). Expanded `StreamDelta` to include `Thought(String)` and added a state machine to `ConstrainedJsonScanner` to incrementally stream the field as text arrives. Rendered live thought outputs in dim ANSI gray (`\x1b[90m`) in `ferric query`, `ferric chat`, and `ferric mcp` to visually distinguish the agent's internal planning from standard tool output.

- **Sprint 64 — Ferric HTTP API and VS Code extension** (2026-07-16). Designed and implemented the Ferric HTTP API (`/v1/query/stream`) to securely stream Server-Sent Events (SSE) representing agentic `StreamDelta`s (thoughts, tool calls, and text summaries). Built `animus-ferric`, a lightweight, native VS Code extension tailored for `Animus_IDE`, wired to stream the agent's internal monologue and tool operations directly into the IDE's Language Model Chat interface.

- **Sprint 65 — Graceful Interrupts (Stops)** (2026-07-17). Implemented `StopReason::Interrupted` logic across the harness. Passed `cancel_flag` of `Arc<AtomicBool>` securely from `ferric-cli` drivers all the way down into `ferric-loop`'s engine block and `ferric-provider` traits. Wired a `tokio::signal::ctrl_c()` handler to toggle the state of the flag and efficiently polled this state during intensive streaming network I/O operations (`tokio::select!`). This successfully establishes a safe early-termination protocol for the agent that securely flushes any trace outputs mid-flight, fully reconstructing the loop state for possible future resumption, all without destabilizing the application or generating panic unwinds.

- **Sprint 66 — Time Travel (Revert)** (2026-07-17). Delivered full workspace-and-trace reversion using a lightweight Git orchestration crate (`ferric-vcs`). During every `TurnEnd` trace event, `ferric-loop` sequentially stashes the entire workspace tree as an orphaned, detached commit (ignoring local branch history) tagged strictly to the current trace session (`refs/ferric/<session>/<turn>`). Users can invoke `ferric revert <trace_file> <turn_id>` via the CLI, triggering an immediate and exact restoration (`git restore --worktree --staged --source=<tag> .`) combined with complete untracked file deletion (`git clean -fd`), while automatically truncating future traces in the source `.jsonl` file to reset the agent's contextual memory precisely.

- **Sprint 67 — Configurable Hooks** (2026-07-17). Introduced a lightweight hooks system allowing custom scripts to execute on deterministic boundaries within the agentic loop (`pre_turn`, `post_turn`, and `on_error`). Bound through `.ferric/config.toml`, hooks are executed via the host's native shell environment (`cmd /C` or `sh -c`) using `std::process::Command`, securely injecting synchronous logic immediately prior to tool execution or after failure outcomes without disturbing the core trace flow.

- **Sprint 68 — Background Task Management** (2026-07-17). Added detached `tokio` process management to `shell_exec` and exposed a `manage_task` built-in tool. This allows the agent to spin up long-running tasks in the background with automatic OS-level file redirection for stdout/stderr into `.ferric/tasks/`. The agent can then use `manage_task` (list, status, kill, send_input) to interact with these asynchronous processes without blocking the execution loop.

- **Sprint 69 — Dream Mode** (2026-07-17). Introduced `ferric dream`, an offline knowledge extraction command that asynchronously parses historical JSONL traces from `.ferric/traces/`. It consolidates previous agent activity (user requests, structural discoveries, recurring bugs) into a synthesized `MEMORY.md` persistent knowledge base using the configured LLM backend.

- **Sprint 70 — CI Stability & Architectural Review** (2026-07-17). Fixed lingering GitHub Actions CI failures caused by strict `-D warnings` enforcement for `clippy::collapsible_if` nested conditions in `ferric-loop` and `ferric-provider`, alongside miscellaneous cleanup in `ferric-cli`. Conducted a comprehensive codebase review, seeding `agent-tasks.md` with forward-looking architectural priorities including `tracing` observability, procedural macro tool registration, and parallel execution for side-effect-free tool capabilities.

- **Sprint 71 — Windows CI Robustness** (2026-07-17). Identified and resolved two persistent GitHub Actions `windows-latest` integration test failures. First, replaced `timeout /t 5` with `powershell -Command "Start-Sleep -Seconds 5"` in `test_background_tasks` to bypass immediate exit errors triggered by the CI runner's detached `stdin`. Second, skipped `ferric-research`'s `alpine:latest` Docker retrieval tests on Windows via `#[cfg_attr(windows, ignore)]`, as GitHub's default Windows runners do not support Linux containers (LCOW/WSL2) out-of-the-box. The CI is now fully green across all platforms.

- **Sprint 72 — Observability via `tracing`** (2026-07-17). Added the harness's first structured-logging channel — deliberately **orthogonal** to the JSONL trajectory (ADR-002): the trace answers *what the model did*; `tracing` answers *why the harness did what it did* (guard trips, retries, compaction, hook failures, tool timing). Libraries emit only the facade; **`ferric-cli` alone** installs one process-wide subscriber (in `main()`, so every subcommand inherits it) that writes to **stderr** — stdout stays a clean machine channel for `mcp` JSON-RPC and `query`/`launch` reports — and is **quiet by default** (WARN), opened up by a global `-v/-vv/-vvv` flag or a `FERRIC_LOG`/`RUST_LOG` env filter. `ferric-loop`/`ferric-tools` and the `ferric-provider` openai valve are instrumented (the provider's dep rides the `backend-openai` feature; the default + aarch64 builds never compile it). `ferric-guard` was left **pure** — its denials log at the registry chokepoint, which has the tool context guard lacks. A buffer-writer capture test asserts a guard trip emits its WARN and a clean run stays silent. Also cleared ~4.3 MB of accidentally-committed Windows build artifacts from the repo root and reconciled two stale ledger items (`ferric-prompt` templating → `oovra`; the `Retriever` trait already shipped). *ADR-063.*

- **Sprint 73 — Agent Delegation via ICM, increment 1** (2026-07-17). Answered "agent delegation" not with a multi-agent framework but with **Interpretable Context Methodology** (Van Clief & McDermott, 2026): the **filesystem is the orchestrator**. Numbered stage folders (`stages/01_research/` → `02_script/` → `03_production/`) encode execution order; each stage's `CONTEXT.md` is an Inputs/Process/Outputs contract; a five-layer context hierarchy (L0 identity → L1 routing → L2 contract → L3 reference/factory → L4 working/product) scopes exactly what each stage-agent sees, so context stays small and focused instead of a monolithic lost-in-the-middle prompt. New **`ferric-icm`** crate (pure: `parse_contract`, `IcmWorkspace::discover` with numeric — not lexical — ordering, guard-checked layered composition → `OrchestrationPlan`, refuse-to-clobber scaffolder); `ferric icm init` scaffolds a runnable 3-stage workspace and `ferric icm plan` prints each stage's scoped context + provenance (which file at which layer, missing inputs flagged) with **no model in the loop** — the delegation made inspectable. The Ferric-native adaptation: each stage is a **workspace-scoped run**, so `ferric-guard`'s containment holds — every contract-referenced path resolves through the workspace boundary, and an escaping input (`../../etc/passwd`) is refused, proven by test. Live per-stage loop execution with human review gates is increment 2 (the plan produced here is exactly its input). 16 new tests; full guide in [docs/icm.md](docs/icm.md). *ADR-064.*

- **Sprint 74 — ICM increment 2: the delegation runs** (2026-07-17). Made ICM *execute*. `ferric icm run` feeds each stage's composed context into the same constrained agent loop `ferric query` drives (`run_with_provider` — guard, loop guards, compaction, hooks, JSONL trace all inherited), in numeric order, with human **review gates** between stages (`--auto` runs straight through; `--from`/`--to` run a sub-range; `--mock` for an offline dry-run). The load-bearing security choice: each stage runs **contained to its own `stages/NN_*/` folder**, stronger than the paper's by-convention model — a stage can only write inside its own directory, which works because inc 1 already folds the prior stage's output into the context as Layer 4 (no cross-stage filesystem reads needed). A stage that doesn't reach a successful terminator **halts** the pipeline (a downstream stage must not read untrustworthy output) — which needed the loop *outcome*, not just an exit code. Config+provider built once and reused; the single-use mock is rebuilt fresh per stage. `compose_stage` gained an Outputs directive so a live agent knows where to write. 4 new tests (full pipeline, review-gate stop, stage range, output directive); proven end-to-end in `--mock`. *ADR-065.*

- **Sprint 75 — Agentic Cron** (2026-07-17). Scheduled periodic *agent* tasks — the motivating case being `/dream every 12h` (consolidate traces into memory on a timer). A workspace's `.ferric/cron/*.toml` holds one job per file (a `schedule` interval + a `command`); `ferric cron` manages them: `add`, `list` (schedule + last-run/next-due), `run [--dry-run]` (one tick), and `watch [--interval]` (loop until Ctrl-C). The **security boundary**: a job's command is an *enum* (`dream`, or a `query` with a prompt), **never an arbitrary shell string** — so cron can only trigger operations Ferric already contains (a `query` is a guard-checked workspace-scoped run), deliberately narrower than the arbitrary-script hooks system. Pure scheduling/due/state logic lives in a new `ferric-cron` crate (reads no clock — `now` is injected, so it's fully unit-tested); the CLI drives it and executes by shelling out to the same `ferric` binary. State advances on *attempt*, so a failing job reschedules instead of hammering every tick; a `query` job can set `mock = true` to run offline. 14 new tests; proven end-to-end (`cron run` fires a mock query and advances state). Full guide in [docs/cron.md](docs/cron.md). *ADR-066.*

- **Sprint 76 — Calendar cron expressions** (2026-07-18). Extended sprint 75's cron so a job's `schedule` accepts a standard 5-field **cron expression** (`0 2 * * *` = 02:00 daily; `0 9 * * 1-5` = 09:00 weekdays; `*/15 * * * *`) alongside the recurrence intervals — calendar-anchored tasks, not just "every N hours". `Schedule` became an `Interval | Cron` enum; `parse_schedule` dispatches on shape. Cron matching is **evaluated in UTC** so due-ness stays a pure, deterministic function of `(expression, epoch-ms)` — no host-timezone dependence, the whole scheduler still unit-testable with an injected `now`. Fire-once-per-minute semantics (a job at 02:00:05 won't re-fire at 02:00:55); standard field grammar (`*`, ranges, lists, `*/step`) with the Vixie day-of-month/day-of-week OR rule. `chrono` (already in the tree via oovra, already aarch64-gated) does the epoch→civil decomposition at zero new build cost. 7 new tests. Guide: [docs/cron.md](docs/cron.md). *ADR-067.*

- **Sprint 77 — `.ferricignore` (project denylist)** (2026-07-18). The first config-driven input to security policy: a gitignore-flavored `.ferricignore` in the workspace root lists paths the agent must not touch (`secrets/`, `*.pem`, vendored trees). Scoped tightly against ADR-005's "security is hardcoded, no config override": it is **additive-only** — `check_with_ignore` evaluates the compile-time floor first and short-circuits on a hardcoded deny, so a pattern can only ever *add* a denial, never turn a hardcoded `Deny` into an `Allow`. An ignored path is off-limits at every level (read/write/execute). The file is user-authored (never the LLM), and `.ferricignore` is itself write-denied so the agent can't edit away its own restrictions. Pure `IgnoreList` matcher (segment / basename-glob / path-prefix, no new dependency) loaded once by `Workspace::new`; enforced at the single registry chokepoint. 8 new tests incl. an end-to-end registry proof and the policy-file write-protection. *ADR-068.*

- **Sprint 78 — direct terminal passthrough in chat** (2026-07-18). `ferric chat` gains a third turn kind: a line prefixed `!` (or `/run `) runs a shell command **directly, with no LLM roundtrip** — for checking `ls`/`git status` mid-conversation without asking the model. It runs through the same guarded `shell_exec` chokepoint the agent uses, so the command denylist still fires (a test drives `!rm -rf /` → blocked). The security shape is clean: the human typed the command, so there is *no LLM in the path* (ADR-005 satisfied trivially) — talk has no action channel, `/do` is LLM-driven-but-constrained, `!cmd` acts without constraint but without an LLM. The command + output are a terminal side-channel (printed + logged as a `Note`), never folded into the talk history. Parsing is exact (bare `!`/`/run` are talked; `/running late` is talked). A lazily-created tokio runtime backs the sync REPL. 3 new tests. *ADR-069.*

- **Sprint 79 — interactive "accept edits" mode** (2026-07-19). `ferric query --accept-edits` pauses before every mutating tool call, previews it, and waits for a human y/N before it touches disk — supervised runs where you can veto a bad write without killing the session. The gate lives at the loop's single dispatch chokepoint and keys on the guard's own permission model (`Registry::permission_of` — `Write`/`Execute` gated, `Read` untouched), not a hand-kept list of tool names. The approver is an injected callback (`RunArgs.edit_approver`, mirroring `stream_sink`), so the loop stays pure: tests inject reject/approve/capture closures, the CLI injects a stdin prompt, and every other surface passes `None` so behavior is unchanged. A rejection is first-class, not an abort — the loop feeds the model an error `ToolResult` (`"edit rejected by user"`) it can adapt to, and the run continues. Preview is v1 (tool + targets + pretty-printed args, to stderr so piped stdout stays clean; empty/`n`/EOF all reject). 3 new tests (reject blocks the write + tells the model, approve lets it through, the preview carries tool + target). *ADR-070.*

- **Sprint 80 — ICM references on demand (`fetch_reference`)** (2026-07-23). The Ferric side of the sibling **Animus Dark Matter** knowledge-layer seam (its `INTEGRATION.md`): instead of folding a stage's whole `references/` into the prompt, `ferric icm run --fetch-references` composes the stage with its own references **withheld** and hands the model a new `fetch_reference` tool to pull only the chunk(s) it queries. A new `ComposeMode` gates it — default `ferric icm run`/`plan` are byte-for-byte unchanged — which also hands the SPEC-§9 A/B its two arms for free. `fetch_reference` (`Read`, ring 0) is registered **only for ICM runs**, so a normal `ferric query` never pays a tool slot for it; a deliberately simple in-tree backend (recursive read + heading chunk + keyword score) stands in for a future Dark Matter MCP knowledge server behind the *same* contract. Scoping falls out of the stage-containment model (ADR-065): only the stage's *own* `references/` are fetchable, so cross-stage Layer-4 and shared `_config` stay folded. Measured: a 133 KB reference vault shrank stage-1's prompt from 136,162 → 3,355 chars (**97.5% smaller**). 10 new tests. *ADR-071.*

- **Sprints 81–82 — full-codebase verification** (2026-07-24). An audit of all 14 crates (29,664 lines) plus the Dark Matter spec repo, classifying every subsystem as critical, refactorable, or vestigial. Sprint 81 completed the static read-through but could not run a single check — `C:` was at 100% and `cargo test` wedged mid-link — and deliberately declined to write an ADR asserting conclusions no test had confirmed. Sprint 82 ran what 81 could not: **463 tests pass / 0 fail** across 52 suites, clippy and fmt clean, cold rebuild 31s with 0 warnings, Dark Matter's verifier PASS 61 / FAIL 0. **The core is genuinely good — and four defects live inside that green suite**, each made to fail a written test: ADR-002's 4,000-char tool-output truncation never reaches the model (**20,028 chars** measured entering the context window on one `read_file`); `Vcs::snapshot` destroys the user's staged git index once per turn; `fetch_reference` finds nothing for queries ≤ 2 chars; and the CaMeL-lite taint set marks trusted provenance instead of the untrusted content, inverting ADR-044 against its own threat model. The shape they share: **each is covered up to a crate boundary and not across it.** Also refuted sprint 81's own proposed fix for the git defect (`read-tree HEAD` destroys the index identically to `git reset`; a temporary `GIT_INDEX_FILE` is the verified fix), and proved the Dark Matter seam is two incompatible contracts sharing one name — a DM-schema-legal call is hard-rejected by Ferric. Audit only; the tree is unmodified. Report: [`docs/verification-2026-07.md`](docs/verification-2026-07.md). *ADR-072.*

- **Sprint 83 — remediating the audit** (2026-07-24). Fixes the four demonstrated defects and clears the vestigial list; **463 → 478 tests, 0 failures**. `Vcs::snapshot` no longer destroys the user's staged git index — it stages into a private `GIT_INDEX_FILE`, and note that sprint 82's own recommended fix was wrong (`git read-tree HEAD` resets the index to HEAD exactly like `git reset`; measuring it is what caught that). Writing a test *adjacent* to that bug then surfaced one the audit had missed entirely: **git discovery walks upward**, so a workspace that isn't itself a repo resolves to the nearest ancestor — and on a machine where `~` is a git repo, the per-turn `git add -A` was targeting the user's whole home directory. All three vcs entry points now refuse unless the workspace *is* the worktree root, which took `cargo test -p ferric-cli` from wedging past 10 minutes to 1 second. Tool-output truncation is restored in the **projector**, where the context window is actually assembled, so run and replay stay identical by construction. The taint set now marks untrusted content instead of trusted provenance — and at line/sentence granularity, because tainting only the whole summary would have been a fix that never fires. Short reference queries (`"Go"`) work again without reintroducing the substring noise the length filter existed to prevent. Six unused deps removed (proven by building without them), plus two items resolved by *use* rather than deletion. *ADR-073.*

- **Sprint 84 — finishing the audit** (2026-07-24). Clears everything sprint 83 deferred: **487 → 503 tests, 0 failures**. `manage_task` can no longer abort the harness — all 12 lock `.unwrap()`s gone (one poisoned lock used to make every later call kill the process), and the two tokio-runtime panic paths are now ordinary tool errors. Writing that test found **the same bug in `shell_exec`**, a Ring-0 tool reachable from far more paths. `RequireApproval` is finally wired to the `EditApprover` that had been sitting at the same dispatch site for four sprints. The sandbox airlock is opt-out rather than opt-in: the default now denies the network and requires gVisor, and unrestricted egress is an enum variant you have to write. `run_with_provider`'s 18 positional parameters collapse to a `RunArgs` (taking 5 clippy suppressions down to 1, and deleting an `icm.rs` macro that existed only to avoid typing the list twice); the `post_turn` block is no longer copy-pasted four times; `ferric-vcs` is honestly synchronous instead of `async fn` with no `.await`. On the Dark Matter seam, a DM-shaped call is accepted at last, silent `k`-capping now reports what it withheld, and DM's verifier reads the real descriptor instead of only checking that two unrelated files exist. **Also a defect in no report:** background-task ids were `task-{millis}`, so two tasks started in the same millisecond collided and the second silently evicted the first — surfaced as a test flake I had initially written off. *ADR-074.*

- **Sprint 85 — verification round 2** (2026-07-25). A second full audit from a cold clean-room build, weighted deliberately toward **sprints 83–84's own changes** rather than spread evenly — and that weighting is the finding: **three of the four new defects were introduced by the remediation sprints themselves**, two of them in the security-facing code those sprints existed to fix. Baseline is green (0-warning cold build, **503 tests pass**, clippy/fmt clean, DM verifier 62/0/0). New: one tool call **prompts the human twice** when accept-edits and the sink policy are both live; the taint granularity chosen in sprint 83 blocks **3 of 3** faithful restatements of researched material under the default `Deny`, and **no threshold fixes it** — substring taint cannot separate "copied an injection" from "wrote a true fact it learned", so that one is a posture decision, not a patch; `run` and `replay` disagree about the truncation cap, refuting a claim ADR-074 made; and `ferric chat` discards trace-write failures at all 6 sites where `run.rs` propagates at 21. Three defect *classes* are now closed — production panics are down to 6 provably-safe idioms, no unresolved intent comments remain, no stale ledger entries. *ADR-075.*

- **Sprint 86 — the live-model round** (2026-07-25). Closes the gap ADR-075 called the highest-value next investment. `ferric server` → llama.cpp `llama-server` → **qwen2.5-coder-7b** live: `doctor`/`up`/`status`/`down` all work, and the constrained agentic loop completed a real task (**read_file → write_file → task_complete, 3 turns, 36 s**, correct output) with streaming and a full trace — the first live confirmation in ~60 sprints. **Two defects that 503 mock tests could not see:** on a harder task the model burned the **entire 20-turn budget** with only **2 distinct tool calls** alternating, and **not one of the three guards fired** — they all key on *consecutive-turn* state, so A-B-A-B resets them, and `FailureGuard` never engages because the calls *succeed*; and `--tailscale` never discovered the Tailnet FQDN, because `DNSName` lives at `Self.DNSName` and the code read it from the root, so `server up --tailscale` announced success and then wrote the **loopback** URL into the runfile. The tailscale bug is fixed here (the `tailscale serve --bg <port>` half was already correct, and now has a test saying so). *ADR-076.*

- **Sprint 87 — the fourth guard** (2026-07-25). Closes sprint 86's F1. The three existing guards all key on *consecutive-turn* state, so an A-B-A-B cycle resets every one of them — and `FailureGuard` never engages at all, because an oscillating model's calls **succeed**. A new windowed `OscillationGuard` asks a different question — *over the last N turns, how many distinct things has the model actually done?* — giving the ladder **repetition 2 < failure 3 < no-progress 5 < oscillation 8**. **Validated live on the exact scenario that found it:** 20 turns / zero guards / `max_turns` became **8 turns / warned twice / stopped with `oscillation`**. The live rig also finally exercised **A1**, which sprint 86 missed because the model paginated: forced with a single 19,992-char line, the trace kept the full text while the model got ~4,000 and said so itself — *"which has been truncated for display."* **One new live finding:** `--research` injected no research context and printed nothing, silently degrading into an ordinary run. 518 tests. *ADR-077.*

- **Sprint 88 — G1 fixed, and a live measurement that corrects our own finding** (2026-07-25). `--research` was silently producing nothing: `LocalFsRetriever` matched the whole query as **one literal substring**, so any multi-word query found nothing unless that exact phrase appeared verbatim (`"configuration"` matched; `"project notes configuration"` did not, in the same directory). Queries are tokenized now, terms ANDed, and an empty research result **reports itself** instead of degrading into an ordinary run — that silence is what hid the bug for three sprints. Then, with a downloaded 3B and a real digest, **E2 was finally measured live — and it corrects ADR-075**: the model copied a digest sentence into `write_file` and it was **allowed**, because the digest is a *paraphrase* and the needle is a whole sentence of which the model wrote a *prefix*. So the taint mechanism is weak in **both** directions, not over-strict; the "unusable in practice" framing was an artefact of a probe feeding whole segments back verbatim. 524 tests. *ADR-078.*

- **Sprint 89 — one call, one prompt** (2026-07-25). Clears ADR-075's two small open items. **E1:** `--accept-edits` and the sink policy's `RequireApproval` cover *exactly* the same calls — both fire only on `Write`/`Execute`, and a tainted `Read` is always allowed — so with both live the human was asked **twice about one call**. Fixed by merging the question rather than suppressing the second ask: the accept-edits preview now discloses the taint, and that approval carries through to the sink gate. One prompt, more information than either gate had alone; with no approver, `RequireApproval` still denies. **E4:** `ferric chat` discarded trace-write failures at all 6 sites where `run.rs` propagates at 21 — now warned, latched once per session, because a silently truncated trace is the wrong failure mode for a harness built on "if it isn't in the trace, it didn't happen". 529 tests. *ADR-079.*

- **Sprint 90 — E2 resolved: a structural gate replaces the detector** (2026-07-25). The open posture question, settled. Substring taint failed live in **both** directions (ADR-078) — it detects *copying* while the threat is *influence*, and paraphrase defeats it at any threshold — so there was no constant to tune. The question changed instead: not *"do these arguments contain untrusted text?"* but *"has this run ingested untrusted content at all?"*, a fact the harness stamps once and the model cannot launder. New `Provenance { Clean, UntrustedIngested }`; **`TaintSet` deleted**, because keeping a detector that does not work manufactures confidence. Default is now `RequireApproval`: a clean run is **never** gated, a contaminated one asks a human once per mutation via sprint 89's single merged prompt, and with no approver it denies. This restores consistency with the rest of Ornstein, where the quarantine has always been structural (ADR-010/040). Validated live on all three cases — including the exact write ADR-078 measured being *allowed*, now denied. 529 tests. *ADR-080.*

- **Sprint 91 — the sandbox meets a real daemon** (2026-07-25). Docker was installed, closing the containerizer gap that had blocked Ornstein's container work since **sprint 33**. A5's airlock — added in sprint 84 but only ever tested at the argv level — is now validated live: `--network none` genuinely isolates (`wget: bad address`), explicit `Unrestricted` genuinely fetches, capabilities really drop, and critically **the gVisor default fails CLOSED** — with `runsc` absent it errors rather than silently falling back to `runc`. Also bounded `check_available()`, which had no timeout and **hung ~60 s** against a half-started daemon; that made a run of 5 *skipped* tests take 269 s and look like 5 passes, which I nearly reported as validation. The real run takes 12 s. **Docker did not unblock D2**, and that is the finding: wiring the web plane is now gated on the **allowlist proxy**, not the containerizer — without it the only choices are a retriever that cannot fetch or the unrestricted egress sprint 84 made opt-out. 534 tests. *ADR-081.*

- **Sprint 92 — the proxy policy was advisory, not an airlock** (2026-07-25). Debugging sprint 91's "last blocker" turned up something more important first: **the mechanism a proxy would have plugged into did not constrain anything.** `NetworkPolicy::Proxy` attached the sandbox to `--network bridge` and set `http_proxy` — but those variables are a convention cooperative clients honour, not a boundary. **Measured:** a container runs `unset http_proxy https_proxy` and fetches the internet in full while the proxy points at a dead port. Building an allowlist proxy behind that would have repeated ADR-078's mistake exactly. Isolation has to come from the network, so `Proxy(url)` is replaced by `Airlock { network, proxy_url }` on a docker network created `--internal` — no route out, holding against both DNS and raw IP. Verified end-to-end against the real topology: allowlisted host **fetched**, non-allowlisted **403**, and `unset http_proxy` **unreachable** — the bypass is closed. 535 tests. *ADR-082.*

- **Sprint 93 — Ferric owns the airlock lifecycle** (2026-07-25). ADR-082 proved the enforced-egress topology by hand; now `airlock::Airlock` builds one. `start(allowlist)` creates the `--internal` network and an egress network, runs a default-deny gateway, **polls** until it accepts connections, and only then attaches it to the internal side — so a sandbox can never reach a proxy that is up but has not loaded its filter. Failure is closed, and teardown is **RAII**, because a panic would otherwise leak the one container on the machine that has egress. Allowlist entries are validated against the DNS charset **before any docker resource exists** — they are written by a shell inside the gateway, so an unvalidated entry is command injection into the one container with network access. A test bug is recorded too: the teardown assertion matched the `ferric-gateway-` *prefix* and so failed against a concurrent test's gateway — correct teardown, wrong assertion, caught only by parallel execution. 542 tests. *ADR-083.* **Amended (ADR-084):** CI then failed on windows-latest, where the runner ships a Docker daemon in **Windows-container** mode — reachable, so the availability probe said yes, and then every Linux image failed to pull. `check_available()` now requires `OSType == linux`. The serious part: **5 of 6 sandbox tests were passing for the wrong reason** — they assert *failure*, and got one, just not theirs. Only the single positive assertion caught it. Negative assertions must now state **why** they failed.

- **Sprint 94 — D2: the web plane reaches the binary** (2026-07-25). `WebRetriever` has been unreachable from `ferric` since ADR-045; sprints 91–93 removed the mechanism gaps, this is the wiring. **`--research-url <URL>`** is separate from `--research` because the planes want different things — Local-FS takes keywords, the Web plane requires the query to *be* a URL, and one parameter with two meanings would have been the quiet kind of wrong. **The allowlist is derived from the URLs and nothing else**, so there is no separate config to drift and the sandbox may reach precisely the hosts you named. That makes `url_host` a security boundary: it strips **userinfo** (`http://example.com@evil.test/` allowlists `evil.test`), drops the port, and validates the result *before* the airlock opens. One airlock per run (~15s, RAII teardown); a failed fetch is fatal rather than skipped; gVisor stays the default with `--allow-standard-runtime` as the named opt-out — network isolation does not depend on it. **Verified live**: airlock opens, URL fetched and quarantined, run **contaminated** so `write_file` is denied, and an unallowlistable URL refused before the airlock opens. 545 tests. *ADR-085.*

- **Sprint 95 — fleet re-calibration, and two defects it exposed** (2026-07-25). The capability map had not moved since sprints 25–26. Refreshed: **`qwen2.5-coder-3b` → measured_level 4 (Small)**, **`qwen2.5-coder-7b` → 6 (Large)**. Same family, so this isolates *size* — and the 7B's 6 matches its sprint-20 figure, 75 sprints of harness change later. The run also found two ways the calibrator misreports. **H1:** a partial `--level` sweep silently **downgraded** a stored profile — investigating the 7B's L5 rewrote its record from 6/Large to 5/Medium, and `ferric query` reads that profile to size its RunPolicy, so looking at one rung shrank the model's tier. Profiles are now written only from a full ladder. **H2:** the 7B's first sweep **failed L5 and passed L6**, scoring 6 and looking identical to a clean run; L5 then passed three times on repeat, so it was noise — but with one sample per level, luck only ever inflates. Non-monotonic ladders are now reported. 549 tests. *ADR-086.*

- **Sprint 96 — a prebuilt gateway, and the skip that hid a broken airlock** (2026-07-25). Every `Airlock::start` ran `apk add tinyproxy` in a fresh alpine container; a prebuilt `ferric-gateway:1` removes it. **The ~10 s premise was wrong** — measured old vs new on the same machine, 2.72 s → 2.08 s; ADR-083's figure came from a suite run that included the alpine pull, and it is corrected rather than quietly reused. The real win is that the airlock no longer depends on reaching the Alpine mirror *at start time*: an external availability dependency removed from a security boundary. Building it exposed something worse: all three live airlock tests **skipped and passed** when `start` failed — *after* the Docker gate had already said yes. A skip condition that can fire after the availability gate turns a broken airlock into a green suite. `start_or_fail` closes it. 553 tests. *ADR-087.*

- **Sprint 97 — the compose stack had never worked** (2026-07-25). `docker-ferric-core-1` had been crash-looping since 2026-07-14. Five defects, and none of them had a failing test because nothing tested the stack at all: `ENTRYPOINT ["ferric"]` + `command: tail -f /dev/null` ran `ferric tail …` under `restart: unless-stopped`; a `/var/run/docker.sock` mount that was doubly non-functional (no docker CLI in the image, and the socket is root-owned 0660 against uid 10001) **while staging a host-root escape next to the airlock**; a squid proxy on a **bridge** network — the topology ADR-082 measured as bypassable — referenced by no code; a **tracked** `docker/.env` pinning the model path to one machine's NAS; and `ferric server down` unable to kill anything in a slim image (`kill(1)` is absent) while deleting the runfile anyway, orphaning a live server. Fixing the first created the next: `sleep` as PID 1 does not reap, so the killed server became a permanent **zombie**, and a zombie answers `kill -0` — `init: true` plus a `/proc` state check. Verified by a full constrained run *inside* the container. *ADR-088.*

- **Sprint 98 — the dead enum, and the live thing beside it** (2026-07-25). B1 asked to retire `Protocol::{FencedCode, EditFormat}` as a schema change with a migration. **The entry was wrong in both directions.** Not a schema change: profiles store `protocol` as a `String` whose on-disk value the enum's `snake_case` rename could not have produced, traces serialize `ActionProtocol` instead, and no artifact contains either variant — nothing to migrate. Also bigger than two variants: the enum's only use was `RunPolicy.protocol`, always the same value and read by nothing but two test assertions, so all of it went. **The real find was adjacent:** profiles key on `(model, protocol)` and six call sites each wrote `format!("{protocol:?}")` independently — a rename would make `read_profile` miss, and a miss is a documented safe no-op, so a model would silently drop to its params tier. One `protocol_key` plus two contract tests. *ADR-089.*

- **Sprint 99 — E2E: three features that had never worked** (2026-07-25). All twelve subcommands driven live. **Three did not work at all, and none of them failed a test.** `ferric launch` scaffolded a `Cargo.toml` with no `[workspace]`, so a project created inside any other Rust tree was silently adopted by it. The `ferric-core` image shipped **no `git`**, so every in-container run had no VCS snapshot and `revert` had nothing to restore — recorded as a trace `note:` and carried on. And **Dream Mode had never once run**: it read `.ferric/traces` while all five writers write `.ferric/trace`, reporting that as a clean "no traces found" — and fixing the path exposed a second defect underneath (`futures_executor::block_on` where a Tokio runtime was needed). Trace-dir now has one definition. Verified working: query, server up/status/doctor/down on both platforms, **VCS snapshot+revert end to end for the first time**, bench, mcp, icm, cron, trace, and the airlock→quarantine→sink-policy chain **in both directions**. *ADR-090.*

- **Sprint 100 — agent skills: installation is consent, invocation is authority** (2026-07-25). Conventional `SKILL.md` loading, with the trust question settled by the user: installing a skill is a deliberate act, so it is not untrusted the way a web page is — but that does not make invocation automatic. Two structural properties. **Only the user installs:** `.ferric` is in `DENIED_WRITE_SEGMENTS`, verified live (the 7B asked to write `.ferric/skills/evil/SKILL.md` was denied), and the same denial protects the allowlist, which is why it lives in config. **Discovery is not authorization:** `Authority` is `UserRequested` or `ConfigAllowed` with **no `Model` variant**, and `DiscoveredSkill`/`AuthorizedSkill` are distinct types, so `compose()` cannot be handed an unauthorized one. Also **deleted a duplicate loader** whose permissive parser let a directory named `helpful/` answer to `deploy`. *ADR-091.*

- **Sprint 101 — a second verification round, on the 7B** (2026-07-25). Cold build from `cargo clean`: zero warnings. **A defect in the day-old skills code:** `authorize()` did not dedup `requested` against itself, so `--skill x --skill x` injected the instructions twice. **ADR-091 was too weak:** `.ferric` is in `DENIED_READ_SEGMENTS` as well as write, so the model cannot even *read* an unauthorized `SKILL.md` — authorized injection is the only route from a skill to the model at all. **Composition proven:** an authorized skill plus ingested research still has `write_file` denied; a skill cannot unlock a contaminated write. The 7B also completed a six-turn task, giving **per-turn VCS granularity** for the first time. And a false positive in my own testing: a background `cargo test` rebuilt the binary without `backend-openai` mid-experiment, and "file not written" read exactly like the security gate working. **When the expected result is an absence, an unrelated failure is indistinguishable from success.** 569 tests. *ADR-092.*

- **Sprint 102 — one truncation cap, and a drift detector that always said drift** (2026-07-26). E3, open since sprint 84, and **the entry was wrong in both directions** — `compact.rs` was a `#[cfg(test)]` helper, while `trace_verify.rs` was a real third site nobody had named. Root cause was neither: **the cap was not in the trace.** `run()` was correct only because it holds the live registry; `replay` and `trace verify` have only the file, so both assumed the default. `PolicySelected` now carries it, the projector reads it from that event and nowhere else, and ADR-074's "identical by construction" is amended in place — sharing the formatting was real, but a shared function fed a different parameter from a different source is not identical. **Then smoke-testing the command I had just edited found that `ferric trace verify` had never verified anything:** `TurnEnd` is written *before* dispatch, so a turn's `ToolCall`s follow it, and building the completion at `TurnEnd` gave every turn the previous turn's calls while dropping the last turn's — losing the terminator, so any trace with a tool call reported drift. A detector that always says drift detects nothing. 574 tests. *ADR-093.*

- **Sprint 103 — C7, half declined** (2026-07-26). The item asked to split `ferric-cli` into subdirectories. **That half is closed as declined, not quietly ticked:** the crate measures 8,396 lines across 19 modules (the logged 9,674 counted tests), the audit's own sentence concedes the spine is factored, and moving 19 files changes no behaviour, finds no defect, and rewrites every `git blame` in the crate. Long is not the same as tangled. **The half worth doing was a real duplication:** `chat.rs` and `icm.rs` each declared their own backend enum — identical apart from the name — with **line-for-line identical** constructors and **byte-identical** feature-off error strings, and `mcp.rs` carried a third copy of that string. Now one `ResolvedBackend`, one builder, one diagnostic. **`mcp::Executor` is kept on purpose:** it builds its provider once at launch and reuses it per `tools/call`, while chat and icm build a fresh mock per invocation — and `MockProvider` is scripted and stateful, so *when* it is constructed is behaviour, not style; collapsing the shapes would have silently changed one. Also deleted an error string that could never be printed: `create_provider` is gated on the feature and still contained a `cfg(not(feature))` arm that could not compile in. The feature-off diagnostic — the exact condition behind sprint 101's false positive — had three untested copies and now has one, with a test. 575 tests, clean in **both** feature configurations. *ADR-094.*

- **Sprint 105 — detaching the repo from the machine that grew it** (2026-07-26). Ferric is meant to be usable as a template, and **the repo had already learned this lesson once and applied it to exactly one file**: sprint 97 found a *tracked* `docker/.env` pinning the model path to one machine's drive, which overrode the portable default on every checkout. The same pattern held elsewhere. **`sprints/` had 139 tracked files while already being listed in `.gitignore`** — a gitignore rule never untracks what already is — so the template shipped 139 files its own tooling calls regenerable. Machine *identity* came out of the Rust fixtures (a real tailnet IP, MagicDNS suffix, hostname and node id; device names and the owner's account handle), every one keeping its exact shape with documentation values — all assertions still pass, which is the evidence none were asserting identity. **The behavioural one was `benchmarks/model_profiles.json`:** ADR-029 reads it back and lets `measured_level` override the parameter prior *in both directions*, so a tracked copy handed every fresh checkout a tier measured on other hardware at a quantization the record never pinned. ADR-029 had established that a profile *miss* is a safe no-op; nobody had asked what a *hit from someone else's machine* means. A one-time cleanup decays, so it is now a test — and **the guard's own self-test found a hole in the guard**: it missed backslash-doubled paths inside Rust string literals, the likeliest leak site of all. 577 tests. *ADR-096.*

- **Sprint 106 — the environment surface, and a credential one `{:?}` from a log** (2026-07-26). A full audit of every runtime environment read (`docs/environment.md`). Only six exist, and **the model can reach none of them** — `.ferric/` is read- *and* write-denied, the user config sits outside containment, and there is no `env::set_var` anywhere. **The real find was not an environment variable at all:** `Config` holds `api_key` in plaintext and **derived `Debug`**, putting the credential one `{:?}` away from a log line, an `assert_eq!` failure message, or a panic payload. Nothing printed one — but "nothing prints it" is a property of the call sites, not of the type. Now a hand-written `Debug` rendering it `<redacted>` while keeping *presence* visible, since that is what config-precedence debugging actually needs. **And this sprint's own research report had claimed the opposite** — that all three key-bearing types lacked `Debug` — read off a `grep -B4` whose context stopped one line short of the derive. Writing the claim as a test *with a positive control* caught it: the grep and the compiler disagreed and the compiler was right. The remaining two types are now guarded by a **compile-time** assertion, so adding a derive fails the build rather than a test someone might skip. The `XDG_CONFIG_HOME → config.toml → hooks → sh -c` chain is answered with **disclosure rather than lockdown** — a run with hooks in effect now names the file that supplied them, because a hook you wrote and a hook from a config you did not know was being read used to look identical. 583 tests. *ADR-097.*

- **Sprint 107 — a tier you can ask for, and a record that says you asked** (2026-07-26). Raised by the user against ADR-006's design. The tier was a pure function of the model profile with no operator dial — but `tier_for_params` is part of that function, so **the only manual route to a tier was to misstate `--params-b`**, claiming 30B until the threshold table produced the wanted answer. Two things wrong with that: `params_b` is a *fact* about the model (and an input `model_profiles.json` and the ADR-029 read-back both trust), and the result was **unattributable** — `tier: Large` was recorded with nothing else, so a tier a model *earned* on the L0–L6 ladder and one somebody *claimed* were byte-identical in the trace. The design forced dishonesty and then destroyed the evidence of it. Now `--tier` (and config `tier`) is an explicit override winning over both the measured read-back and the parameter prior, in **either** direction — a capable model can be held down as easily as a small one lifted, which the params route could never do without claiming the model was tiny. This does not reopen what ADR-006 closed: that rules out runtime *heuristics*, and a config-supplied choice is the opposite — explicit, inspectable, recorded. The other half is that the record now says so: `TierSource` lands on `RunPolicy` itself, `trace cat` renders `Large (from override)`, and **a test pins why it matters** — an earned Large and an asked-for Large have identical budgets, so the provenance label is the *only* field telling them apart. 588 tests. *ADR-098.*

- **Sprint 110 — Monday demo readiness** (2026-08-01). Replaced executable `trace verify` replay with a side-effect-free, phase-aware transcript validator; routed CLI/MCP/API attachments through workspace read policy with strict size bounds; removed host shell and task management from every model-visible ring while retaining guarded human chat passthrough; centralized successful stop semantics; fixed API mock/bind/workspace behavior, repeated MCP mock calls, and noninteractive launch; and replaced false-green E2E checks with an eight-step offline smoke runner. The freshly built release path was rehearsed end to end on Windows with `.\tools\demo-smoke.ps1`. Docker, Tailscale, and live-model integration were unavailable and are explicitly not claimed. *ADR-101.*

- **Sprint 111 — live server acceptance** (2026-08-01). Superseded the offline Monday criterion at the user's direction and exercised the actual release path: `ferric server doctor` → `server up` → independent HTTP health/model checks → a six-turn Qwen2.5-Coder-7B task with asserted file creation, deletion, `task_complete`, and trace verification → `server down`. The engine PID owned the loopback listener, both runfiles matched it, and shutdown removed the process, listener, and registrations. The live task passed in about 58 seconds; the installed llama.cpp distribution appeared CPU-only, so that timing—not correctness—is the remaining presentation caveat. *ADR-102.*

- **Sprint 112 — an autonomy baseline that can fail honestly** (2026-08-02). Added a frozen internal corpus of 24 executable repository tasks (eight ambiguity, eight recovery, eight long-horizon) across current, recovery, and metadata-only repository-brief variants. Every episode is a real `ferric query` child against an OpenAI-compatible server—there is no mock/offline autonomy path. Results separate contract completion, objective completion, and infrastructure failure; retain hashed traces and binary/model/corpus provenance; report Wilson intervals, clarification/recovery outcomes, paired brief comparisons, and pass³ only when three trials exist. Recovery is now a durable trace contract with workspace-bound checkpoints, resume-of-resume, structured clarification, refusal probes, and mutation-newer verification evidence. The targeted Qwen2.5-Coder-7B sample was **3/6**, with the long-horizon H01 pair failing in both variants; that is deliberately recorded as a small, unbalanced sample, not a general coding-agent score. Three hardened process-cold `server up` lifecycles passed with exact PID/listener/HTTP/model checks and clean teardown. *ADR-103.*

> **Next.** Establish the first complete autonomy baseline: 72 episodes for one
> pass over the 24×3 matrix, then 216 for pass³ when hardware time permits.
> Use the retained failure traces to improve read-before-edit behavior,
> verification-guided repair, and long-horizon recovery without tuning to one
> task. Duplicate/collateral-effect instrumentation and safe identity binding
> for stale `server down` runfiles remain explicit gaps. Skills granting tools
> and the SSH-only `TailnetFsRetriever` design remain separate open decisions.

Animus_Ferric

Animus_Ferric Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Animus_Ferric

Animus_Ferric Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README