Memory/Recovery Agent Completion Trace

Date: 2026-05-03

Scope decision

Phase 5 is complete as a gated selected-file recovery apply path for CLI/MCP. Phase 6 is complete as beginner-facing, read-only GUI agent cards for session memory and recovery recommendations. GUI destructive apply is intentionally out of scope for Phase 6 so the GUI does not create a second apply model; apply remains behind CLI/MCP grant, feature flag, typed-argument, confirmation, lock, sandwich checkpoint, and audit gates.

The source design is finalized as Completed product design in docs/superpowers/specs/2026-05-02-vibelign-memory-recovery-agent-design.md; the implementation spec is finalized as a Completed implementation baseline in docs/superpowers/specs/2026-05-02-vibelign-memory-recovery-agent-implementation-spec.md, with remaining unchecked items tracked as follow-up hardening rather than Phase 1–6 baseline blockers.

Completion-state interpretation: the product baseline is implemented, recovery apply remains default-off behind env-backed feature flag plus MCP grants, and the work is not release-certified / operationally complete until open hardening items 1–3 and 5 land. Items 1–3 provide lock-race safety plus measurable P0 audit evidence; item 5 prevents GUI/CLI/MCP contract drift. The Windows/macOS/WSL platform cases below are mostly required new coverage, not proof of existing coverage.

Follow-up code hardening priority

  1. Close the recovery lock TTL race in vibelign/core/recovery/locks.py / vibelign/core/recovery/apply.py, with tests for long-running restore, expiry, and competing lock ownership.
  2. Add audit integrity plus vibelign/core/memory/aggregator.py so P0 SLOs are backed by monotonic audit rows and count-only release-window summaries.
  3. Add vibelign/core/memory/retention.py for audit log rollover while preserving active P0 aggregation windows.
  4. Remove ambiguity around RecoveryApplyRequest.feature_enabled; real apply gates remain env-backed is_enabled("RECOVERY_APPLY") plus MCP grants.
  5. Add shared memory_state.schema.json and recovery_plan.schema.json contracts for GUI/CLI/MCP drift detection.
  6. Wire the optional Recovery Level 2 patch_suggester seam after safety and observability hardening.

Platform edge cases are part of this follow-up, not optional polish. Before each item is closed, Windows and macOS coverage must include lock TTL expiry races, drive/UNC/WSL path inputs, Windows reserved names and trailing-dot/space paths, macOS case-insensitive and Unicode-normalization collisions, symlink escapes, audit JSONL partial-line/rollover behavior, packaged GUI/MCP feature-flag behavior, and schema validation for Unicode plus normalized display paths. The full checklist lives in the implementation spec’s Windows/macOS implementation edge-case section.

2026-05-04 follow-up checklist

  • Guided + Assisted Recovery Agent product contract documented in the source design.
  • Next implementation slice documented in the implementation spec as Guided Recovery Agent with Assisted Apply.
  • Existing safety gates preserved: explain, recommend, preview, checkpoint sandwich, explicit confirmation, limited apply, result explanation.
  • GUI destructive apply remains prohibited unless it uses the same service-layer gates as CLI/MCP.
  • Memory/handoff free text remains data only; it cannot become executable recovery instruction.
  • VibeLign verification recorded for the follow-up docs update: recent change risk LOW, no protected or anchor violations.

Requirement trace

