constraint-driven-development

# Constraint-Driven Development

## Overview

This skill produces a written record of **this project's** bar, with numbers, that outlives the conversation and can be checked mechanically.

The reason matters. When you wrote the code, reading it told you whether it was any good. An agent writes more in an afternoon than you will read that week, so the judgement moves out of your head and into checks that run around the loop. Those checks need to exist, they need numbers you actually chose, and they need to fire close enough to the work that the agent fixes its own output.

Spec-driven development says what to build. Test-driven development proves it works. Constraint-driven development defines what "good enough to ship" means, before anyone argues about it in a pull request.

## Loading Constraints

The interview needs a live user. **Don't run it in non-interactive contexts** (CI, autonomous runs). If constraints are missing and you're in one of those, apply the Floor below, note that you did, and flag the rest for a human. In such a context the floor is applied only as a change the workspace's `proceed` setting lets you make without waiting; otherwise propose it, as AGENTS.md says.

## The Process

### Step 1: Detect before you ask

Never ask what you can read. Before the first question, gather:

| What | Where to look |

|------|---------------|

| Language and stack | `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml` |

| Test runner | dev dependencies, `test` script, existing test files |

| Existing linters | `eslint.config.*`, `biome.json`, `.ruff.toml` |

| CI | `.github/workflows/`, `.gitlab-ci.yml` |

Report what you found in two lines, then ask only what's left.

### Step 2: Four questions, each with a default

```

Q1: Beyond the floor, which of these do you want enforced?

(a) Test coverage on new code

(b) Security scanning

(c) Performance budgets

(d) Accessibility

(e) Architecture boundaries

GUESS: (a) and (b) — you have a test runner already and you're handling user input.

DEFAULT if unsure: (a) and (b).

Say what each pick costs: (c) and (d) need a running URL, (e) needs a rules file written.

```

```

Q2: When a check fails while the agent is mid-task, should it block or warn?

GUESS: Block. You're running agents unattended and a warning nobody reads is a warning.

DEFAULT if unsure: Block on the floor, warn on everything else for the first two weeks.

```

```

Q3: Do you have target numbers in mind, or should I measure where you are today and hold that line?

GUESS: Measure. Most teams don't have a number, and an invented one gets ignored.

DEFAULT if unsure: Measure and hold. See "Ratchets" below.

```

```

Q4: What's the slowest check you'll tolerate before the agent hands work back?

GUESS: About 90 seconds. Longer and you'll stop running it.

DEFAULT if unsure: 90 seconds at task end, unlimited in CI.

```

Stop at four. A twelve-question intake produces a config nobody understands and a user who regrets starting.

```markdown

## Constraints

Last reviewed: 2026-08-08 by @addy

### Floor (always enforced, no setup required)

- No new suppression comments: `@ts-ignore`, `eslint-disable`, `# noqa`, `# type: ignore`

- No unimplemented stubs: `throw new Error("Not implemented")`, empty `catch {}`

- No skipped or deleted tests; the floor guard flags each one, and only the owner lets one through

- No secrets in source

- This section does not get weakened to make a change pass

### Enforced with numbers

| Dimension | Rule | Checked by | Runs at |

|-----------|------|-----------|---------|

| Types | Zero type errors | `tsc --noEmit` | every edit |

| Lint | Zero errors from our config | `biome check` | every edit |

| Secrets | No secrets in source | `gitleaks detect --redact` | every edit |

| Coverage | Changed lines ≥ 80% covered | `vitest run --coverage` + git diff | task end, CI |

| Security: code | No high findings | `semgrep scan --config p/default` | CI |

| Security: deps | Nothing at high or above | `osv-scanner scan source -r .` | CI |

| Accessibility | Zero critical or serious | `axe $PREVIEW_URL --tags wcag2a,wcag2aa,wcag21aa` | preview deploy |

| Performance | LCP ≤ 2500ms, CLS ≤ 0.1 | `lighthouse $PREVIEW_URL --output=json` | preview deploy |

Every row names the command that produces the verdict. A dimension with a

number and no command in this column is an aspiration, not a constraint.

### Measured, not yet enforced

| Metric | Today | Direction |

|--------|-------|-----------|

| Project coverage | 62.4% | must not fall |

| Bundle size (main) | 184 kB | must not grow |

### Exceptions

| ID | Rule | Path | Reason | Owner | Expires |

|----|------|------|--------|-------|---------|

| W1 | `no-explicit-any` | `src/legacy/**` | Rewrite tracked in ENG-441 | @addy | 2026-11-01 |

