0008 — A story lands on the base branch; a release is made there

Status: accepted (amends 0006 while maturity.flow exists; supersedes 0005 and 0007 when #199 removes the batch) Date: 2026-11-13 Story: stories/032-tp-story-land-puts-a-story-in-a-pull-request-into.md

Context

At code level 1 a story reaches the base branch only as part of a release. That one coupling is why release collects stories (0005), why a lone story carries release commits and a second story has to undo them (0007), and why tp release query exists to say which of those states a checkout is in. The agents doing the stories lose their place in it.

Trunk-based development names the shape: release receives work before the trunk does and is merged into it, where the site's release branch is cut from the trunk, takes only cherry-picks from it and is never merged back. It keeps integrating and releasing apart: short-lived branches merge to the trunk one at a time, the trunk stays releasable, and a release is made from it.

The fragments already let stories be prepared in parallel without touching a shared file, so nothing about the CHANGELOG needs release.

Options

How a release is made once stories merge to the base on their own, the base branch refusing direct pushes:

Option Complexity Testability Domain clarity Operational risk
A. tp release on the base gathers changes/ into a release/vX.Y.Z pull request, merges it and tags the merge 0001's shape; the batch code goes real git in a temp dir, a fake forge a story lands, a release is one generated commit a story that lands mid-release leaves its fragment for the next version: refuse to tag while fragments remain
B. The tag is the release; the CHANGELOG is rendered from fragments and tags a renderer; README version markers need another home parsing tests the purest release from trunk no committed CHANGELOG.md, against the project convention
C. tp pushes the release commit through a protection allow-list a bypass per forge needs a forge protection becomes "except tp" rejected in 0007
D. Keep the batch none as today integrating and releasing stay one act the states 0007 added, and their cost to agents, stay

How it is introduced:

Option Complexity Domain clarity Operational risk
R. Redefine code level 1 in one release one large story one fact picks the process every level 1 project changes on upgrade; tp releases itself with the process it is replacing
N. A new code level a rung beside batch the ladder orders gates; this is not a stricter gate than batch projects pass through a level they do not want (0006's objection to its option B)
K. A temporary maturity.flow: trunk beside the batch, then R two processes in the tree for a few releases a second fact, declared, with a removal story the key outlives its purpose: #199 removes it

Decision

A and K. Under maturity.flow: trunk at code level 1 and up a story lands with tp story land, which merges the base in, checks, pushes and opens the pull request into the base, and decides no version; tp release runs on the base branch only (#197). Each story of the epic ships in a batch release with the new process unreachable unless the key is set: branch by abstraction, the key the switch. When it has been used on task-plus and one other project, #199 makes it what code level 1 means and deletes the batch and the key.

The ladder then orders how work reaches the trunk, which is what the site's styles order: 0 commits to it, 1 a story pull request, 2 the same with CI required. A release is the same act at every level.

Unfinished work that must merge is kept out of reach by not wiring it in, or by a declared key such as this one; tp provides no flag framework.

Consequences

Easier:

  • A story's run has one outcome, an open pull request, and never reads release state. Stories are started and landed independently; a conflict between two shows when the later one merges the base in, in its own checkout.
  • A batch needs no opening: a release holds whatever has landed since the last tag. .tp-release.yml, after:, the conversion and the unprepare have no counterpart.

Harder:

  • The base branch carries merged work that is not released, so it must be releasable at every merge.
  • Which finished stories a release holds is no longer chosen, except by not merging one.
  • Until #199 maturity.code alone does not name the process, which 0006 set out to guarantee.

What still holds:

  • 0005's fragments: the CHANGELOG line per story, the version from their kinds, the issues a release closes from their names.
  • 0001's release pull request with the forge as the state, and 0003's bounded wait, for #197.
  • 0006: the base branch is protected from code level 1.