AI-generated code guardrails

Every import added by a change names a package that actually exists and a symbol that package actually exports — no invented helper, no method borrowed from a neighbouring library, no import of a module the change never creates. Hallucinated imports are the signature failure of generated code, and attackers publish packages under commonly hallucinated names precisely so that installing one by mistake runs their code.

Blocks: at best it fails at runtime, at worst it installs someone else's code. Judged on the import lines the change adds — whether an already-declared dependency is still in the manifest is a job for your lockfile, not for this rule.

`TODO`, `FIXME`, `...`, `pass # implement`, `throw new Error("not implemented")` and stubbed return values must not appear in a pull request opened for review. Generated scaffolding reads as complete — the surrounding code is fully written — so a placeholder in the middle survives review far more often than a missing function would.

Blocks: it is a known hole shipping with the appearance of finished work.

A catch block logs with context and then rethrows or returns a typed failure. An empty catch, or one that swallows the error into a default value, is rejected unless a comment on the same line states why that default is the correct outcome. Agents resolve uncertainty by catching and continuing, which converts a loud bug into a quiet wrong answer.

Blocks: swallowed errors turn debuggable failures into unexplainable data.

Any retry loop, pagination loop, polling loop or `while (true)` declares a maximum iteration count and a backoff. Unbounded retry against a degraded dependency is a self-inflicted outage: your service turns a partner's slow minute into a traffic amplification attack on both of you.

Blocks: the blast radius extends beyond your own service.

A change must not hand-roll an operation it already imports a helper for, and must not add two implementations of the same utility — date formatting, retry, slugify, deep clone, currency formatting. Agents write from scratch by default because it is faster than searching; three date formatters is how a codebase stops having one behaviour.

Warns: duplication is a maintenance cost, not a defect — and the gate only sees the duplication inside the change itself. A helper that already exists elsewhere in the repo is still the reviewer's catch.

A change must not introduce a second way of doing something it is already doing elsewhere in the same change: `require` next to `import`, a new HTTP client alongside the calls it just wrote, a second assertion library in the same test file, two different error shapes for the same kind of failure. The cost is not aesthetic — it doubles what every future reader, human or agent, has to hold in mind.

Warns: it is drift, not breakage — and it is judged on the lines the change adds, so consistency with the untouched rest of the file stays a human call.

A diff must not add commented-out implementations, unused helpers, or a second code path kept "in case". Agents hedge by leaving both versions in place; the next reader — human or agent — cannot tell which one is the intended design and will preserve both.

Warns: it is clutter with compounding cost, not a defect on its own.

A new test must fail if the behaviour breaks. Tests that only assert a mock was called, snapshot an entire structure with no assertion about meaning, or re-implement the function under test are rejected. Generated tests optimise for passing, and a test that cannot fail is worse than no test — it buys confidence with nothing behind it.

Warns: a weak test is not an outage, but it is a false signal in every future review.

Code that keeps mutable state at module level, assumes a single running instance, or relies on ordered delivery must say so in a comment next to it. Agents reach for module-level caches and counters readily; they work perfectly on one machine and break as soon as a second replica starts.

Warns: it is correct today in many deployments — the comment is what makes it reviewable.

A comment added next to code explains why the code is that way, and must not contradict the line it sits on or narrate what that line already says. Generated code narrates by default, and a comment describing an earlier version of the logic is trusted far longer than stale code — nobody re-reads a comment with suspicion.

Informational: a readability defect that only costs later — but it is what makes the next reader, and the next agent, get the file wrong.