Upgrading from v1 / v4

If you have used SDLC Studio since the early, mostly human-driven days, the tool has grown a lot of discipline. The good news: nothing changes in an existing project until you say so.

New in 5.1: it stops making you wait

If you have run SDLC Studio against a real backlog, two things grated. Both are gone.

status was taking about a minute, every time. Measured on the same machine, over a backlog of 822 stories and 667 bugs:

	5.0.1	5.1
status	59.6s	0.9s
status hint	59.5s	0.8s

Fixing one bug no longer invalidates other people’s evidence. Mutation evidence used to be tied to a whole file, so editing anywhere in a file another unit had touched staled that unit’s evidence too - one line moving forced seven units’ checks to be re-run by hand before anyone could commit. Evidence is now tied to the exact spot a test covered, so an edit elsewhere in the same file leaves it alone.

The other direction, plainly: the checks that run when you commit take longer, not less. There are 536 more tests than 5.0.1 and the full suite moved from 286s to 331s. That is the trade - more is checked, so more is caught. What got fast is what you run interactively.

The rest of 5.1 is about trusting what the checks tell you: a new probe asks whether a criterion could ever fail before you build against it, Done refuses a unit whose own tests never ran a line it added, and the release gate asks the forge whether CI actually passed instead of believing a local file.

One breaking change

mutation.py register now requires --anchor - the exact text your mutant replaced. Existing calls exit 2 until you add it. Rows already in your ledger are untouched and need no backfill.

The upgrade is opt-in

Re-run the installer (or /sdlc-studio skill-update). It is a drop-in: no project migration, and existing sdlc-studio/ directories keep working exactly as they did. The v5 workflow changes - the two-backlog gates, sizing demands, terminal-status derivation - are off by default. An existing project upgrades with zero disruption and keeps its old flow until you turn enforcement on.

What is new to learn

• The two-backlog model. The single biggest shift: a request (CR/RFC) is not work until refine sizes it into delivery units. This is new if you last drove the pipeline by hand.
• Sizing is compulsory. Delivery units carry points (stories/bugs) or a T-shirt size (CRs/RFCs/epics). The planner refuses an un-sized unit.
• Two-role review. Past a configurable threshold, Done needs an independent, non-author sign-off.
• The sprint. A deliberate batch driven to a goal, reviewed at its boundary and closed with a reconcile, a review and a retro that has to produce work.

Turning enforcement on

Start with /sdlc-studio migrate. It reviews every artefact and upgrades what it safely can - conventions, version, sizing - applying the deterministic set and reporting the judgement calls with the command that fixes each. It is dry-run by default; --apply writes the safe set.

Then three deliberate steps:

1. /sdlc-studio migrate --apply - convert existing requests and containers to a T-shirt size deterministically, and report the delivery units that need re-sizing.
2. refine the accepted requests into sized delivery work.
3. Set two_backlog.enforce: true in .config.yaml.

The sizing migration only adds a Size: line and the workflow is one config line, so the upgrade is reversible.

The numbering question

New projects mint collision-free ULIDs (US-01JQK3F8) so parallel agents never fight over sequential ids. An existing project is asked the numbering question explicitly on upgrade, with three supported answers - it is never auto-flipped.

Note

The full, in-repo detail - what changed, the numbering question and its answers, and the honest breaking-change notes - lives in docs/existing-users.md in the repository.