Work Packages: Fix Merge Target Branch Resolution

Inputs: Design documents from kitty-specs/049-fix-merge-target-resolution/ Prerequisites: plan.md (required), spec.md (user stories)

Tests: Regression tests are explicitly required by NFR-002.

Organization: Fine-grained subtasks (Txxx) roll up into work packages (WPxx). Each work package must be independently deliverable and testable.

Prompt Files: Each work package references a matching prompt file in tasks/ generated by /spec-kitty.tasks.

Work Package WP01: Fix Merge Target Resolution & Template (Priority: P1) MVP

Goal: Fix top-level spec-kitty merge to resolve target_branch from feature meta.json when --feature is provided, add branch existence validation, and align the merge command template to the canonical spec-kitty merge --feature <slug> path. Independent Test: Run spec-kitty merge --feature 049-fix-merge-target-resolution --dry-run --json and confirm target_branch reads from meta.json, not resolve_primary_branch(). Prompt: tasks/WP01-fix-merge-target-and-template.md Estimated prompt size: ~300 lines

Included Subtasks

  • ✅ T001 Fix target resolution logic in src/specify_cli/cli/commands/merge.py (lines 721-724)
  • ✅ T002 Add branch existence validation after target resolution (FR-006)
  • ✅ T003 Align src/specify_cli/missions/software-dev/command-templates/merge.md to canonical command path

Implementation Notes

  • T001: Port the pattern from feature.py lines 1337-1343. When feature is provided and target_branch is None, call get_feature_target_branch(repo_root, feature). When feature is not provided, call resolve_primary_branch(repo_root) (unchanged).
  • T002: After resolution, check if target branch exists locally (refs/heads/) or on remote (refs/remotes/origin/). If neither, hard error with actionable message referencing meta.json.
  • T003: Update merge.md so frontmatter and body both reference only spec-kitty merge --feature <slug>. Remove any mention of spec-kitty agent feature merge.

Parallel Opportunities

  • T001 and T003 modify different files and can be done in parallel.
  • T002 must follow T001 (extends the same code path).

Dependencies

  • None (starting package).

Risks & Mitigations

  • Regression in no-feature merge path → WP02 test case #6 explicitly covers this.
  • Branch existence check could be slow on large repos → Use git rev-parse --verify (fast, no network).

Work Package WP02: Regression Tests & Verification (Priority: P1)

Goal: Create comprehensive regression test suite proving all acceptance scenarios pass, and verify success criteria SC-001 through SC-004. Independent Test: python -m pytest tests/specify_cli/cli/commands/test_merge_target_resolution.py -v — all 7 tests pass. Prompt: tasks/WP02-regression-tests.md Estimated prompt size: ~350 lines

Included Subtasks

  • ✅ T004 Create tests/specify_cli/cli/commands/test_merge_target_resolution.py with 7 test cases
  • ✅ T005 Run tests and verify SC-001 through SC-004

Implementation Notes

  • T004: Unit tests with tmp_path for filesystem setup and mocked git commands. Each test creates a minimal kitty-specs/<slug>/meta.json fixture, then exercises the target resolution code path.
  • T005: Run full test suite, confirm no regressions. Optionally run manual --dry-run against a real feature to validate SC-001.

Test cases (all in T004):

1. Feature targets 2.x → resolves to "2.x" 2. Feature targets main → resolves to "main" 3. Missing meta.json → falls back to resolve_primary_branch() 4. Explicit --target overrides meta.json 5. Nonexistent target branch → hard error 6. No --feature flag → uses resolve_primary_branch() (backward compat) 7. Malformed meta.json → falls back to resolve_primary_branch()

Parallel Opportunities

  • None. Tests depend on WP01 fix being in place.

Dependencies

  • Depends on WP01.

Risks & Mitigations

  • Flaky tests from git subprocess mocking → Use unittest.mock.patch on subprocess.run with deterministic return values.

Dependency & Execution Summary

  • Sequence: WP01 → WP02
  • Parallelization: None (WP02 depends on WP01)
  • MVP Scope: WP01 alone eradicates the CRITICAL bug. WP02 provides proof.
  • Implementation commands:
  • spec-kitty implement WP01 (branches from 2.x)
  • spec-kitty implement WP02 --base WP01 (branches from WP01)

Subtask Index (Reference)

Subtask IDSummaryWork PackagePriorityParallel?
T001Fix target resolution in merge.pyWP01P1No
T002Add branch existence validationWP01P1No
T003Align merge.md templateWP01P1Yes
T004Create regression test file (7 tests)WP02P1No
T005Run tests and verify success criteriaWP02P1No

<!-- status-model:start -->

Canonical Status (Generated)

<!-- status-model:end -->

  • WP01: done
  • WP02: done