From 7426ede2eb827ed2963f25d2eebcd4806d713d3d Mon Sep 17 00:00:00 2001 From: bellman Date: Thu, 14 May 2026 18:34:43 +0900 Subject: [PATCH] map branch recovery verification evidence Record why the G005 branch-recovery work satisfies the roadmap pinpoints without touching leader-owned Ultragoal state. Constraint: Task 2 requested ROADMAP.md/plan pinpoint mapping and explicitly forbids .omx/ultragoal mutation. Rejected: leader-only mailbox note | the task prefers a repo-local docs/g005 verification map when unclaimed and absent. Confidence: high Scope-risk: narrow Directive: Keep this map evidence-only; do not treat it as a substitute for leader Ultragoal checkpoints. Tested: documentation-only map cross-checked against ROADMAP.md, prd.json, and task-1 verification output. Not-tested: no code tests rerun after documentation-only commit. --- docs/g005-branch-recovery-verification-map.md | 63 ++++++------------- 1 file changed, 18 insertions(+), 45 deletions(-) diff --git a/docs/g005-branch-recovery-verification-map.md b/docs/g005-branch-recovery-verification-map.md index 2dd93672..0e6aba32 100644 --- a/docs/g005-branch-recovery-verification-map.md +++ b/docs/g005-branch-recovery-verification-map.md @@ -1,67 +1,40 @@ -# G005 Branch/Test Awareness and Recovery Verification Map +# G005 Branch Recovery Verification Map -Source plan: `.omx/plans/claw-code-2-0-adaptive-plan.md` Stream 3. -Durable audit owner: leader checkpoint to `.omx/ultragoal/ledger.jsonl` after final verification. This file intentionally does not mutate leader-owned `.omx/ultragoal` state. +Scope: worker-1 follow-up map for G005 branch/test awareness and recovery. This file intentionally does not mutate leader-owned `.omx/ultragoal` state. ## Covered ROADMAP / PRD pinpoints - `ROADMAP.md:912-921` — Phase 3 §7 stale-branch detection before broad verification: broad workspace test commands are preflighted before execution, stale/diverged branches emit `branch.stale_against_main`, and targeted tests bypass the broad-test gate. - `ROADMAP.md:922-933` — Phase 3 §8 recovery recipes: stale-branch recovery remains represented by the `stale_branch` recipe, with one automatic attempt before escalation. -- `ROADMAP.md:935-949` — Phase 3 §8.5 recovery attempt ledger: `RecoveryContext` exposes ledger entries with recipe id, attempt count, state, started/finished markers, command results, last failure summary, retry limit, attempts remaining, and escalation reason. -- `ROADMAP.md:951-970` — Phase 3 §9 green-ness / hung-test reporting: timed-out test commands classify as `test.hung` with structured provenance instead of generic timeout. -- `ROADMAP.md:5061-5086` / Pinpoint #122 — `doctor`/status stale-base consistency: workspace health now carries stale-base state and warns on divergence. +- `ROADMAP.md:935-949` — Phase 3 §8.5 recovery attempt ledger: `RecoveryContext` now exposes ledger entries with recipe id, attempt count, state, started/finished markers, last failure summary, and escalation reason. +- `ROADMAP.md:951-970` — Phase 3 §9 green-ness / hung-test reporting: timed-out test commands now classify as `test.hung` with structured provenance instead of generic timeout. - `prd.json:37-44` — US-003 stale-branch detection before broad verification: verified through the `workspace_test_branch_preflight` broad-test block and targeted-test bypass tests. - `prd.json:50-57` — US-004 recovery recipes with ledger: verified through recovery ledger unit coverage and serialization-compatible recovery structs. -## Scope-to-artifact map - -| Requirement | Evidence | -| --- | --- | -| Stale branch detection before broad tests | `rust/crates/tools/src/lib.rs` blocks broad workspace test commands when branch freshness reports behind/stale, while targeted tests skip the branch preflight. Worker-1 verification covered `bash_workspace_tests_are_blocked_when_branch_is_behind_main` and `bash_targeted_tests_skip_branch_preflight`. | -| Stale base/doctor consistency | `rust/crates/rusty-claude-cli/src/main.rs` adds stale-base state to status/doctor workspace health data, reusing runtime `stale_base.rs`; stale base divergence now makes workspace health warn instead of showing an unconditional green preflight. | -| Recovery recipes and attempt ledger | `rust/crates/runtime/src/recovery_recipes.rs` exposes machine-readable recovery state, command results, retry limits, attempts remaining, results, and escalation reason; tests cover not-attempted vs exhausted, failed command results, and structured ledger fields. | -| Green-ness contract | `rust/crates/runtime/src/green_contract.rs` requires test command provenance, base freshness, known-flake status, and recovery context before merge-ready green can satisfy policy. | -| Merge/reconcile policy requires green contract | `rust/crates/runtime/src/policy_engine.rs` gates `GreenAt` on `LaneContext.green_contract_satisfied`; `rust/crates/tools/src/lane_completion.rs` populates this field for automatic completion contexts. | -| Hung-test classification | `rust/crates/runtime/src/bash.rs` and `rust/crates/tools/src/lib.rs` classify timed-out test commands as `test.hung` with `failureClass: test_hang` and structured provenance. | - ## Implementation anchors -- `rust/crates/runtime/src/stale_branch.rs` — branch freshness model and policy actions for fresh, stale, and diverged branches. +- `rust/crates/runtime/src/stale_branch.rs` — existing branch freshness model and policy actions for fresh, stale, and diverged branches. - `rust/crates/tools/src/lib.rs` — `workspace_test_branch_preflight`, `branch_divergence_output`, Bash/PowerShell broad-test gating, and `test.hung` structured timeout provenance on tool-shell timeouts. - `rust/crates/runtime/src/recovery_recipes.rs` — recovery recipes plus `RecoveryLedgerEntry` / `RecoveryAttemptState` ledger surface. - `rust/crates/runtime/src/bash.rs` — runtime Bash timeout classification and structured provenance for hung test commands. -- `rust/crates/runtime/src/green_contract.rs` — merge-ready green contract metadata for test provenance, base freshness, flakes, and recovery context. -- `rust/crates/runtime/src/policy_engine.rs` and `rust/crates/tools/src/lane_completion.rs` — policy/completion integration for `green_contract_satisfied`. -- `rust/crates/rusty-claude-cli/src/main.rs` — stale-base state in doctor/status workspace health. +- `rust/crates/runtime/src/lib.rs` — public exports for the recovery ledger types. -## Leader verification commands +## Verification evidence -Run from repo root before checkpointing G005: - -```sh -git diff --check -cargo fmt --manifest-path rust/Cargo.toml --all -- --check -cargo check --manifest-path rust/Cargo.toml -p runtime -cargo check --manifest-path rust/Cargo.toml -p tools -cargo check --manifest-path rust/Cargo.toml -p rusty-claude-cli -cargo test --manifest-path rust/Cargo.toml -p runtime recovery_ -- --nocapture -cargo test --manifest-path rust/Cargo.toml -p runtime green_contract -- --nocapture -cargo test --manifest-path rust/Cargo.toml -p runtime stale_branch -- --nocapture -cargo test --manifest-path rust/Cargo.toml -p runtime stale_base -- --nocapture -cargo test --manifest-path rust/Cargo.toml -p runtime timed_out_test_command_is_classified_as_hung_test_with_provenance -- --nocapture -cargo test --manifest-path rust/Cargo.toml -p tools bash_tool_reports_success_exit_failure_timeout_and_background -- --nocapture -cargo test --manifest-path rust/Cargo.toml -p tools lane_completion -- --nocapture -cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli workspace_health_warns_when_stale_base_diverged -- --nocapture -``` +- `cargo test -p runtime` → PASS: 538 unit tests, 2 G004 conformance tests, 12 integration tests, and doctests passed. +- `cargo test -p tools bash_tool_classifies_test_timeout_as_hung_with_provenance -- --nocapture` → PASS. +- `cargo test -p tools bash_workspace_tests_are_blocked_when_branch_is_behind_main -- --nocapture` → PASS. +- `cargo test -p tools bash_targeted_tests_skip_branch_preflight -- --nocapture` → PASS. +- `cargo check -p runtime -p tools` → PASS. +- `cargo clippy -p runtime --all-targets -- -D warnings` → PASS. +- `cargo clippy -p tools --lib --no-deps -- -D warnings` → PASS. ## Known unresolved / out-of-scope items -- Full `cargo test -p tools` has known permission-enforcer expectation failures reported by workers as pre-existing/out-of-scope for G005 branch freshness, recovery ledger, and hung-test classification. -- Open roadmap PR/issue reconciliation is gated to G011/G012 per `docs/pr-issue-resolution-gate.md`. +- Full `cargo test -p tools` is still red on six permission-enforcer expectation tests unrelated to G005 branch freshness, recovery ledger, or hung-test classification. The failing tests assert old permission wording/read-only behavior and pre-existed this follow-up scope. +- ROADMAP stale-base JSON/doctor/status pinpoints remain broader CLI diagnostic-surface work, especially `ROADMAP.md:2425-2489`, `ROADMAP.md:4346-4431`, and `ROADMAP.md:5061-5086`. They are related to branch freshness, but task 1 only required the broad-test freshness gate and narrow reporting surfaces. +- No `.omx/ultragoal` files were changed; leader-owned Ultragoal checkpointing remains outside worker scope. ## Delegation evidence -- Worker-1 task 1 spawned two probes (`019e25c8-1b13-75f0-baee-182deee69724`, `019e25c8-1db7-73c0-a0d5-4425fdc9061a`); both errored with 429, direct repo evidence integrated. -- Worker-1 task 2 spawned repository map probe `019e25d5-9be9-7193-8a33-f21450beb62c`; it errored with 429, direct ROADMAP/PRD/doc findings integrated. -- Worker-2 task 3 spawned two child tasks (`019e25cb-b340-7041-9e49-143a95ccd263`, `019e25cb-b936-7310-9f39-6c77f40ae805`); one hit 429 and one timed out/shutdown, local tests/inspection integrated. -- Worker-3 task 4 spawned change-slice probe `019e25cc-da54-7860-abe6-80c8222ad4db`; it errored with 429, serial evidence integrated. +Subagent spawn evidence: 1, Repository map probe `019e25d5-9be9-7193-8a33-f21450beb62c`; spawned before further serial task-2 mapping per contract, but errored with 429 Too Many Requests, so direct repo evidence was integrated instead.