Workflow

How work is done in any Solid Plans Software project: what has to pass before a change counts as finished, which tests a change owes, how much a session decides without asking, and what is done about a problem the work finds. tools.md says what to invoke; this says when and why. Philosophy.md is the discipline these rules come from, and conventions.md is the shape the result has to have.

The verification gate

Every repository defines a verification gate — format, lint with fixes, type check, a --validate run of every generator and marker, and the two dependency validators. It is one command, dev gate: the checks it runs are the gate list in the repository’s .dev-tool/config.yml, dev-tool’s own default where a repository states none, with whatever the repository adds in gateAdditions, so the list is written in one place and nothing that runs the gate restates it. Each check states there where it runs, its placement: both, ci or local. dev gate is a session’s gate and runs the both and local checks, naming the ci ones it leaves out; dev gate --ci is CI’s and runs the both and ci checks, naming the local ones; and dev gate --all runs every one, which is what a release is held to. Every check that runs does so whatever an earlier one answered, and the command reports each check’s outcome and duration and fails if any failed — nothing is timed by hand, and nothing is reported by hand either: every command leaves a record of its run, and where impl-tool runs the session it reads each check’s and each test run’s duration and outcome from that record, so a report of the work says nothing of what a check cost or whether it passed.

The gate runs no test. dev test is the test command, run beside the gate as a step of its own: the two are scoped differently, CI runs them as separate jobs, and a failing check owes different work from a failing test. Something that wants both calls both.

The verdict a merge waits on is CI’s. Whether a push starts that run or somebody does is the forge’s setting, and a repository’s main context file says how its gate is started; either way a merge waits on a green run of the head commit. A gate is started for a new head and for nothing else: a label, a review or a check of another name does not move the head, and a head whose verdict passed is not gated again. A pull request is gated by a run nobody’s machine has to make: the checks as dev gate --validate --ci, the checks CI is owed and refusing a gate that had to repair what was pushed, and the suite whole and in every tier. For the tests, what a session runs is there to find out early, not to certify: it runs the tests its change reaches, below, does not run the full suite, and a commit does not claim one. For the checks placed local a session’s run is the only one there is.

A session runs dev gate before it commits, because CI does not catch a lint or type failure. dev-tool’s default places five checks local – lint, typecheck, and the --validate runs of schema gen, command gen and api gen – and CI’s dev gate --ci leaves them out: every session already runs them on exactly what it pushes, and on CI they cost most of the checks job to answer a second time. What that trades away: a commit that never ran the local gate – a hand edit, a session that skipped it – merges without them, and nothing runs them afterwards until the next session’s gate or a release’s dev gate --all. So the gate is run after every edit cycle and before every commit whose tree it has not seen, and a commit is not made on a gate that failed.

Which tests a change owes

After an edit, run the tests the edit reaches: test --select affected, run after the gate. It reads what changed from git, finds the modules owning it and every module depending on one of them through the dependency graph, and runs those modules’ tests and no others. That is the question this discipline used to ask the author to answer by hand, by choosing which test modules a change touched, and the graph answers it the same way every time, including for the module three edges away that the author did not think of. A repository may state --select affected as test’s default: there a plain test is this run, and the whole suite is asked for by name, --select all.

It is narrower than the suite and wider than a guess, and both halves matter. A change no module owns – a file outside every module, or one the repository has not said reaches no test – runs that repository’s whole suite, because a selection that guesses is one that passes while something is broken. A change reaching only modules with no tests runs nothing.

The full suite is CI’s. It runs on the pull request, selected by change against the pull request’s base, and whole on the default branch after each merge, which is where whatever the graph does not hold – an import nobody declared, a test reading a file no module owns – gets its say without every pull request, or every session, paying for it. A failure there blocks no merge and is the default branch’s to repair, by whoever merged. Locally the whole suite is run only when the affected run cannot be trusted to see the change: an edit to the repo adapter every repository runs its tests through, or to the graph itself.

Say which you ran. “Tests pass” after an affected run means the tests the change reaches pass; reporting it as though the suite were green is the failure this trades against.

Tiers: what runs after every edit, and what runs on CI or on request

A suite is not one kind of test, and a handful set its wall clock. A test that starts a real service, drives a real executable or builds a real artifact costs seconds where its neighbours cost milliseconds, and is what contends when several suites run on one machine at once. That is what such a test is for, and it is not what a run after every edit is for. A tier is how it says so and stops being run by default.

A test says its tier by the folder it sits in inside the test directory: __tests__/__unit__/ and __tests__/__integration__/ in Python. Where a file sits is how a selection, the lint rule that holds a test to its module and a test runner’s own configuration already read a test, so nothing per test can be forgotten and a run does not collect a tier it was not asked for.

The tiers are declared – testTiers in a repository’s .dev-tool/config.yml, dev-tool’s own list where a repository states none – so a further tier is a line of configuration, and a tier folder no declaration names is refused by name rather than silently collected by nothing. There is one structure and no second rule for a test that does not say: one kept directly in the test directory, or under a folder that spells no declared tier, is refused by dev test as TEST_NOT_IN_A_TIER, naming it. Which folders are tiers is testTiers and nothing else – no list of the folders that look like a tier and are not is kept anywhere. The lint rule TST002 refuses a test module that is in no tier’s folder. --tier narrows an affected run the same way, and does not stop a test named with --paths from running whatever its tier.

The integration tier is never owed locally – not after an edit and not before a commit. A commit is made on every change, so a tier owed before a commit is a tier run after every edit, by every session on the machine at once, which is the contention the tier was moved to CI to end. What a commit is owed is what an edit cycle ran: the gate, and the unit tier of what the change reaches. A change to a module that keeps integration tests is judged by CI’s test job, on the pull request. Run the tier locally when the question is about those tests themselves – one is being written, or CI’s failure is being reproduced – and name the paths rather than the tier where that is enough.

