AI Governance for Large Legacy Codebases

Gradual Rollout: Strangler & codemod, no big bang

Background & principle

Martin Fowler's Strangler Fig: don't rewrite — grow new structure at the boundary and gradually "strangle" the old until it can be removed. Two concrete tactics for governance. First, changed-files-only gating: new rules (type checks, lint, complexity limits) enforce only on the files actually modified in a PR — existing code is exempt but frozen — so the rule seeps in as developers "fix what they touch," instead of detonating overnight. Second, hand mechanical legacy conversion to codemods (jscodeshift / OpenRewrite / ast-grep) — AST-level scripts do bulk edits instead of humans hand-editing file by file. AI's role is clear: the long tail a codemod can't handle (irregular semantics, needs judgment) goes to an agent for bulk edits — but every change still passes the §3/§4 gates.

In practice

# strict checks only on files changed in this PR; legacy untouched
CHANGED=$(git diff --name-only origin/main... | grep '\.ts$')
if [ -n "$CHANGED" ]; then
  npx tsc --noEmit --strict $CHANGED      # new/changed files must pass strict
  npx eslint --max-warnings 0 $CHANGED    # legacy files not in the list → exempt
fi
# mechanical migration via codemod, not by hand:
# npx jscodeshift -t rename-api.js src/   ·   ast-grep --pattern '...' --rewrite '...'

Core mental model: wire governance to the diff, not to a whole-repo scan. A whole-repo scan produces thousands of violations you won't fix today — it only trains the team to "ignore red," which is how governance dies.

The Ratchet & Guardrails-as-Code: make the repo only get better

Background & principle

Ratchet: record the current violation count as a baseline; CI fails only when it's worse than baseline. Existing debt is tolerated, new debt is blocked; each fix lowers the baseline, and it can't ratchet back up — one direction only. Tools like betterer make this a general mechanism. The companion is guardrails-as-code / fitness functions (Building Evolutionary Architectures): write architecture constraints as executable tests — dependency direction, layer boundaries, forbidden imports, complexity limits — run via ArchUnit / dependency-cruiser / import-linter. Governance shifts from "docs + people watching" to "CI red/green," depending on no one's memory. AI's place: have an agent shave the baseline a little per PR (fix one or two legacy items), so the long-tail debt gets ground down inside normal work — not deferred to a "refactor sprint" no one ever has time for.

In practice

# fitness function: "UI layer must not import the DB directly" as a test
import { dependencyCruiser } from "dependency-cruiser"
forbidden = [{
  name: "ui-not-to-db",
  from: { path: "^src/ui" },
  to:   { path: "^src/db" },          # violation = CI red, not caught by review
}]

# ratchet: only block "worse than yesterday"
BASE=$(cat .debt-baseline)               # e.g. 412
NOW=$(count_violations)
if [ "$NOW" -gt "$BASE" ]; then echo "debt rose: $BASE→$NOW"; exit 1; fi
[ "$NOW" -lt "$BASE" ] && echo "$NOW" > .debt-baseline   # lock the new low

Review Without the Bottleneck (I): machines filter first

Background & principle

Think of code review as Day 34 HITL's confidence routing applied to code: each PR first passes a row of pre-human gates — tests, types, lint, coverage delta, SAST/secret scan, dependency audit, change-impact analysis. A gate not passed = deny; it never enters the human queue. Only when all gates pass does a human decide whether to review closely. This is especially valuable for AI-generated code: AI's most frequent failures — hallucinated APIs, turning a failing test into assert True to make CI green (see Day 31's test tampering), missed null / concurrency edge cases — are largely machine-detectable. Let sanitizers, the type system, mutation tests, and secret scanners catch that layer, so human attention isn't wasted on "what a machine could have found." The inverse holds too: don't make a human do what a machine does better (humans can't read out a race condition, but ThreadSanitizer can).

Review Without the Bottleneck (II): risk tiers · sampling · provenance

Background & principle

Three things compress human attention to a level that can actually review carefully. ① Risk scoring: tier by the paths touched — payment / auth / data migration / crypto = high; copy / tests / comments = low — layered with diff size and blast radius (see Day 31). High-risk forces full review + a CODEOWNERS owner; low-risk gets sampled human review + full post-merge audit. ② Trust tiering: give "AI authors" and "human authors" different default review intensity, adjusted by track record (same as Day 34's audit-driven retuning) — a newly wired agent is reviewed strictly, then relaxed once it's proven. ③ Provenance / attestation: mark which code was AI-generated, with which model / prompt (SLSA-style). When something breaks you can pinpoint it and bulk-recall "all code from one bad prompt" — a necessity at AI scale, not a compliance ornament.

In practice

def review_policy(pr):
    paths = pr.changed_paths
    high = any(p.startswith(("src/payment","src/auth","migrations/")) for p in paths)
    risk = "high" if high or pr.diff_lines > 400 else "low"
    trust = author_trust(pr.author)         # new AI < senior human, adjusts with record
    if risk == "high": return "full_review + CODEOWNERS"
    if trust < 0.7:      return "full_review"
    return "sample_5pct + post_merge_audit"   # low risk, high trust → sample

# carry origin metadata on the PR for tracing / recall
provenance = { "ai_generated": True, "model": "claude-opus-4-8", "prompt_id": "refactor-v3" }