Keeping specifications in the change review

An accepted change does not remain accepted because its discussion is somewhere in an agent transcript. Code moves, dependencies are updated, a deployment enters a transition period and another agent resumes work with only part of the earlier context. A user can also discover a problem without changing the repository at all.

The change review must keep the active obligations, their applicability and the evidence for its decision connected as the system changes. An ordinary defect can leave the contract intact.

Begin with the ordinary repair

When an existing requirement is settled and the implementation violates it, start with the smallest repair that restores the requirement. Reproduce or investigate the behaviour, trace the responsible boundary, change the cause, exercise the relevant success and failure paths and review the result. The repair does not need a new specification merely because an agent is doing it.

The distinction matters for the download rule from Part 5. EXP-05 requires current account authorisation for each new download request, including a direct storage URL if the design uses one. If a revoked administrator can start a new download through an existing link, that is a conformance failure. The first route is to repair the authorisation boundary and check the denied request at that boundary. It is not to weaken EXP-05 until the existing link passes.

The route changes when the evidence challenges the requirement rather than the implementation. Part 5 assumes authorisation at request start, so an already-authorised transfer may finish. If the product now wants revocation to interrupt that transfer, it is proposing a stronger rule with new design and feasibility consequences, not completing the ordinary repair. Preserve the counterexample, identify the owner of the decision and use the correction process from Part 4.

Scroll horizontally to see all columns.

This classification keeps a local repair local. It also prevents the opposite mistake: treating a product decision as a test failure that can be fixed by editing an assertion.

Keep one compact change record

The record belongs in the existing pull request, task or change discussion. A new ledger creates another place that can drift from the contract and the code. The record only needs enough information for a later reviewer to reconstruct the decision:

• the applicable requirement IDs and contract version;
• whether the decision concerns the next target version, a deployed version or a transition between them;
• the code revision or recorded workspace state, relevant configuration and affected consumers;
• the checks that were planned and the checks that actually ran;
• the result, limitations and any obligations left unverified;
• the person responsible for acceptance, the decision and the next action.

“Run the download test” is a plan. “The revoked-download scenario ran against revision r7 with the staging authorisation policy and returned no data” is a report of an observation. If the scenario was not run, record that fact. A passing command recorded against a different revision is evidence about that earlier state, not the current change.

The invoice investigation remains illustrative. The contact and download fixtures in Part 7 were actually executed during this series revision. The existing revision task recorded the following results on 21 September 2026; these are checks of synthetic contracts, not evidence that their policies serve a real product.

Applicable contracts: contact v1 (DEDUP-01–DEDUP-05), especially DEDUP-02, first-record retention; and the authorisation fixture’s EXP-05, current authorisation for each new download request.

Examined boundaries: the contact operation and the API and direct download entry points in the fixture suite.

Command: python3 -B -m unittest discover -s fixtures -p 'test_*.py'.

Evidence: retaining the last duplicate caused a failure. Restoring first-record retention passed all four fixture tests: two contact tests and two download tests. The format-1 recorder reported complete, matching before, after and comparison-time fingerprints over its recorded scope, which omitted directory state. Command success was reported separately.

Decision and next action: the revision’s implementation reviewer retained the contact repair under contact v1; EXP-05 also remained unchanged. Any subsequent change to a rule or affected inputs requires a new assessment.

Limit: these in-process fixtures exercise neither a deployed contact importer nor a real storage or authorisation service. Runtime details and the recorder’s bounds are beside the implementation.

Scroll horizontally to see all columns.

The last edit made the whole-workspace fingerprint outdated. That comparison alone does not establish a requirement violation. The failing direct-download check demonstrated the fixture’s EXP-05 violation; it did not show a new DEDUP-02 failure.

The updated recorder writes recorder format 2 and rejects format-1 records for comparison; a fresh run is required. Recorder formats are separate from the contact contract versions below. The recorded outcomes and fingerprints remain historical observations.

