Hardening batch: fail-loudly invariants, audit visibility, migration rails, test depth

CHANGELOG.md

@@ -4,6 +4,75 @@ All notable changes to Foundation CLI are documented here. This project follows
 semantic-ish versioning: feature releases bump the minor version; bug fixes and
 small enhancements land on patch releases.
 
+## [Unreleased] — hardening batch (2026-06)
+
+Closes the gaps found in the 2026-06-10 full-project review (see
+`plans/fcli-hardening-roadmap.md` for stage-by-stage detail and the findings
+that were checked and rejected).
+
+### Changed
+
+- **Executor invariants fail loudly.** All 16 `assert` statements in the
+  action executor (kind/payload narrowing, file/git service wiring) were
+  replaced with a typed `ExecutorInvariantError`; violations now surface as
+  FAILED execution results in the trace instead of interpreter crashes, and
+  survive `python -O`.
+- **Plan-action validation closed its last holes.** A stray `question`
+  payload on EXPLANATION/SHELL/TOOL_CALL actions (and a stray `explanation`
+  on QUESTION actions) is now rejected at validation time and routed through
+  the existing plan-repair retry.
+- **One source of truth for git mutation subcommands.**
+  `GIT_MUTATION_SUBCOMMANDS` lives in `models/git.py`; the planner and the
+  guardrail policy engine both alias it, so they can no longer diverge.
+- **Audit-trail failures are visible.** Event-sink failures are counted and
+  warned about; a sink failing 3 consecutive times is disabled with one
+  final warning instead of spamming. A crash inside the NDJSON event-log
+  writer now marks the session `write_truncated` in `sessions.jsonl` instead
+  of letting the index claim a complete log. Gap-message phrasing fallbacks
+  log their reason (provider-error / empty / json-or-fenced / plan-shaped).
+- **History migrations have safety rails.** Before any schema migration the
+  database file is backed up to `<db>.pre-v<target>.bak` (newest kept). The
+  v6 rebuild validates row counts before dropping the source table; failures
+  raise `HistoryMigrationError` naming the backup, with the original data
+  intact.
+- **Diff applier leniency is bounded and reported.** Hunks whose declared
+  source-line count disagrees with their body, and hunks with no additions
+  or removals, are rejected at parse time. Bare context lines and
+  newline-normalized matching remain accepted but are reported through
+  `FileMutationResult.leniency_notes` into the trace.
+
+### Fixed
+
+- A plan naming a nonexistent capability id crashed the turn with an
+  unwrapped `ValueError`; it now routes through the plan-repair retry.
+- Model-generated text was parsed as Rich markup in the live detail panel
+  and both chat renderers, allowing styling injection and a `MarkupError`
+  crash; it renders literally now.
+- In piped, non-interactive runs an approval-gated action died with a bare
+  "Aborted." (exit 1) when the prompt hit EOF; it now resolves as
+  PENDING_APPROVAL with the graceful stop notice. A TTY user pressing
+  Ctrl-C at the prompt still aborts.
+- Typing "y" at an interactive approval prompt no longer resolves as "n":
+  the live status line's `?`-toggle keypress reader kept reading stdin
+  byte-by-byte during prompts, eating the user's answer so `typer.confirm`
+  saw only the Enter and fell back to the default. `pause()` now stops the
+  reader thread, restores canonical terminal mode, and flushes type-ahead;
+  `resume()` reinstalls the reader. Affected every mid-turn prompt
+  (approvals, agent questions, out-of-scope read grants) on a real TTY.
+- A turn that failed, repaired itself, and completed no longer reports
+  "stopped: tool failed"; the summary reads "Executed N actions, recovered
+  from M earlier failure(s)". Custom test scripts (any command with "test"
+  in its basename, e.g. `./run_tests.sh`) now count as verification, and
+  the verification outcome across iterations is decided by the latest
+  attempt instead of worst-wins, so a repaired test run reports "passed".
+
+### Added
+
+- 100+ new tests, including isolated `PlannerService` unit tests
+  (`tests/test_planner.py`), Codex provider failure-path coverage, live
+  rendering edge cases, sink failure/circuit-breaker tests, and migration
+  backup/sabotage tests.
+
 ## [0.2.0] — unreleased (v3)
 
 v3 makes `foundation` behave like a real coding-agent shell on top of the v2

docs/TECHNICAL.md

@@ -243,6 +243,18 @@ Retention defaults to 200 sessions / 500 MB; oldest sessions are pruned
 automatically on session end. Configure under `[monitor]` in
 `config.toml`.
 
+**Degradation is recorded, never silent.** A session whose event log lost
+writes — whether from an I/O error or a crash inside the writer — closes
+with `status=write_truncated` in `sessions.jsonl`, so consumers can tell a
+complete log from a partial one. An event sink that fails on 3 consecutive
+events is disabled for the rest of the session with one final warning.
+
+**History migrations back up first.** Before any schema migration runs, the
+SQLite history database is copied to `<db>.pre-v<target>.bak` next to the
+original (only the newest backup is kept). A failed migration raises
+`HistoryMigrationError` naming the backup and leaves the original data
+untouched.
+
 **Opt-out:** pass `--no-monitor` for one invocation, set
 `FOUNDATION_MONITOR=0`, or `monitor.enabled = false` in `config.toml`.
 Override the directory with `--events-dir <path>`.

plans/00-roadmap.md

@@ -1,5 +1,9 @@
 # Foundation CLI v0.1 Roadmap
 
+## Status
+
+**v0.1 shipped** — superseded by the v2/v3/v4 roadmaps and the fix/hardening batches.
+
 ## Purpose
 This planning set is the stage-zero baseline for Foundation CLI. It turns the MVP direction into an execution sequence with explicit gates so implementation can move from an empty repository to a usable v0.1 without scope drift.
 

plans/fcli-fixes-roadmap.md

@@ -1,5 +1,14 @@
 # FCLI Fixes Roadmap
 
+## Status
+
+**Complete (verified 2026-06-10).** All five stages shipped: command error
+recovery (`_COMMAND_USAGE_ERROR_PATTERNS` in `gap_handoff.py` + repair
+notices in `orchestrator.py`), static gates restored (ruff check/format and
+strict mypy all green), and live loading UX (`LivePhase` model in
+`live_turn.py`, landed via #11/#12). Superseded by
+`plans/fcli-hardening-roadmap.md` for the next fix batch.
+
 ## Purpose
 
 Track the near-term fixes needed to get Foundation CLI back to a clean,