```

### Step 4: Wire it to the lifecycle

The single biggest mistake is running everything everywhere. A check that stalls the agent gets switched off, and a gate people switched off is worse than no gate, because the bar still looks like it exists.

| Step | When | What runs | Budget |

|-------|---------|-----------|--------|

| build | after each edit | Types, lint, secrets, the floor | under 5s, changed file only |

| verify | at task end | Related tests, coverage on changed lines | under 90s |

| review | at the review step | Everything, plus the guards below | minutes |

| CI | before a merge | Direction checks, no regressions | CI |

Two rules that keep this tolerable:

1. **Scope to the diff.** Check the lines this change touched, not the whole repo. Coverage of changed lines is a number the agent can move; project coverage is one it inherited.

2. **Cost decides placement.** Anything over a few seconds moves out of the edit loop. Mutation testing on a whole repo takes hours; on the files a change touched it takes under a minute, which is the difference between a check people run and one they don't.

### Step 5: Guard the bar itself

Someone will point out that if the agent writes the code and the checks, the checks prove nothing. Half right, and worth engineering around.

Agents don't craft clever loopholes. They hit a red check and take the cheapest road to green. Watch for these five moves in the diff, at review time:

1. **The threshold moved.** A budget lowered, a severity dropped, a check removed from the fast stage. Compare the bar in the decision home against its state at the branch point.

2. **A test got easier.** `.skip` added, a test file deleted, assertions pulled out of tests that stayed.

3. **A checker got silenced.** New `@ts-ignore` or `eslint-disable`. Four suppressions deserve special attention because they switch off a check you're relying on: `istanbul ignore` drops code from coverage instead of testing it, `Stryker disable` hides a surviving mutant, `nosemgrep` and `gitleaks:allow` do it for security findings.

4. **Work is unfinished.** A stub that throws, an empty `catch` turning a failure into silence, a `TODO` standing where the implementation should be.

5. **An exception appeared.** A new row in the Exceptions table nobody discussed.

None of this needs tooling beyond `git diff`. Tightening the bar should be silent; loosening it should be loud.

Unlike the numbered dimensions, the floor has no de facto tool of its own, so an agent asked to enforce it tends to write a checker from scratch, and two agents write two different ones. A reference implementation of these five checks ships with this skill in [references/floor-guard.md](references/floor-guard.md) (diff-scoped, exit `0`/`1`/`2`, patterns adaptable per ecosystem). Adapt that rather than reinventing it, for the same reason every dimension names a de facto tool: so the mechanism is the same across runs and stacks. Run the floor guard as one of the repository's own checks, recorded as a check, with `--bar` naming the file that holds the bar where the decision home is the repository's own, at the build and review steps; it never runs as a harness hook. In CI, where the repository has one, the job calls the guard directly on each change before it merges, not as a recorded check, whose facts a CI run does not keep: it checks out the whole history of the change and of the branch it merges into, and passes `--base` naming that branch as CI fetched it, such as `origin/main`, and `--bar` as above; a shallow checkout holds no merge base, so the guard bails with exit `2`, which fails the job as exit `1` does.

**Not all checks are equally circular.** Rank them by one question: can the agent make this pass by writing code that doesn't work?

- **External** — axe-core encodes WCAG, `osv-scanner` reads a vulnerability database, Lighthouse measures a real browser. The agent can't argue with these.

- **Project** — your lint rules, your layer boundaries. A human owns the file.

- **Suite** — your own tests. Most useful, and the only genuinely circular one.

A bar made entirely of the third kind is worth less than one with an outside opinion in it. Check that at least one external constraint is present.

### Step 6: Ratchets, when you don't have a number

Set 80% coverage on a codebase at 62% and you get a red build forever, then a team that learns to ignore red builds.

The alternative asks for no decision: record where you are, then refuse to get worse. Put it in the "Measured, not yet enforced" table with today's number and a direction. Every check compares against the recorded value, not an aspiration. When a number improves, update it; when it drops, that's the finding.

This also answers a fair objection to training. Models are rewarded for passing tests, which you can evaluate in seconds. Architectural rot shows up over months and never reaches the weights. A ratchet is the missing penalty, written down where the build can see it.

## Escalation Path

Constraints work at three levels of teeth. Start at the first.

1. **Written only.** The bar is written in the decision home, and agents read it. Costs nothing, catches the honest mistakes, relies on the agent complying.

2. **Scripted.** An `npm run check` (or `make check`) that runs the fast checks, recorded as a check and in your CI. Deterministic, no new dependency.

3. **Tool-backed.** A dedicated runner that handles diff scoping, budgets, ratchets, and the guard checks. Use when the config outgrows a shell script. The floor-guard reference in [references/floor-guard.md](references/floor-guard.md) is the starting point for the guard-checks half of this.

Most projects should stop at 2. Move to 3 when you're maintaining more than about thirty lines of check-running shell.

**A first run can be floor-only.** The floor guard is diff-only and needs no installs, so you can enforce the floor on day one and add numbered dimensions as you install each tool, rather than standing up every checker before the first commit is protected. Security tools that install machine-wide (gitleaks, osv-scanner) can also run CI-only if you'd rather keep laptops clean; declare where each dimension runs in the `Runs at` column.

# Floor guard: reference implementation

This is the reference. Adapt the patterns to your stack; keep the contract identical.

## Contract

- **Input:** the diff between the merge base and the working tree (added *and* removed lines, plus untracked files). A guard that reads only `git diff` misses new files and staged-but-uncommitted work.

- **Detects the five Step 5 moves:** a weakened threshold in the bar, a test made easier (`.skip`, a deleted test file, an assertion removed from a test that stayed), a silenced checker (a new suppression comment), unfinished work (a stub or empty `catch`), a new Exceptions row.

- **Exit codes:** `0` clean, `1` at least one floor violation (block the change), `2` the guard could not run (no merge base, not a git repo). Never let a `2` read as a `0`.

- **Reports the rule and the location, never the matched secret value.** Redaction is not optional.

- **Tightening is silent, loosening is loud:** only surfaces moves that lower the bar.

## Reference (Node, ~stack-agnostic patterns)

```js

#!/usr/bin/env node

// floor-guard.mjs: diff-scoped enforcement of the bar's floor, in the decision home.

// Usage: node floor-guard.mjs [--base <ref>] [--bar <path>]

// (defaults: origin/main, and the decisions book .greenline/DECISIONS.md)

import { execFileSync } from 'node:child_process';

import { readFileSync } from 'node:fs';

import { relative } from 'node:path';

import { fileURLToPath } from 'node:url';

const base = (() => {

const i = process.argv.indexOf('--base');

return i > -1 ? process.argv[i + 1] : 'origin/main';

})();

const bar = (() => {

const i = process.argv.indexOf('--bar');

return i > -1 ? process.argv[i + 1] : '.greenline/DECISIONS.md';

})();

// `git diff --no-index` exits 1 whenever the two sides differ, which is the normal case for a

// new file, so that output is kept. Any other failure is null, and null never reads as clean.

const git = (args, { diffExit = false } = {}) => {

try { return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }); }

catch (e) { return diffExit && e.status === 1 && typeof e.stdout === 'string' ? e.stdout : null; }

};

const bail = (msg) => { console.error('floor-guard: ' + msg); process.exit(2); };

// Run from the top of the work tree. `git ls-files` lists only the current directory's subtree,

// relative to it, so a guard started in a subfolder would miss untracked files elsewhere and name

// the rest differently from `git diff`, which always covers the whole tree.

const top = git(['rev-parse', '--show-toplevel'])?.trim();

if (!top) bail('not inside a git work tree');

process.chdir(top);

// The guard's own file as the diff names it, which it never scans for the patterns it holds.

const self = relative(top, fileURLToPath(import.meta.url)).replace(/\\/g, '/');

// Merge base; bail to exit 2 rather than pretending a shallow/rootless clone is clean. In CI, check

// out the whole history first, since a shallow clone's commits have no parents, and fail the job

// on exit 2 as on exit 1.

const mergeBase = git(['merge-base', base, 'HEAD'])?.trim();

if (!mergeBase) bail('no merge base against ' + base);

// Unified diff plus untracked files (git diff alone cannot see new files).

const tracked = git(['diff', '--unified=0', mergeBase, '--']);

if (tracked === null) bail('could not diff against ' + mergeBase);

const untrackedFiles = git(['ls-files', '--others', '--exclude-standard']);

if (untrackedFiles === null) bail('could not list untracked files');

const untracked = untrackedFiles.split('\n').filter(Boolean).map((f) => {

const d = git(['diff', '--no-index', '--unified=0', '/dev/null', f], { diffExit: true });

if (d === null) bail('could not diff untracked file ' + f);

return d;

}).join('\n');

const diff = tracked + '\n' + untracked;

// Walk the diff. `---` and `+++` are file headers only between a file's `diff` line and its first

// `@@` hunk; inside a hunk every line is content, so an added `++i` (shown as `+++i`) or a removed

// `-- comment` is a change, not a header. Both headers name the file, so a deletion

// (`+++ /dev/null`) keeps its name.

const added = [], removed = [], deleted = [];

const pathOf = (s) => s.replace(/^[ab]\//, '');

let file = '', oldFile = '', inHeader = false, oldLine = 0, newLine = 0;

for (const line of diff.split('\n')) {

if (line.startsWith('diff ')) inHeader = true;

else if (line.startsWith('@@')) {

inHeader = false;

const m = /^@@ -(\d+)(?:,\d+)? \+(\d+)/.exec(line);

oldLine = m ? Number(m[1]) : 0;

newLine = m ? Number(m[2]) : 0;

}

else if (inHeader) {

if (line.startsWith('--- ')) oldFile = pathOf(line.slice(4));

else if (line.startsWith('+++ ')) {

const newFile = pathOf(line.slice(4));

file = newFile === '/dev/null' ? oldFile : newFile;

if (newFile === '/dev/null') deleted.push(file);

}

}

else if (line.startsWith('+')) added.push({ file, text: line.slice(1), line: newLine++ });

else if (line.startsWith('-')) removed.push({ file, text: line.slice(1), line: oldLine++ });

}

const findings = [];

const flag = (rule, f, text) => findings.push({ rule, file: f, text: text.trim().slice(0, 120) });

const isTest = (f) => /\.(test|spec)\.|_test\.|test_/.test(f);

// The bar is the `## Constraints` section of that file: a line counts only inside the section, in the old

// text for a removed line and in the new text for an added one, so an edit elsewhere in the decision

// home is no move on the bar.

const sectionOf = (text) => {

if (text === null) return null;

const lines = text.split('\n');

const start = lines.findIndex((l) => /^## Constraints\s*$/.test(l));

if (start < 0) return null;

const end = lines.findIndex((l, i) => i > start && /^## /.test(l));

return [start + 2, end < 0 ? lines.length : end];

};

const readBar = () => { try { return readFileSync(bar, 'utf8'); } catch { return null; } };

const oldBar = sectionOf(git(['show', mergeBase + ':' + bar]));

const newBar = sectionOf(readBar());

const within = (range, n) => range !== null && n >= range[0] && n <= range[1];

const isConstraints = (l, side) => l.file === bar && within(side === 'old' ? oldBar : newBar, l.line);

// A section the old text had and the new one lacks is the bar removed or renamed, never a quiet

// skip.

if (oldBar !== null && newBar === null) flag('section-removed', bar, '## Constraints');

// 1. Silenced checker — extend this list for your ecosystem.

const SUPPRESSIONS = /@ts-ignore|@ts-nocheck|eslint-disable|biome-ignore|# *noqa|# *type: *ignore|istanbul ignore|nosemgrep|gitleaks:allow|Stryker disable/;

// 4. Unfinished work.

const STUBS = /throw new (Error|NotImplemented).*[Nn]ot implemented|catch\s*\(\w*\)\s*\{\s*\}|catch\s*\{\s*\}|\bTODO\b|\bpass\s*# *stub/;

// 2. A test made easier (added skips).

const SKIPS = /\.(skip|todo)\b|\bxit\(|\bxdescribe\(|@pytest\.mark\.skip|t\.Skip\(/;

for (const entry of added) {

const { file, text } = entry;

// The bar's section and the guard's own file name the patterns they forbid, so neither is

// scanned for them: the change that introduces the two passes, and the same pattern added

// anywhere else is flagged.

const scanned = file !== self && !isConstraints(entry, 'new');

if (scanned && SUPPRESSIONS.test(text)) flag('silenced-checker', file, text);

if (scanned && STUBS.test(text)) flag('unfinished-work', file, text);

if (scanned && SKIPS.test(text)) flag('test-made-easier', file, text);

if (isConstraints(entry, 'new') && /^\| *(W|E)\d+ *\|/.test(text)) flag('new-exception', file, text);

}

// 2b. A test file deleted, or an assertion removed from a test file that still exists.

for (const f of deleted) if (isTest(f)) flag('test-deleted', f, 'file deleted');

for (const { file, text } of removed) {

if (isTest(file) && !deleted.includes(file) && /\b(expect|assert|should)\b/.test(text)) {

flag('assertion-removed', file, text);

}

}

// 1b/2c. A rule of the bar weakened or removed. A rule is a floor bullet or a table row,

// identified by the bullet's text before its first colon or by the row's first cell. Each number

// carries a direction read from the words around it: a minimum (>=, at least, must not fall) is

// loosened by going down, a maximum (<=, at most, under, must not grow) by going up. A number whose

// direction cannot be read is reported whenever it changes, because the guard cannot tell

// tightening from loosening and staying quiet is the wrong default. Numbers are paired within

// their direction (the first minimum with the first minimum, and so on), so a number added

// elsewhere in the text does not shift the pairing; a threshold with no counterpart after the

// edit was removed, and an added one tightens.

const ruleKey = (t) => {

const s = t.trim();

if (s.startsWith('|')) return s.split('|').map((c) => c.trim()).filter(Boolean)[0] ?? '';

if (/^[-*] /.test(s)) return s.slice(2).split(':')[0].trim();

return null; // prose, headings, dates: not a rule

};

const isException = (t) => /^\| *(W|E)\d+ *\|/.test(t.trim());

const MIN_BEFORE = /(>=|>|≥|at least|minimum|\bmin\b|no less than|not fall|not drop)\s*$/;

const MAX_BEFORE = /(<=|<|≤|at most|maximum|\bmax\b|no more than|under|below|not grow|not exceed)\s*$/;

const MIN_AFTER = /^\s*\S*\s*(or more|or higher|must not fall|must not drop)/;

const MAX_AFTER = /^\s*\S*\s*(or less|or lower|must not grow|must not exceed)/;

const thresholds = (t) => {

const out = [], re = /\d+(?:\.\d+)?/g;

let m;

while ((m = re.exec(t))) {

const before = t.slice(Math.max(0, m.index - 24), m.index).toLowerCase();

const after = t.slice(m.index + m[0].length, m.index + m[0].length + 40).toLowerCase();

const dir = MIN_BEFORE.test(before) || MIN_AFTER.test(after) ? 'min'

: MAX_BEFORE.test(before) || MAX_AFTER.test(after) ? 'max' : null;

out.push({ n: Number(m[0]), dir });

}

return out;

};

const removedRules = removed.filter((l) => isConstraints(l, 'old') && ruleKey(l.text) !== null);

const addedRules = added.filter((l) => isConstraints(l, 'new') && ruleKey(l.text) !== null);

for (const r of removedRules) {

const a = addedRules.find((x) => ruleKey(x.text) === ruleKey(r.text));

if (!a) {

if (!isException(r.text)) flag('rule-removed', r.file, r.text); // dropping an exception tightens: silent

continue;

}

const before = thresholds(r.text), after = thresholds(a.text);

let verdict = null;

for (const dir of ['min', 'max', null]) {

const was = before.filter((x) => x.dir === dir), now = after.filter((x) => x.dir === dir);

was.forEach((b, i) => {

const n = now[i];

if (verdict) return;

if (!n) verdict = 'threshold-removed';

else if (n.n === b.n) return;

else if (dir === 'min' ? n.n < b.n : dir === 'max' ? n.n > b.n : true) {

verdict = dir ? 'threshold-loosened' : 'threshold-changed';

}

});

}

if (verdict) flag(verdict, r.file, r.text + ' -> ' + a.text);

}

if (findings.length === 0) { console.log('floor-guard: clean'); process.exit(0); }

console.error('floor-guard: ' + findings.length + ' floor violation(s):');

for (const f of findings) console.error(` [${f.rule}] ${f.file}: ${f.text}`);

if (findings.some((f) => f.rule === 'rule-removed')) {

console.error('\nA rule-removed finding can also mean the rule\'s label changed: rename a rule in one commit and change its thresholds in another.');

}

if (findings.some((f) => f.rule === 'threshold-removed')) {

console.error('\nA threshold-removed finding can also mean a number gained or lost its direction words (">= 80%" becoming "80%", or the reverse): compare the two lines before assuming a threshold was deleted.');

}

console.error('\nEach is a move that lowers the bar. Fix the code, or route it through a tracked exception.');

process.exit(1);

```

## Adapting it

- **Patterns are the only stack-specific part.** Add your language's suppression and stub forms to the three regexes; the diff plumbing, the bar's checks, and the exit codes stay as-is.

- **A `.constraintsignore`** (one glob per line) lets you exempt a path the guard would otherwise flag; check each added line's file against it before flagging, so a genuine exception is a tracked file rather than a loosened rule.

- **This is a starting point, not a finished tool.** It is deliberately regex-shallow: it catches the cheap-road-to-green moves agents actually make, not a determined human hiding a change. That is the right trade for a check that runs on every diff. Once you outgrow it, move to a real runner (Escalation Path level 3).