Requirement Evidence
Layer 4 memory text cannot invoke recovery apply tests/test_mcp_denied_capabilities.py::test_recovery_apply_ignores_free_text_memory_instructions
Drift accuracy circuit breaker degrades below 80% over 20 incidents tests/test_recovery_planner.py::test_drift_accuracy_circuit_breaker_degrades_to_diff_aware_mode
vib recover --preview read-only surface tests/test_vib_recover_cmd.py::test_run_vib_recover_preview_is_read_only_alias
vib recover --file read-only validation surface tests/test_vib_recover_cmd.py::test_run_vib_recover_file_preview_is_read_only
CLI explicit apply flags route through core apply tests/test_vib_cli_surface.py::test_vib_recover_parser_accepts_explicit_apply_arguments, tests/test_vib_recover_cmd.py::test_run_vib_recover_apply_routes_to_core_apply
Core recovery apply acquires lock, restores selected files, releases lock, writes count-only audit tests/test_recovery_apply_execution.py::test_execute_recovery_apply_restores_selected_files_with_lock_and_audit
Concurrent recovery apply returns busy without restoring tests/test_recovery_apply_execution.py::test_execute_recovery_apply_reports_busy_without_restoring
MCP recovery_apply denied by default and grant-only path remains gated tests/test_mcp_denied_capabilities.py, tests/test_mcp_recovery_handlers.py::test_recovery_apply_with_grant_but_without_feature_stays_denied
MCP grant plus feature gate executes selected-file apply tests/test_mcp_recovery_handlers.py::test_recovery_apply_executes_only_with_grant_and_feature_enabled
MCP env feature gate writes count-only audit without raw paths tests/test_mcp_recovery_handlers.py::test_recovery_apply_env_feature_gate_executes_without_raw_path_audit
MCP argument payload cannot bypass the env feature gate tests/test_mcp_recovery_handlers.py::test_recovery_apply_argument_cannot_bypass_env_feature_gate
Phase 6 GUI cards are present and wired into Home tests/test_gui_cli_contracts.py::test_agent_memory_cards_are_wired_into_gui_home
Apply requires preview paths before execution tests/test_recovery_apply_scaffold.py::test_validate_recovery_apply_request_requires_preview_paths_for_apply
Absolute path validation errors are redacted tests/test_recovery_apply_scaffold.py::test_validate_recovery_apply_request_redacts_absolute_path_errors
GUI cards surface verification freshness, drift candidates, and safe checkpoint details tests/test_gui_cli_contracts.py::test_agent_memory_cards_are_wired_into_gui_home

Manual QA evidence

  • Core apply stub QA: returned ok=true, would_apply=true, changed_files=["src/app.py"], changed_files_count=1, lock released, audit created.
  • MCP dispatch QA: default deny returned permission_denied; grant+feature returned ok=true, changed_files_count=1, would_apply=true.
  • CLI blocked apply QA without feature flag printed Recovery apply blocked, No files were modified., and feature-gate errors.
  • GUI build: rtk npm run build succeeded (tsc && vite build, built in 4.38s) with only existing Vite chunk-size warnings.
  • Oracle blocker fixes QA: focused blocker tests passed after enforcing preview_paths, redacting absolute path errors as <absolute-path>, and expanding GUI cards to display verification freshness, drift candidates, and safe checkpoint candidates.
  • Feature-gate bypass QA: focused safety tests passed after removing argument-level feature_enabled bypasses from core apply and MCP registry; live apply now requires VIBELIGN_RECOVERY_APPLY or internal env-backed feature enablement.

Final verification

  • Focused blocker tests: 19 passed via uv run --with pytest python -m pytest tests/test_recovery_apply_scaffold.py tests/test_recovery_apply_execution.py tests/test_gui_cli_contracts.py -q.
  • Focused Phase 5 gate tests: 22 passed in 0.24s via uv run --with pytest python -m pytest tests/test_recovery_apply_scaffold.py tests/test_recovery_apply_execution.py tests/test_recovery_apply_readiness.py tests/test_recovery_path_safety.py tests/test_vib_recover_cmd.py -q.
  • Focused feature-gate safety tests: 29 passed in 0.11s via uv run --with pytest python -m pytest tests/test_recovery_apply_scaffold.py tests/test_recovery_apply_execution.py tests/test_recovery_apply_readiness.py tests/test_mcp_recovery_handlers.py tests/test_mcp_denied_capabilities.py -q.
  • Focused traceability tests: 36 passed.
  • Final full suite: 1177 passed, 4 xfailed, 26 subtests passed in 56.14s via uv run --with pytest python -m pytest -q.