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.