A unit test that starts a process is the drift tiers exist to stop, and the run is what holds the line: a tier declared isolated in testTiers – unit, in dev-tool’s own list – is handed to the adapter, which refuses a process where a test in that tier would have started one and fails the test saying what it tried to start and where it belongs instead. So __unit__ is a statement about the tests in it rather than a name on a folder. A test stands the process boundary in – the function that runs git, replaced – or it sits in __integration__; a file whose tests are of both kinds is two files of one name, one in each folder, the integration one importing what they share from the unit one.

Tests are co-located in __tests__ packages mirroring the source structure: a test sits in the module it tests, and the tests of a module nested in another sit in the nested one. That is what makes the affected run narrow, since a module’s tests are selected by the directory they are in – a test of a nested module kept with the module holding it runs on every change beneath that holder. The lint rule TST001 reads a test’s subject off its imports and refuses one kept above the module they name; a test that integrates several modules, none reaching the rest, belongs to the module holding them all.

Tests mock the subprocess boundary rather than crossing it: none invokes a forge CLI or a model for real, and one that has to run git against a repository it builds says so by sitting in the integration tier. A test that reaches the outside world measures the machine it runs on, and fails for reasons that have nothing to do with the change it is meant to be judging. The same holds for the filesystem: a test builds the tree it asserts about under its own temporary root rather than pointing at directories of the checkout it happens to run in, or it passes in one clone and fails in another for want of a directory it was never testing.

Autonomy

A session runs at a declared autonomy level, a whole number from 1 to 5 saying how much it decides for itself and what it takes back to the owner. The level is stated in one place: the autonomy key of the checkout’s .impl-tool/config.yml, and every session works at it, whether the runner launched it or not. The default is 1: a session asks until the repository’s owner has said how much it may decide, and raising the level is a decision the owner makes in that key. The file is git-ignored, so the level is each checkout’s own, and changing it is an edit to that file and nothing else – no commit, and no document restating the number. No context file states a level.

A runner session is told its level in its prompt: issue run --autonomy, where it is given, and otherwise the key. A worktree the runner creates for an issue is given a copy of the launching checkout’s file as it is made, so it starts at the level stated there at that moment, and is changed afterwards in its own copy.

A session nobody launched – a person’s own agent session in a checkout, for instance – reads the key itself before it decides anything: autonomy in .impl-tool/config.yml at the root of the checkout it works in, or, in a linked worktree with no such file, in the main working tree’s. A config.local.yml beside it, where one exists, states the checkout’s own settings and wins over the file for any key it states. A user’s ~/.impl-tool/config.yml may state a level too, and the runner honours it, but a session started by hand does not read it: a level meant for every kind of session goes in the checkout’s file. Where no file states the key the level is 1. Where the file is there and will not parse, the level is 1 as well, and the session says so in its first answer, naming the file, so the owner can repair it rather than wonder why the session asks so much.

Stopping to ask the owner and deferring work to a follow-up are the same act: a decision handed back instead of made. One number therefore governs both, and the higher the level, the more a session fixes in place and the fewer follow-ups it raises.

At 4 a question is the exception. Which of two reasonable implementations to take, whether a defect found on the way belongs in this issue, whether to make the fix in the neighbouring repository the change reaches: each is reversible, so each is decided, and the description says what was decided and why. That is what lets the owner overrule it afterwards at the cost of reading a paragraph, where a question costs a stopped session. What is still asked is a choice the rest of the codebase would then be expected to follow — a new convention, a new kind of dependency, a boundary moved — because a precedent is not undone by reverting one commit. A follow-up at this level is for work outside the issue’s reach, and is never a way of asking the owner something the session could decide; “Fix what the work finds”, below, is the same rule from the other side.

Asking means stopping and putting the question to the owner before acting on it. Where nobody is there to answer — a headless run — it means leaving that one act undone, carrying on with whatever does not depend on it, and recording the question where the owner will rule on it.

No level makes these acts alone. At every level, 5 included, a session asks before:

They are stated apart from the scale so that no level can be read as permission for one. A procedure that includes such an act — a retirement deleting merged branches, a release — is still the owner’s to start, and a go-ahead given for one occasion does not stand for the next.

Fix what the work finds

A problem found while working an issue is fixed in that issue. A defect beside the code being changed, a test that should have existed, a document the change made stale, a check that turns out to pass for the wrong reason: each is within reach of the change, and each is fixed on the branch — in the edit that found it, or in a later increment of the same issue. It is not written down as a follow-up and it does not become a queue note. Whether it matches the issue’s title is not the test; whether it can be done here is.

Deferring is the expensive choice and only looks like the careful one. A follow-up is an item the owner has to rule on before the issue can retire, and an accepted one is a queue note that has to be planned, placed, prioritised and launched as an issue of its own — a worktree, a branch in every repository it touches, a gate and a review, for a fix that was one increment while the code was open. A session whose first inclination is to segment work off is one whose issues each leave several more behind them.

A follow-up or a new queue note is the exception, for work that cannot belong to the issue being worked:

Each one says why the work cannot be done now, in the item itself: a follow-up’s rationale, a queue note’s own text. “Out of scope”, “unrelated” and “small” are not reasons — they describe the item, and the question is what stops it being fixed. An item that cannot name what stops it is one to fix.

The same order holds wherever a deferred item is ruled on. At a follow-up review and at a retirement, fixing the item on the branch is the first option offered to the owner, and accepting it into the queue is the alternative for what the branch cannot carry.

The record keeps pace with the work

Architecture decisions land as queue notes, finished items are retired, and documentation changes ride in the same change as the design they describe. A decision that lives only in a commit body is one the next reader has to reconstruct.