Review findings and roadmap

[patrick91]

Summary

This issue tracks the comprehensive review findings and the prioritized roadmap to fix correctness, UX, and stack management problems.

Key Findings

• get --downstack flag is defined but unused.
• GitRepo.commit bypasses hooks for non-interactive commits.
• Stack metadata in .git/shortcake.json is local-only and worktree-unaware.
• Worktree support is incomplete (hard-coded .git paths).
• create --insert updates parents but not parent_revision.
• move and split compute parent_revision from local trunk instead of origin/main.
• submit requires a clean tree even when no restack is needed.
• ls hides branches by rendering only the first child chain.
• Docs mismatch: README config path/format vs XDG TOML config.

Plan

Phase 1: Correctness and Data Safety

• Implement or remove get --downstack.
• Ensure hooks run for non-interactive commits.
• Use Repo.git_dir or git rev-parse --git-dir for metadata and split state paths.
• Update parent_revision when inserting branches.
• Normalize trunk refs to origin/main for parent revision calculations.
• Render all stack roots and children in ls.
• Align docs with actual config location/format.

Phase 2: UX Improvements

• Only require a clean tree in submit when restack is needed (or add --no-restack).
• Add a safe view/status command for stack inspection.
• Provide interactive nav up when multiple children exist.
• Add consistent --dry-run behavior across mutating commands.

Phase 3: Cross-Device Metadata

• Evaluate trailers vs notes for portable metadata.
• Add shortcake metadata migrate and shortcake metadata sync.
• Add fallback stack reconstruction when metadata is missing.

Phase 4: Workflow Enhancements

• Optional integration with git-absorb or git-autofixup.
• Add undo/runlog recovery commands.
• Consider a land/merge command for orderly stack landing.

Suggested Tests

• Worktree path handling for metadata and split state.
• submit behavior with dirty tree when restack not needed.
• create --insert parent revision updates.
• get --downstack behavior.

[patrick91]

Current status as of 2026-03-19:

Already addressed:

• submit no longer hard-fails just because the tree is dirty; it warns instead.
• ls renders parallel roots and branches correctly.
• multi-child up navigation exists.

Still relevant:

• worktree support remains incomplete.
• auxiliary local-only state still exists.
• several roadmap items are still open.

This tracker is partially stale; it would be worth trimming it down to the remaining items only.

[patrick91]

Triaged against main at 52da8bd.

This is still useful only as an umbrella tracker. A few items are now handled or tracked more specifically:

• sc move PR sync is implemented and sc move should probably update the PRs on GitHub immediately #112 is closed.
• sc pull whole-stack backfill exists; the remaining fetch gap is narrowed in sc checkout should fetch enough stack context for remote branches #32 to sc checkout stack context.
• Create error handling from Handle errors when creating better #7 is closed as completed.
• Worktree support remains open in Add support for worktrees #27.
• Crash recovery has been reframed in Handle crash recovery for interrupted insert operations #5 around interrupted insert operations.
• Local-only submit branch tracking remains open in Missing remote branch tracking after running shortcake submit on a local-only adopted branch #26.
• Custom branch names remain open in Add option to specify custom branch name #6.
• Issue-closing metadata is now clarified in Add sc create --closes support for issue-closing PR metadata #25.

Recommendation: either keep this as an umbrella, or trim the body down to links to the remaining focused issues.