v1.20.0 ·
The gates never checked that two files agree
Every gate in AIDLC asks about existence. Does the requirements file exist and is it marked complete. Does a review file hold at least one real finding. Does every acceptance criterion have a test that names it. Is the person advancing the phase the one who claimed it. They are good checks. But each one describes a single moment, and none asks whether two documents still agree.
Here is what happened, repeatedly, and what nothing caught. A requirements phase closes on a Tuesday. On Thursday a customer needs JSON as well as CSV, or a review shows a criterion cannot be built as written. Somebody edits the requirements file. The phase file still says complete. The design still describes the old criterion. The tests still cite it by its old number, so the traceability gate finds coverage for something that no longer says what it did. aidlc gate exits zero. The suite is green. Ship it.
The information is not missing. The change is right there in the file. What is missing is anything that notices the change invalidated something downstream. There was a hint this had been thought about and narrowed to nothing: the instance state carries a scope history with before, after, reason, time and author. That is change control, applied to one field. Requirements changes got none. The transitions log also had no word for going back. It knew a normal advance, a deliberate skip and a scope upgrade, all forward. A reopened phase would read as an ordinary step.
What changed
A change to a criterion is now written as an ## Amendment <n> section with Retires:, Issues:, Reopens: and Reason: bullets. I measured the format off what the repo already had before fixing it: five hand-written numbered amendments in one instance and four unnumbered sections in three others. The numbered form parses. The rest get a warning, because a near-miss that reads as absence is a defect this project has paid for five times.
aidlc amend <instance> sets the phase named in Reopens:, and every phase between it and the current one, back to in-progress, then appends a reopen record naming the amendment, the criteria and the phases rewritten. Churn now shows in the history. Cost and lead time follow the reopened phase with no change to how they work.
aidlc amend <instance> --impact is read-only. It lists every task, test and artifact that still cites a retired criterion. It does not pick which phases to reopen. My first design derived that from the walk, and it was degenerate: the requirements file always cites every retired criterion, so every amendment would have reopened requirements. A destructive state write should not hang on a prose-scanning guess. The author states Reopens: and the walk offers a line to paste.
Why this way
The roadmap item asking for this had been parked as the largest piece of machinery on the board, weeks of work. That estimate was written before three other things shipped: retirable criterion IDs, tasks that link to the criteria they satisfy, and cost windows that know which phase was open. Most of it was already in the code. Walking backwards already worked, because the resolver returns the first unfinished phase.
I rejected amendments as prose plus a manual reopen, since nothing can check prose and this project has already seen a written-down fix rediscovered from scratch. I also rejected a new consistency gate. Every gate is a tax on every future instance, and it would fail instances that keep a historical reference on purpose. Reopening works by setting a phase to in-progress, which re-arms the artifact gate that already exists. A test pins the gates at eleven.
What it leaves out
The original idea also stored a digest of each artifact when its phase completed, so an unamended edit could be caught. That is not here. Phases reach complete three ways: the normal transition, a second writer for the final phase, and by hand, which the phase skills tell agents to do. A digest written on one route detects nothing on the other two. And a missing digest has to read as allowed for the forty-five instances that predate it, so the check would look clean because it never ran. It is a separate roadmap item, waiting for those writers to become one.
The amendment rule is now stated in the requirements, design, implementation and testing skills, so an agent reads it when it would otherwise edit a finished artifact.