constraint-driven-development

Constraint-driven development

Contract

Inputs

Required: the set of non-negotiable constraints the change must satisfy, each stated as a measurable predicate (a budget number, a platform limit, or a legal or API rule with a checkable condition). Optional: an existing constraints record that already governs the target tree. A constraint that arrives as prose without a measurable form must be converted to one before any code is written; a constraint that cannot be checked is unmeasurable and stops the run.

Procedure

1. Read the target tree once to learn language, stack, test runner, and any existing constraints record. Do not ask for what is readable. Done when: the target tree is read and its stack and test runner are known.
2. Extract every stated constraint into a named invariant: a predicate, the command or inspection that produces its verdict, and the value it must hold. Record them in a constraints record at the repo root, one row per constraint (name, rule, checked-by, runs-at). A constraint with a number and no check command is unmeasurable, not a constraint; stop and ask the user to supply a check or drop the constraint. A constraint with no number is not non-negotiable until the user supplies the target value; do not invent one. Done when: every constraint is a named invariant with a check and a target value, recorded in the constraints record.
3. Bound the change scope before mutating: list the files the work will touch. Constraints apply to the diff, not the whole tree, unless a constraint is explicitly project-wide. Done when: the change scope is bounded and listed.
4. Capture the baseline. Run each constraint's checked-by command against the current tree and record the measured value. This baseline is the floor: the delivered change must not produce a worse value for any constraint. Done when: every constraint has a recorded baseline value.
5. Implement the change. After each edit run the fast subset of checks (types, lint, the constraints whose checked-by command is fast) scoped to the touched files. Done when: the change is implemented and the fast checks pass for each edit.
6. Validate against the baseline guard. For each constraint, run its checked-by command on the delivered change and compare the result to the baseline value from Step 4. A constraint is violated when the delivered value is worse than the baseline (a threshold exceeded, a count increased, a check that previously passed now fails). Tightening is silent; loosening is a violation. A constraint that cannot be re-measured after the change is unverified and blocks done. Done when: every constraint is re-measured and none worsened against the baseline.
7. Run the full check set: every constraint's checked-by command against the complete change, plus the project test suite. Scope expensive checks (mutation testing, security scans) to the touched files. Done when: every constraint's checked-by command runs and the test suite passes.
8. Verify the done predicate: every constraint holds in the delivered change and none worsened against the baseline. Done when: every constraint holds and the baseline guard is clean, or the failing constraint is named.