Update documentation with 9 changed files (#4522)

docs/howto/converge-a-stuck-red-canary-self-deploy.md

@@ -8,6 +8,7 @@ doc_type: howto
 status: active
 related:
   - ../reference/canary-gate-convergence.md
+  - ../reference/canary-unit-test-gate-diagnostics.md
   - ../reference/overseer-deploy-canary-diagnostics.md
   - ../reference/self-deploy-api.md
   - ../reference/overseer-tick-self-healing.md
@@ -150,6 +151,10 @@ simard status | grep -Ei 'deploy_drift|running_commit'
 - [Canary gate isolation and self-deploy convergence](../reference/canary-gate-convergence.md) —
   the full design: per-gate spans, `canary_env`, `scrub_gate_env`, and the
   preserved fail-closed invariants.
+- [Diagnosable canary unit-test gate](../reference/canary-unit-test-gate-diagnostics.md) —
+  why the `unit-test` gate detail now names the failing test: the
+  `cargo test --lib` scope alignment and the `parse_unit_test_failure` /
+  `truncate_output_tail` capture of stdout+stderr (#4522).
 - [Overseer deploy red-canary diagnostics](../reference/overseer-deploy-canary-diagnostics.md) —
   how the reddening gate is named in the tick WARN and the operator
   notification.

docs/index.md

@@ -160,6 +160,7 @@ Bare `simard` prints the unified help text instead of attempting a hidden enviro
 - [Overseer tick self-healing reference](./reference/overseer-tick-self-healing.md) - The transient-failure self-healing rung on the `overseer` meta-thread's per-tick health: a `cycle_failed` tick whose `run_cycle()` error is a transient upstream blip (5xx, timeout, connection reset, rate-limit) routes to a self-clearing `"backoff"` for one cadence instead of `"erroring"`. Covers the additive `transient_cycle_failure` field, the fail-closed `is_transient` classifier, the bounded consecutive-transient escalation ceiling, and the safety invariants (#893).
 - [Overseer deploy red-canary diagnostics reference](./reference/overseer-deploy-canary-diagnostics.md) - The additive diagnostics that make a refused self-deploy diagnosable: the reddening canary gate name and detail surfaced into the `overseer::deploy` WARN and OTel attributes (`failing_gate` / `failing_detail`), the `CanaryResult.failing_gate` / `failing_detail` fields, `CanaryResult::refusal_reason`, the enriched `deploy_refused` notification and `Capability` detail, and the fail-closed `is_transient` `deploy_gate` / `target_canary` guard that stops a red canary being retried as a transient blip (#4420).
 - [Canary gate isolation and self-deploy convergence reference](./reference/canary-gate-convergence.md) - The #4440 root-cause repair that acts on those diagnostics so a healthy candidate self-deploys and `DeployDrift` returns to 0: per-gate `self_relaunch::gate` tracing/OTel spans in `verify_canary`, the additive `RelaunchConfig.canary_env` narrow allow-list plus `scrub_gate_env` that supplies a gate's legitimately-missing signal without weakening fail-closed semantics, and the self-deploy loop advancing past the stuck target SHA. See the [convergence runbook](./howto/converge-a-stuck-red-canary-self-deploy.md).
+- [Diagnosable canary unit-test gate reference](./reference/canary-unit-test-gate-diagnostics.md) - The #4522 follow-on that ends the red-canary crash-loop on the relaunch `unit-test` gate: `run_unit_test_gate` aligns to the proven-green `cargo test --lib` scope (the all-targets scope dragged `SIMARD_*`-dependent integration binaries into the scrubbed subprocess and aborted with exit 101 before any summary), captures **both** stdout and stderr, and `parse_unit_test_failure` + `truncate_output_tail` surface the failing test name and `test result: FAILED` line via structured `tracing` (never `print!`), without weakening the `LD_PRELOAD`/hijack-class deny-by-default scrub.
 - [How to review the Overseer's workstream gaps](./howto/review-overseer-workstream-gaps.md) - Read, act on, and tune the Overseer's recurring "what workstreams are we missing?" gap-scan — the uncovered high-priority goals, high-signal issues, and unaddressed anomalies it flags each tick, where the deduped notification appears, and the `SIMARD_OVERSEER_GAP_SCAN` knobs (#2630).
 - [Overseer workstream gap-scan reference](./reference/overseer-workstream-gap-scan.md) - The additive Observe→Orient→Act gap-scan: the `Signal::WorkstreamGap`/`GapItem`/`ProblemKind::WorkstreamCoverage` model, the coverage-set detection contract, the deduped NotifyOperator act path, the `SIMARD_OVERSEER_GAP_SCAN` configuration, and the additive `OverseerTickReport.workstream_gaps_detected` counter (#2630).
 - [Overseer recipe-launch idempotency reference](./reference/overseer-recipe-launch-idempotency.md) - The launcher-level rail that makes `AmplihackRecipeRunner::spawn` idempotent per task signature: the pure `recipe_signature` normalization (`target_repo` + `task_description`, trim/lowercase/whitespace-collapse, `\u{1F}` separator), the reap-then-dedup order, the fail-visible `overseer::recipe` suppressed-launch warning, the shared-handle `probe` semantics, and the injectable `ChildSpawner`/`SpawnedChild` test seam — so a still-blocked signature no longer spawns a byte-identical `smart-orchestrator` every tick (#4125).

docs/reference/canary-gate-convergence.md

@@ -8,6 +8,7 @@ doc_type: reference
 status: implemented
 related:
   - ./overseer-deploy-canary-diagnostics.md
+  - ./canary-unit-test-gate-diagnostics.md
   - ./self-deploy-api.md
   - ./self-deploy-source-prep.md
   - ./overseer-tick-self-healing.md
@@ -366,6 +367,10 @@ green."
 
 ## See also
 
+- [Diagnosable canary unit-test gate](./canary-unit-test-gate-diagnostics.md) —
+  the #4522 follow-on that fixes the `unit-test` gate itself: `cargo test --lib`
+  scope alignment and the `parse_unit_test_failure` / `truncate_output_tail`
+  diagnostics that name the failing test in the gate detail.
 - [Overseer deploy red-canary diagnostics](./overseer-deploy-canary-diagnostics.md) —
   the #4420 observability this repair acts on (`failing_gate` / `failing_detail`,
   `refusal_reason`, the `overseer::deploy` WARN, the `is_transient` guard).