docs(overseer): document goal-board health — self-heal + escalate (#2609/#2616)

[rysweet]

What

Enhances the Overseer goal-board health capability (feature #2616 / 965c859f, already on main) with two follow-up layers:

1. Documentation — the feature merged code-only, with no user-facing docs (unlike its siblings feat(overseer): add the Simard Whisperer — advisory OODA steering (#2605) #2611 Whisperer and feat(journal): Simard's daily journal — narrative diary in cognitive memory, dashboard tab + TUI pane (#2606) #2618 Journal). This fills that gap with concept + howto + reference pages.
2. Code hardening (follow-up commits) — security, perf, and refactor refinements to the observe → self-heal → escalate path, chiefly SMTP hardening of the NotifyOperator email channel that carries genuine "needs human review" escalations.

Every symbol described is grounded in the merged code under src/overseer/.

Why

In production the OODA no-progress safeguard hard-blocked the standing research goal ("needs human review") and nothing surfaced it — the Overseer's ObservedState had no goal-board field, so the marker reached no human. #2616 closed that gap (observe Blocked goals → self-heal false-parked perpetual goals, escalate genuine blocks). Its behaviour was undocumented; operators had no reference for SIMARD_OVERSEER_GOAL_HEALTH, the overseer::goal_health traces, or the escalation notifications. The follow-up code commits harden the escalation email path (which reaches a human) against header/body injection and mailbox corruption.

Documentation changes

• Concept — docs/concepts/overseer-goal-board-health.md: the silent-failure gap fix(ooda): exempt standing/perpetual goals from the no-progress hard-block (#2589) #2609 left, the observe→signal→decide→act flow, self-heal vs escalate routing, guardrails (dedup, fail-closed identity, opt-out), invariants.
• How-to — docs/howto/configure-overseer-goal-board-health.md: SIMARD_OVERSEER_GOAL_HEALTH, reading the overseer::goal_health traces / tick counters / activity feed / goal-blocked notifications, and verifying with tests_goal_health.
• Reference — docs/reference/overseer-goal-board-health-api.md: the exact additive surface (BlockedGoal, blocked_goals_from_board, Signal::GoalBlocked, decide_blocked_goal, Intervention::{UnblockGoal,EscalateBlockedGoal}, ActOutcome variants, OperatorNotification::goal_blocked + OperatorNotifier, goal_health_enabled, the extended OverseerTickReport/OverseerTotals, and wiring). Synced with observe_board.
• Discoverability — mkdocs.yml nav entries; an index.md highlight; cross-links from the fix(ooda): exempt standing/perpetual goals from the no-progress hard-block (#2589) #2609 perpetual-goal concept and the overseer-activity-feed reference.

Code changes (follow-up commits, additive)

• src/overseer/notify.rs — SMTP hardening of the escalate NotifyOperator email path: sanitize headers against CRLF injection, dot-stuff the message body, and byte-bound headers. This is the channel that carries "needs human review" to a human, so it must not be corruptible by an attacker-influenced goal id/reason.
• src/overseer/mod.rs — observe the goal board once per tick (was twice) for perf; dedupe the goal-health suppress arms into one helper (refactor, no behaviour change).
• src/overseer/capabilities.rs / src/overseer/wiring.rs — the observe_board API (blocked_goals, in_flight) and its wiring.

Step 13: Local Testing Results

Detected toolchains:

• Rust / Cargo — Cargo.toml at repo root (name = "simard", edition = "2024", default-run = "simard"), Cargo.lock present. All changed source files are src/overseer/*.rs; the user/consumer boundary is the simard CLI (src/operator_cli/goal.rs, which honours SIMARD_STATE_ROOT) plus the Overseer OODA library. No Node/Python/Go manifests are involved. Per the qa-team skill's repo-type table, a Cargo.toml root ⇒ native cargo test, not the gadugi framework.

Chosen validation strategy:

• Drive the real simard goal CLI against an isolated SIMARD_STATE_ROOT temp dir (never ~/.simard, live daemon untouched) to reproduce the exact production false-park and exercise the self-heal's reused goal unblock operation from a user's perspective (Scenario 1), and run the injected-fake goal-health integration suite that exercises sensor → GoalBlocked signal → GoalHygiene problem → self-heal/escalate with fakes for goal-store/notify/whisper/clock/identity and no network (Scenario 2). Regression: full overseer:: and operator_cli::tests_goal suites; cargo fmt --check + cargo clippy --all-targets -- -D warnings clean.

Scenario 1 — CLI end-to-end: standing goal false-parked by OODA safeguard, then cleared via goal unblock (the exact op the self-heal reuses)

Command: SIMARD_STATE_ROOT=$(mktemp -d) simard goal add 3 --standing "Standing research goal"; simard goal list; <inject "🔒 [OODA-SAFEGUARD] … needs human review" Blocked marker>; simard goal list; simard goal unblock standing-research-goal; simard goal list
Result: PASS
Output (key lines):

[simard] goal add: 'standing-research-goal' added at p3 -> repo Simard (daemon) [standing/perpetual]
# after injecting the safeguard false-park, `goal list` surfaces it:
standing-research-goal  p3  blocked: 🔒 [OODA-SAFEGUARD] OODA goal made no shippable progress for 5 consecutive no-action cycles; needs human review  -  [standing] Standing research goal
# `goal unblock` — the operation the Overseer self-heal reuses:
[simard] goal unblock: 'standing-research-goal' restored to NotStarted (was: blocked: 🔒 [OODA-SAFEGUARD] … needs human review)
# final `goal list` — reactivated:
standing-research-goal  p3  not-started  -  [standing] Standing research goal

Scenario 2 — Injected-fake goal-health integration suite (observe → signal → self-heal + escalate, guardrails, failure isolation)

Command: cargo test --lib overseer::tests_goal_health
Result: PASS
Output (key lines):

running 11 tests
test overseer::tests_goal_health::blocked_goals_projection_surfaces_perpetual_and_needs_review_goals ... ok
test overseer::tests_goal_health::run_cycle_populates_observed_blocked_goals_and_emits_signals ... ok
test overseer::tests_goal_health::goal_blocked_signal_maps_to_a_goal_hygiene_problem ... ok
test overseer::tests_goal_health::perpetual_no_progress_goal_is_unblocked_once_and_not_escalated ... ok
test overseer::tests_goal_health::needs_review_goal_escalates_to_operator_on_both_channels ... ok
test overseer::tests_goal_health::self_heal_and_escalate_fail_closed_without_a_distinct_identity ... ok
test overseer::tests_goal_health::disabled_goal_health_holds_both_actions ... ok
test overseer::tests_goal_health::goal_health_enable_flag_is_opt_out_and_off_when_overseer_off ... ok
test overseer::tests_goal_health::a_failing_unblock_is_isolated_and_the_tick_survives ... ok
test overseer::tests_goal_health::decide_routes_a_blocked_goal_by_shape ... ok
test overseer::tests_goal_health::goal_health_interventions_are_routine_and_admitted_by_default_gate ... ok
test result: ok. 11 passed; 0 failed; 0 ignored; 0 measured; 7203 filtered out

Verification

• Outside-in CLI + integration — both Step 13 scenarios PASS (above).
• Regression — cargo test --lib overseer:: → 195 passed / 0 failed; cargo test --lib operator_cli::tests_goal → 28 passed / 0 failed.
• Lint/format — cargo fmt --check clean; cargo clippy --all-targets -- -D warnings → exit 0.
• Pre-push gates (no --no-verify) — Rust-only gate, cargo fmt --all -- --check, cargo test --release --lib race subset, and cargo clippy --all-targets --all-features --locked -- -D warnings all Passed on push.
• scripts/verify-docs.sh — 17/17 pass; mkdocs build --strict clean (0 broken links / anchors / orphaned nav pages).

Deploy note

No redeploy performed by this PR. The operator redeploys the Overseer daemon after merge (~/.simard and the live daemon were left untouched during development and testing).

Relates to #2609; extends #2616. Merged per policy: no git --no-verify, no gh pr merge --admin.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[github-actions]

📊 Coverage Summary

Generated by cargo llvm-cov --workspace --summary-only (nightly, excluding test files)

Module	Lines	Covered	Coverage
Total	136776	113253	82.8%

_{Coverage data from CI run. Test files matching tests?/ are excluded from line counts.}