The task also exercised a deliberate contact-v2 requirement change: use Unicode case-folded identity instead of exact case-sensitive identity. The changed expectation failed against the contact-v1 implementation (704286ed72f3). Applying identifier = identifier.casefold() before comparison, while retaining the original record fields, passed the revised checks (b0c6c915d9a3). This was a stipulated alternative for the exercise, not a discovery that v1 was defective. The published quickstart retains contact v1; the task history records the contact-v2 experiment separately.

That distinction determines the handoff. The ordinary repair preserves DEDUP-02; the v2 experiment changes DEDUP-01 and requires its callers and expected results to be reconsidered. A later agent needs to know which branch and rule it has been assigned before either passing result is useful.

State which version the rule governs

The contract being corrected for the next release and the obligations already owed by a deployed release can differ. A repair may need to preserve both while a migration is in flight. Name the distinction instead of using “the current spec” for all three.

The target contract describes the behaviour the change is intended to establish. The deployed contract describes what existing users and consumers can rely on until the transition is complete. A review should say which one it is accepting. If the target changes EXP-05 to require authorisation during an active transfer, the review must identify the deployed versions that still permit completion and the transition behaviour that governs work already started.

This applies to shared interfaces as well. A helper change can affect a requirement that was not edited. Suppose a contact-import entry point governed by the deduplication contract begins lowercasing IDs before it calls the pure deduplication function. The function may still conform in isolation, while the entry point now violates the contract’s exact case-sensitive identity (DEDUP-01) and can change which first record survives (DEDUP-02). Review the entry point and both consumer paths against the unchanged obligations. Do not copy those requirements into the helper’s task as a second authority.

The same reasoning catches an alternate path that ordinary happy-path tests miss. A check through the main import command can pass while a batch endpoint still calls the old normaliser. The record should name the paths examined and identify the path that remains unverified. “The shared helper passed” is not a substitute for checking the consumers that can bypass it.

Treat evidence as attached to a state

Evidence has a subject. For implementation conformance, that subject includes the requirement version, code state, configuration, fixtures and command that produced it. A later merge, fixture update or permission-policy change can invalidate a result even when the original command still passes.

Do not rerun every check after every edit by ritual. Inspect what changed and rerun the checks whose obligations or inputs it could affect. A change to the export query may require the snapshot and download checks; a documentation edit may require neither. A merge that changes a shared authorisation helper requires more than the test file that happened to be edited.

When an agent resumes, give it the active contract version, the applicable scope, unresolved findings and the evidence state. A transcript can help retrieve context, but it is not the authority. The resumed agent must not treat an old plan as permission to decide a question that was left open or to report an earlier result as current.

Non-code feedback enters the same record. If finance cannot identify an invoice in a file because two records share its visible values, the repository may have no diff. The observation still challenges the export’s suitability. Record who observed it, the sample or workflow used, the expected outcome and what decision is pending. Part 5’s reconciliation branch shows why satisfying every stated column rule can still fail the task that justified the export.

Keep ownership and history separate

One maintained contract should own each active obligation. A task can propose a change, a feature file can own an agreed scenario and test code can own setup, selectors and adapters. None of those should silently become a second source for the rule. The change record links them and preserves the evidence.

When a requirement is superseded, remove it from the active contract and preserve its former wording, decision basis, affected work and evidence in history. Do not leave a cancelled obligation in the current rule set with a status that agents must interpret alongside active obligations. The new rule, if any, becomes the one maintained home. A historical record explains why the replacement happened; it does not compete with it.

This also makes handoffs bounded. A later reviewer needs the active contract, the relevant history link, the code state and the open next action. They do not need a new parallel register of every conversation. If the existing pull request or task cannot carry that information, improve that record or create the smallest task record that can; the goal is recoverable responsibility, not a new bureaucracy.

Use the skills as routes, not gates

The six skills described in Part 7 divide useful work: orchestration, writing, clarification, specification review, behavioural examples and conformance review. They are not six approvals that every maintenance change must collect.

An ordinary EXP-05 repair may need an existing contract, a focused investigation and a conformance review. A DEDUP shared-component change may need affected-consumer analysis and checks at both entry points. A user report may first require clarification or validation. If the existing contract is sufficient, say so and proceed. If it is not, route the finding to the owner who can change it.