Software maturity

A project's maturity is declared, not inferred: task-plus.yml states the level the project has reached on each ladder, and task-plus enforces the practices that level requires and reports the gaps. The ladders are the contract; the enforcement details live in task-plus and are linked from here, so this page stays true when a command changes shape.

There are two ladders rather than one, because how code reaches main and how a release reaches a running system move independently: a project can deploy every release and sense-check it while still committing straight to main, and a trunk-based project can run blue-green. Each ladder is strict — a level includes everything below it.

Code flow

How a change reaches main, and so how a release is made. The level alone picks the release process; task-plus has one process per level, not variants within a level.

Level Name Practice task-plus enforces
0 Trunk Commit on main; a release is a tag on main tp release tags and pushes on main, and refuses when the forge protects main
1 Story branches One short-lived branch per story, carrying its CHANGELOG line as a fragment (changes/<n>.<kind>.md); each story lands on main by its own pull request once its build is green; main is protected against direct pushes and always releasable; a release is a separate act on main tp story land merges main into the story branch, builds, pushes and opens the pull request; tp release on main gathers the fragments into a release/vX.Y.Z pull request, merges it and tags the merge. tp check refuses a hand-edited [Unreleased]
3 Agent flow Level 1, with the work between a defined story and its landing done by agents: an idea is captured as an issue, an interview turns it into a story, the story is built and reviewed in a worktree and merged by the agent; a human is called when the story no longer holds, and reviews main after the fact not built; the specification is agent flow

There is no level 2. It was to be level 1 with CI running the build on every pull request and the merge blocked until green; it was never built and no project declared it. CI on pull requests is a forge setting a project may add at any level, not a level of its own, so the ladder stays strict: level 3 builds on level 1.

The acts behind the table (build, land, release) are defined in the method. Level 1 keeps landing and releasing apart, after two drafts that did not. The first put the release inside each story's pull request, so parallel stories collided on the shared [Unreleased] and on the version. The second gathered stories on a release branch and took the batch to main in one pull request: fragments removed the collisions, but a story still reached main only as part of a release, and every step began by working out whether a batch was open and whose it was. Landing each story on main by itself needs no such shared state, and the fragments still give the version when a release is made.

Level 1 is in transition between the two. task-plus builds trunk flow beside the batch, chosen by maturity.flow: trunk, until every level 1 project has moved; a level 1 project without the key still runs the batch. What the batch was, how to recognise a project still on it and how to move one are on the batch page.

The release is a write to main like any other, so at level 1 it goes through a pull request like any other. No account is whitelisted for pushes, so the gate holds for everyone and every commit on main has been through the same door. Only the tag is pushed directly.

Level 1 is not about review. A solo project with an agent gains little from a second pair of eyes on every merge. What it gains is a main that is deployable at any moment, which the deployment ladder from level 2 upward depends on. Review of every merge by a person, when a project wants it, is a forge setting, not a level of its own.

Deployment

How a release reaches a running system, and what that system promises while it happens. Each level is a deployment strategy paired with the reliability metrics it commits to; the metrics are what make the level testable rather than aspirational.

Level Name Strategy Downtime per upgrade Data loss (RPO) Recovery (RTO) task-plus enforces
0 Manual Deployed by hand when someone remembers unmeasured unmeasured unmeasured nothing
1 Released Every story ships as a release that is deployed and sense-checked before the next story starts the whole run restarts; state is not kept everything since the run began a fresh run post_release deploy hook present; release not closed until the deploy reports
2 In place Stop, replace, start on the same host; schema migrations are versioned and expand/contract; rollback to the previous release is rehearsed the restart, measured and recorded per deploy (minutes) none: every committed fact survives restart time, or rollback time if the release is bad a migration version table exists; the deploy log records downtime per upgrade
3 Zero downtime Blue-green or rolling behind a load balancer; old and new versions serve together, so migrations must be compatible with both none: every request during the deploy is served none seconds (switch back) deploy log shows requests served across the switch
4 Multi-region Level 3 in more than one region; the loss of a region is survived none, including for a region outage none automatic failover —

Downtime is therefore not a separate concern bolted on to a deployment strategy: it is the metric that distinguishes the levels. A project at level 2 is allowed downtime, and says how much; moving to level 3 is the decision to stop allowing it, and that decision costs the ability to run a single process against the database.

Declaring a level

# task-plus.yml
maturity:
  code: 1
  deploy: 2

tp check reports each ladder's level and the practices still missing for the declared level, and warns when a project exceeds a level it has not declared (a project at code: 0 with branch protection on main is probably at code: 1 and should say so). Raising a level is a story in the project that adopts it, because each one changes the project's day-to-day flow; lowering one is an ADR.

Where this is implemented, and the exact checks, is task-plus's maturity page. Until that ships, the table above is the specification it is built to.

Example: gobank

Today Next Later
Code 1: stories batched through release 1: trunk flow 3: agent flow
Deploy 1: every story deployed to Hetzner and sense-checked 2: stage 2, the demo resumes from its database and each later story is an upgrade drill 3: stage 8, several processes, blue-green; 4: phase 4, CockroachDB across regions

Downtime is accepted at deployment level 2 and recorded per upgrade, so there is a number to drive to zero when level 3 arrives.