Skip to content

feat(stack): add configurable readiness modes - #39

Draft
gabelease wants to merge 2 commits into
kitlangton:mainfrom
gabelease:feat/readiness-modes
Draft

feat(stack): add configurable readiness modes#39
gabelease wants to merge 2 commits into
kitlangton:mainfrom
gabelease:feat/readiness-modes

Conversation

@gabelease

@gabelease gabelease commented Jul 12, 2026

Copy link
Copy Markdown

Adds opt-in, provider-neutral readiness policy to stacked PR/MR workflows while preserving current behavior by default.

This PR is scoped only to readiness behavior. The independent Apple Git replay compatibility fix is isolated in #40.

Why

Today every newly created change is ready unless an operator manages draft state separately. On active stacks, that can trigger review and CI repeatedly as lower changes move.

  • Existing users need a no-surprises default.
  • Teams need a durable root-ready policy, not one-time host commands.
  • Converting an existing stack must be scoped, previewable, and reversible.

Key changes

Readiness policy

  • Adds unmanaged, all-ready, and root-ready modes.
  • Reads the default from git config stack.readinessMode.
  • Adds one-command --readiness-mode overrides to sync and merge.
  • Keeps unmanaged as the default, including host-default readiness for new changes.

Host behavior and safety

  • Implements draft/ready creation and transitions for GitHub and GitLab.
  • Uses sync as the explicit conversion path for existing stacks.
  • Applies readiness only after branch repair, pushes, retargeting, and description updates.
  • Refuses to promote a draft current root immediately before merge; operators sync it first and wait for resulting requirements.
  • Journals prior readiness so undo --apply restores surviving changes safely.

Operational guidance

  • Documents that linked worktrees share stack metadata, the undo journal, and repo-local config.
  • Requires branch-scoped mutations for independently owned worktree stacks.
  • Adds a minor changeset and updates the packaged skill.

Risks and review focus

Risk: changing readiness can trigger code-host automation.
→ Promotions occur only after repair is complete; default unmanaged performs no readiness transitions.

Risk: undo state is shared across linked worktrees.
→ Documentation makes ownership and single-journal behavior explicit, and scoped tests prove independent stacks are not touched.

Review focus: readiness journaling, provider transitions, and post-merge baseline behavior in Stack.

Test plan

bun run typecheck
PATH=/opt/homebrew/bin:$PATH bun run test
bun run lint
bun run format:check
bun run package:smoke
bun run changeset:status --since upstream/main
bun src/cli.ts sync --help
bun src/cli.ts merge --help

All 146 tests pass with Git 2.50.1. On Apple Git 2.39.5, the same seven real-Git tests fail on both upstream main and this branch because cherry-pick --empty=drop is unsupported; #40 isolates that compatibility fix.

Rollback

Revert the readiness feature and release commits. Existing installations remain behaviorally unchanged unless a managed readiness mode is configured or passed explicitly.

@hungmuha hungmuha left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM — well-tested, type-safe readiness modes with sound undo/journal integrity and safe defaults. One release-hygiene nit below.

Comment thread .changeset/calm-stacks-ready.md Outdated
@@ -0,0 +1,5 @@
---
"@kitlangton/stack": patch

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: Changeset is marked patch, but this adds a user-facing feature (the stack.readinessMode config key plus --readiness-mode flags on sync and merge). Prior releases bumped analogous additions as minor — e.g. CHANGELOG 0.3.0 stack.blockLink/stack.trunks and 0.4.0 stack skill are all Minor Changes. Consider minor to match convention.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah totally right. Will fix.

Keep prior behavior under unmanaged while allowing sync and merge to enforce all-ready or root-ready across GitHub and GitLab. Readiness changes run after repair and description updates, and the undo journal preserves prior states so conversions remain reversible.
@gabelease
gabelease force-pushed the feat/readiness-modes branch from c1a6aad to 9bd6e16 Compare July 14, 2026 05:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants