diff --git a/MERGE_CHECKLIST.md b/MERGE_CHECKLIST.md new file mode 100644 index 0000000..0485fb0 --- /dev/null +++ b/MERGE_CHECKLIST.md @@ -0,0 +1,208 @@ +# Merge Checklist — claw-code + +**Purpose:** Streamline merging of the 17 review-ready branches by grouping them into safe clusters and providing per-cluster merge order + validation steps. + +**Generated:** Cycle #70 (2026-04-23 03:55 Seoul) + +--- + +## Merge Strategy + +**Recommended order:** P0 → P1 → P2 → P3 (by priority tier from REVIEW_DASHBOARD.md). + +**Batch strategy:** Merge by cluster, not individual branches. Each cluster shares the same fix pattern, so reviewers can validate one cluster and merge all members together. + +**Estimated throughput:** 2-3 clusters per merge session. At current cycle velocity (~1 cluster per 15 min), full queue → merged main in ~2 hours. + +--- + +## Cluster Merge Order + +### Cluster 1: Typed-Error Threading (P0) — 3 branches + +**Members:** +- `feat/jobdori-249-resumed-slash-kind` (commit `eb4b1eb`, 61 lines) +- `feat/jobdori-248-unknown-verb-option-classify` (commit `6c09172`) +- `feat/jobdori-251-session-dispatch` (commit `dc274a0`) + +**Merge prerequisites:** +- [ ] All three branches built and tested locally (181 tests pass) +- [ ] All three have only changes in `rust/crates/rusty-claude-cli/src/main.rs` (no cross-crate impact) +- [ ] No merge conflicts between them (all edit non-overlapping regions) + +**Merge order (within cluster):** +1. #249 (smallest, lowest risk) +2. #248 (medium) +3. #251 (largest, but depends on #249/#248 patterns) + +**Post-merge validation:** +- Rebuild binary: `cargo build -p rusty-claude-cli` +- Run: `./target/debug/claw version` (should work) +- Run: `cargo test -p rusty-claude-cli` (should pass 181 tests) + +**Commit strategy:** Rebase all three, squash into single "typed-error: thread kind+hint through 3 families" commit, OR merge individually preserving commit history for bisect clarity. + +--- + +### Cluster 2: Diagnostic-Strictness (P1) — 3 branches + +**Members:** +- `feat/jobdori-122-doctor-stale-base` (commit `5bb9eba`) +- `feat/jobdori-122b-doctor-broad-cwd` (commit `0aa0d3f`) +- `fix/jobdori-161-worktree-git-sha` (commit `c5b6fa5`) + +**Merge prerequisites:** +- [ ] #122 and #122b are binary-level changes, #161 is build-system change +- [ ] All three pass `cargo build` +- [ ] No cross-crate merge conflicts + +**Why these three together:** All share the diagnostic-strictness principle. #122 and #122b extend `doctor`, #161 fixes `version`. Merging as a cluster signals the principle to future reviewers. + +**Post-merge validation:** +- Rebuild binary +- Run: `claw doctor` (should now check stale-base + broad-cwd) +- Run: `claw version` (should report correct SHA even in worktrees) +- Run: `cargo test` (full suite) + +**Commit strategy:** Merge individually preserving history, then add ROADMAP commit explaining the cluster principle. This makes the doctrine visible in git log. + +--- + +### Cluster 3: Help-Parity (P1) — 4 branches + +**Members:** +- `feat/jobdori-130b-filesystem-context` (commit `d49a75c`) +- `feat/jobdori-130c-diff-help` (commit `83f744a`) +- `feat/jobdori-130d-config-help` (commit `19638a0`) +- `feat/jobdori-130e-dispatch-help` + `feat/jobdori-130e-surface-help` (commits `0ca0344`, `9dd7e79`) + +**Merge prerequisites:** +- [ ] All four branches edit help-topic routing in the same regions +- [ ] Verify no merge conflicts (should be sequential, non-overlapping edits) +- [ ] `cargo build` passes + +**Why these four together:** All address help-parity (verbs in `--help` → correct help topics). This cluster is the most "batch-like" — identical fix pattern repeated. + +**Post-merge validation:** +- Rebuild binary +- Run: `claw diff --help` (should route to help topic, not crash) +- Run: `claw config --help` (ditto) +- Run: `claw --help` (should list all verbs) + +**Merge strategy:** Can be fast-forwarded or squashed as a unit since they're all the same pattern. + +--- + +### Cluster 4: Suffix-Guard (P2) — 2 branches + +**Members:** +- `feat/jobdori-152-init-suffix-guard` (commit `860f285`) +- `feat/jobdori-152-bootstrap-plan-suffix-guard` (commit `3a533ce`) + +**Merge prerequisites:** +- [ ] Both branches add `rest.len() > 1` check to no-arg verbs +- [ ] No conflicts + +**Post-merge validation:** +- `claw init extra-arg` (should reject) +- `claw bootstrap-plan extra-arg` (should reject) + +**Merge strategy:** Merge together. + +--- + +### Cluster 5: Verb-Classification (P2) — 1 branch + +**Member:** +- `feat/jobdori-160-verb-classification` (commit `5538934`) + +**Merge prerequisites:** +- [ ] Binary tested (23-line change to parser) +- [ ] `cargo test` passes 181 tests + +**Post-merge validation:** +- `claw resume bogus-id` (should emit slash-command guidance, not missing_credentials) +- `claw explain this` (should still route to Prompt) + +**Note:** Can merge solo or batch with #4. No dependencies. + +--- + +### Cluster 6: Doc-Truthfulness (P3) — 2 branches + +**Members:** +- `docs/parity-update-2026-04-23` (commit `92a79b5`) +- `docs/jobdori-162-usage-verb-parity` (commit `48da190`) + +**Merge prerequisites:** +- [ ] Both are doc-only (no code risk) +- [ ] USAGE.md sections match verbs in `--help` +- [ ] PARITY.md stats are current + +**Post-merge validation:** +- `claw --help` (all verbs listed) +- `grep "dump-manifests\|bootstrap-plan" USAGE.md` (should find sections) +- Read PARITY.md (should cite current date + stats) + +**Merge strategy:** Can merge in any order. + +--- + +## Merge Conflict Risk Assessment + +**High-risk clusters (potential conflicts):** +- Cluster 1 (Typed-error) — all edit `main.rs` dispatch/error arms, but in different methods (likely non-overlapping) +- Cluster 3 (Help-parity) — all edit help-routing, but different verbs (should sequence cleanly) + +**Low-risk clusters (isolated changes):** +- Cluster 2 (Diagnostic-strictness) — #122 and #122b both edit `check_workspace_health()`, could conflict. #161 edits `build.rs` (no overlap). +- Cluster 4 (Suffix-guard) — two independent verbs, no conflict +- Cluster 5 (Verb-classification) — solo, no conflict +- Cluster 6 (Doc-truthfulness) — doc-only, no conflict + +**Conflict mitigation:** Merge Cluster 2 sub-groups: (#122 → #122b → #161) to avoid simultaneous edits to `check_workspace_health()`. + +--- + +## Post-Merge Validation Checklist + +**After all clusters are merged to main:** + +- [ ] `cargo build --all` (full workspace build) +- [ ] `cargo test -p rusty-claude-cli` (181 tests pass) +- [ ] `cargo fmt --all --check` (no formatting regressions) +- [ ] `./target/debug/claw version` (correct SHA, not stale) +- [ ] `./target/debug/claw doctor` (stale-base + broad-cwd warnings work) +- [ ] `./target/debug/claw --help` (all verbs listed) +- [ ] `grep -c "### \`" USAGE.md` (all 12 verbs documented, not 8) +- [ ] Fresh dogfood run: `./target/debug/claw prompt "test"` (works) + +--- + +## Timeline Estimate + +| Phase | Time | Action | +|---|---|---| +| Merge Cluster 1 (P0 typed-error) | ~15 min | Merge 3 branches, test, validate | +| Merge Cluster 2 (P1 diagnostic-strictness) | ~15 min | Merge 3 branches (mind #122/#122b conflict) | +| Merge Cluster 3 (P1 help-parity) | ~20 min | Merge 4 branches (batch-friendly) | +| Merge Cluster 4–6 (P2–P3, low-risk) | ~10 min | Fast merges | +| **Total** | **~60 min** | **All 17 branches → main** | + +--- + +## Notes for Reviewer + +**Branch-last protocol validation:** All 17 branches here represent work that was: +1. Pinpoint filed (with repro + fix shape) +2. Implemented in scratch/worktree (not directly on main) +3. Verified to build + pass tests +4. Only then branched for review + +This artifact provides the final step: **validated merge order + per-cluster risks.** + +**Integration-support artifact:** This checklist reduces reviewer cognitive load by pre-answering "which merge order is safest?" and "what could go wrong?" questions. + +--- + +**Checklist source:** Cycle #70 (2026-04-23 03:55 Seoul)