032 — tp story land puts a story in a pull request into the base under maturity.flow trunk (#202)

Status: in progress Roadmap: #196

Why

At code level 1 a story reaches the base branch only as part of a release: tp release on its branch either makes the release commits there (a lone release) or sends it through release (a batch), and a second story converts one into the other (ADR 0007). Whoever runs it, usually an agent, has to work out which of those states the repository is in before every step, and the story's own run decides a version it should know nothing about.

Trunk-based development keeps the two acts apart: a short-lived branch is integrated into the trunk when it is ready, and a release is made from the trunk later. This story is the first half, built beside the batch and chosen by a temporary key (ADR 0008), so it ships in an ordinary release without changing any project that has not asked for it.

Vocabulary

Term Meaning
land put a story branch in a pull request into the base branch: base merged in, checks passed, pushed. No version, no release commits
trunk flow code level 1 or 2 with maturity.flow: trunk: stories land; a release is made on the base branch
batch flow code level 1 or 2 without the key: today's process

What changes

  • task-plus.yml: maturity.flow, empty or trunk. Any other value is a config error. trunk at code level 0 is a config error: level 0 commits to the base and has nothing to land.
  • tp story land [-dry-run] (new): on a story branch under trunk flow, merges the remote base branch into it when the base has moved, runs the checks, pushes and opens the pull request into the base branch, titled by the story's fragment. An open pull request is reused. The run ends there: the merge is the human's.
  • tp release under trunk flow refuses: on a story branch it names tp story land; on the base branch it says the release from the base is #197.
  • docs/story.md, docs/maturity.md: the command and the key.

Acceptance

tp story land:

Flow Branch State Outcome
batch, or code 0 any any error naming maturity.flow: trunk; nothing done
trunk the base branch any error: land runs on a story branch
trunk not story/<n>-<slug> any error naming the form
trunk story working tree dirty error; nothing done
trunk story release on the remote error: a batch is in flight, finish it first
trunk story no changes/<n>.<kind>.md error naming the file to add
trunk story CHANGELOG names an untagged version (a lone release's commits) error: land takes no release commits
trunk story already in the base branch says so; nothing pushed, no pull request
trunk story its last pull request closed without merging error: reopen it or close the story
trunk story its pull request open into another branch error: retarget or close it
trunk story level with the base checks, push, pull request into the base titled by the fragment; CHANGELOG and fragment untouched; no tag
trunk story base has moved, merges cleanly the remote base merged in, then as above
trunk story base has moved, conflicts the merge is left in progress; error names the files; nothing pushed
trunk story checks fail error; nothing pushed, no pull request
trunk story its pull request into the base open checks, push; the pull request reused
trunk story -dry-run each step printed; nothing merged, pushed or opened

tp release:

Flow Branch Outcome
trunk story error naming tp story land
trunk the base branch error: the release from the base under trunk flow is #197
batch any as today

Out of scope

  • The release from the base under trunk flow (#197) and tp release query (#198).
  • Waiting for the merge: merge_wait is not read by tp story land.
  • A worktree per story (#193).
  • Removing the batch and the key (#199).

Decisions

ADR 0008.

Done when

  • tests express the acceptance table and pass
  • spec updated
  • ADR written if a fork was resolved
  • roadmap ticked and stamped; changelog entry
  • issue closed with a link to the release