Part two
This is where a work order becomes a commit — and where most of the machine checks live. Four steps: build, hand off, ask for review, get a verdict.
Tests, linting, security scanning, dependency audit, secret scan, and an independent AI review of the change — all before anything is called done.
Writes up what changed, what was proved and how, what was skipped. Then tells the Principal one short line.
Nothing reviews itself. A finished report waits until the Principal asks.
An Architect session re-runs the checks rather than trusting the report, proves the security rule still holds by deliberately breaking it in a copy, and checks something nobody was asked to check. Only the strongest models available run this step, and never the session that built the item — a verdict's job is to disprove the builder, the last check before work is accepted, and it can't do that from inside the session it's grading.
Most builds run all four steps smoothly: build, hand off, ask for review, get a verdict of conforms, done. But the path isn't required to be that clean, and the rule for what happens when it isn't is the same rule that governs everything else here — a Developer never resolves something outside their own spec.
If a Developer hits a real issue mid-build — the spec is ambiguous, the fix needs a file they don't own, something looks wrong that nobody asked them to check — they don't decide it themselves. They document exactly what they found and why they stopped, close out their own report as usual, and hand off. That question now belongs to the Architect, not the Developer: it gets answered at review, where the Architect either resolves it directly, or writes the follow-up work as its own item. Either way the verdict says so explicitly — conforms-with-deviations, or kicked-back with exactly what's owed — never a silent "looked fine to me."
That's the same escalation rule from Define's "every seat's rulebook" — guessing is not part of any seat's job — applied at the one point in the loop where a session is most tempted to just fix the thing in front of it and keep moving.
They look redundant and aren't. The work order says what was asked for. The report says what was actually done and how it was proved. The verdict says what an independent reviewer made of it. Losing any one of them loses a distinct thing.
What the Principal actually types
These remove clerical load, never judgment. They don't decide what to build, what's safe to ship, or whether something works.
| Command | What it does | Leaves behind |
|---|---|---|
/projectplan | State of everything, plus which items can safely run at the same time | — |
/nextdev | Briefs a Developer item — summary on screen, full detail to a file | a dispatch note |
/nexttw | The same, for the Tech Writer | a dispatch note |
/build | A fresh session picks the item up and takes the role the note names | a commit |
/review | The strongest available model reviews a finished build — never the session that built it | a verdict |
/accept | Records what was tested and what happened | an acceptance record |
/checkpoint | Makes state durable so a session can be closed safely | committed files |
In action
A real piece of work from this week: T20, closing a gap in the settings leak-guard's own test coverage. The guard's formatter had just been unit-tested thoroughly (a separate item, T3), but nothing yet proved the guard's pytest.fail actually fires when settings genuinely drift. Here is every keystroke.
Principal — Architect session
/projectplan
Shows everything open, who holds what, and which items can safely run at the same time.
Principal — Architect session
/nextdev T20
The Architect writes the full briefing to a file, then reports back:
T20 — the leak guard's trigger is untested. Developer, 0.75h.
Building: tests proving the guard's pytest.fail genuinely fires on real settings drift, extending the existing formatter tests.
Touches: tests/test_settings_leak_guard.py only — extend it, don't rewrite it. tests/conftest.py is read-only.
Must not break: the eleven existing formatter tests keep passing.
Not doing: the guard's own registration — whether pytest wires the fixture in at all — isn't in scope here.
Run: /build T20 in a fresh session.
This is the approval moment. Five lines, and the two that matter are must not break and not doing — where a wrong instruction is visible before any code exists.
Principal — new session
/build T20
Six characters. The session reads the briefing from disk, takes the Developer role because the briefing says so, and confirms scope in three lines before touching anything.
Then it builds: three new tests, each proved by mutation against a scratch copy — the exact disarm that motivated the spec (pytest.fail silently mutated to pass) makes one specific test fail, and several more independent mutants each land on exactly one test. All fourteen tests pass on the real file. It writes up what it did and says: "T20 done, `772aa45`."
Principal — Architect session
/review T20
The Architect reads the write-up, then ignores it and checks for itself — re-runs all fourteen tests, reproduces the mutants in a scratch copy, and looks at one thing nobody was asked to look at. That last habit is where the best findings come from.
Verdict: conforms. And the habit paid off here — the thing nobody was asked to check turned out to be real: the guard's own registration (whether pytest actually wires the fixture in for every test) was untested by either this build or the one before it. Raised as a new item, T25, rather than fixed on the spot — deciding scope is Architect work, and a review isn't the place to expand one.
The Principal typed four commands and one ID. Nothing was copied between windows, nothing was decided without him, and every step left a committed file behind — so if any session had died mid-way, the next one could pick up exactly where it stopped.
This particular item's story stops at the verdict: T20 is a test-only change with no page or button a person can click, so it was never separately exercised in the test environment and never entered the business-acceptance log. Not every item needs to — see Not Done for the one that has gone all the way through business testing.
Does it actually work
Eleven independent checks stand between a session's first keystroke and anything reaching a server. Listing what each one catches and stopping there would be a brochure. The column that matters is the one on the right.
| Safeguard | Catches | Does not catch |
|---|---|---|
| Architect review | Conformance to spec, proven by mutation | Whether the spec was right |
| Qcoder LLM review | Defects in .py | Templates, workflows, shell, config — no review at all |
pytest -q on every push | 919 tests | Nothing end-to-end |
ruff check . | Lint and style | — |
bandit -c pyproject.toml | Insecure Python patterns | Excludes tests/ |
pip-audit | Vulnerable dependencies | — |
scan_secrets.py + pre-commit hook | Committed secrets | Values that aren't quoted string literals |
Both deploy jobs needs: all five gates | Anything deploying un-green | — |
promote.sh green check | Non-green shas — and refuses on "no checks at all" and "still running", with three distinct messages | — |
environment: production reviewer | An unreviewed production release | It is one person approving their own release |
| Prod fast-forwards to the SIT tip only | New code entering prod without passing SIT | — |
Each safeguard's scope is listed here for reference, next to what it catches: together, static analysis, dependency and secret scanning, spec conformance, and the CI-to-deploy path cover the full pipeline from commit to release.
Two of these are worth calling out as genuinely good, without hedging. The green check doesn't just look for a failure — it treats "no checks have run at all" as a refusal too, which is exactly the case a naive "nothing failed" test gets wrong. And both deploy jobs require all five CI gates before they'll run — SIT is protected by exactly the same bar as production, not a lighter one.
The last three rows — the green check, the human reviewer, and the SIT-tip rule — are the promotion path's own safeguards. Deploy covers the full path a commit takes from SIT into production; this table is the full reference for all eleven.
Test coverage and acceptance
919 tests, eleven independent safeguards, five required CI jobs, review-by-mutation, and a promotion path that fails closed in three directions.
Test authorship follows the same rule as the rest of the build: whoever builds a spec writes the tests that pin it, and the Architect verifies both by mutation — breaking the code and confirming the test catches the break — rather than reading the test and taking it on faith. Business-level acceptance happens separately: a person actually uses what shipped, and that's recorded per release (see Deploy for the count).