AI SDLC Governance: Three Layers for Engineering Leaders

The same AI tooling. Two engineering organizations. Opposite outcomes: one cut pull request (PR) cycle time 31.8% while AI-generated code volume scaled 750x over six months (Kumar et al., 2025); the other saw PR closure time climb 42%, from 5:52 to 8:20 hours, partly from deeper engagement with automated feedback (Cihan et al., 2025). Neither study isolates governance maturity as the causal variable. Both show that AI impact is highly context-dependent; organization-level workflow, review, and platform conditions are plausible contributors worth measuring rather than assuming away.

This post gives that scaffolding as a three-layer model, comprehension, review gate, and observability, with patterns from two production open-source repositories: aptu-coder, an MCP (Model Context Protocol) comprehension server, and aptu, a GitHub App for automated PR review and security scanning.

Table of contents

What Is a Governance Stack for AI-Generated Code?

A governance stack for AI-generated code is not a single tool. It is three layers, each addressing a distinct failure mode that appears when AI-generated code moves from an editor into a shared codebase.

Three Layers, Three Failure Modes

The comprehension layer provides structured analysis before any code is generated or reviewed. Without a symbol table, call graph, or AST (abstract syntax tree), agents operate on raw file bytes, a condition of context starvation that compounds with codebase scale.

The review gate layer combines automated review with graduated escalation, not binary approve/reject, at the PR boundary. When that gate is shallow, verification gaps accumulate, a pattern examined in AI Approval Gates.

The observability layer captures provenance an agent cannot self-verify. Without it, the stack produces no reconstructable audit trail, examined further in AI Observability Gaps.

Each layer functions independently; the stack is what their integration produces, extending the accountability-layer thesis in AI-Assisted Development.

A fourth risk sits at the integration boundary: drawn from 1,600+ annotated traces across seven frameworks, UC Berkeley’s Multi-Agent System Failure Taxonomy (MAST) finds that review layers added without defined input/output contracts reproduce specification errors in CI rather than eliminating them (Cemri et al., 2025).

How Does the Comprehension Layer Work?

The comprehension layer gives agents and reviewers a structured understanding of a codebase before either generates or reviews a line of code. aptu-coder, an MCP server written in Rust, is a concrete implementation.

Structured Analysis Over Raw File Reads

aptu-coder provides structured analysis across 18 languages, 13 via tree-sitter AST and 5 via structured regex fallback, exposing four tools, analyze_directory, analyze_file, analyze_module, and analyze_symbol, over a streamable HTTP transport that multiple delegate agents share concurrently. An agent receives pre-parsed symbol tables and call graphs directly, rather than reading raw file bytes and re-deriving structure on every call. Token-cost evidence for this approach, benchmarked against Django and OpenFAST, is documented in AI Adoption in Engineering, referenced here rather than reprinted.

Comprehension-Generation Asymmetry and Why It Matters

A survey of more than 1,400 papers establishing context engineering as a distinct discipline identified a core finding: models process complex input context far more reliably than they produce equivalent long-form output, an asymmetry the survey terms comprehension-generation asymmetry (Mei et al., 2025). aptu-coder’s structured output exploits this deliberately: an agent receiving pre-parsed AST, call graphs, and symbol tables works in the domain where models perform best, instead of expanding into an unrestricted repository scan.

The Agentic Context Engineering (ACE) framework reinforces this: it matches a top-ranked production agent using a smaller open-source model by controlling context evolution instead of upgrading model scale (Q. Zhang et al., 2025). Context management, not model size, is the cost lever both findings point to.

How Does the Review Gate Layer Work?

The review gate layer sits at the pull request boundary. aptu, a GitHub App, implements this layer as configuration-as-code rather than a mandatory pipeline step.

Configuration as Code: The Opt-In Governance Model

Configuration enforces opt-in per repository via .github/aptu.yml, with precise path scoping. Credentials follow a tiered model: allowlisted organizations share managed AI credentials; external installs supply their own or receive HTTP 403. Install via the aptu GitHub App.

version: 1
triage:
  enabled: true
review:
  enabled: true
  skip-labeled: true
  instructions-file: .github/instructions/pr-review.md
ai:
  provider: openrouter
  model: google/gemma-4-26b-a4b-it
  api-key-secret: OPENROUTER_API_KEY
path_filters:
  - "src/**"
  - "crates/**"
  - "!**/*.md".github/aptu.yml

What the Benchmark Actually Measures

A self-reported internal benchmark compared aptu+mercury-2 against raw claude-opus-4.6 across six fixtures, one run per fixture, directional only and not independently verified. Scores reflect the author’s assessment against a fixed rubric: issue coverage, specificity of feedback, absence of hallucinated findings, and actionable framing.

The comparison is architecturally unequal by design: the raw opus baseline used a generic two-sentence prompt with no schema, rubric, or AST context. The result illustrates the architecture pattern, not a model capability claim.

The narrow savings range (93-96%) across fixture types reflects that review cost is dominated by fixed context size, not fixture complexity; the architecture’s cost advantage is structural, not fixture-dependent. ByteDance’s BitsAI-CR confirms at industrial scale that purpose-built structured pipelines outperform generic prompting regardless of model choice (Sun et al., 2025).

What Does the CI/CD Harness Look Like in Practice?

CI/CD enforcement and release attestation are the mechanisms that make the review and observability controls enforceable. The CI/CD harness turns those patterns into gates.

A Multi-Job Pipeline Where Every Gate Has a Purpose

The CI pipeline (Figure 2) has a defined dependency graph: a path filter gates all downstream jobs; quality and security jobs run in parallel where possible. Notably, the local just lint recipe omits the cognitive-complexity flag CI enforces, meaning CI is authoritative.

The scan-self job produces both outputs in a single invocation. The --output github-annotations flag fails the PR on critical and high findings; --sarif-output writes a permanent SARIF (Static Analysis Results Interchange Format) record to Code Scanning.

  scan-self:
    permissions:
      contents: read
      security-events: write
    needs: [changes, build]
    if: needs.changes.outputs.code == 'true'
      && needs.build.result == 'success'
    # ... checkout and artifact download omitted
    steps:
      - name: Run security scan and generate SARIF
        if: always()
        run: |
          ./target/ci/aptu scan-security crates/ \
            --output github-annotations \
            --sarif-output findings.sarif \
            --fail-on critical,high
      - name: Upload SARIF report
        if: always()
        uses: github/codeql-action/upload-sarif@18420e3271f74589575af831a523c833acda327f
        with:
          sarif_file: findings.sarif
          category: aptu-scan-security.github/workflows/ci.yml

Code Complexity as a First-Class CI Gate

The check job (Code Snippet 3) enforces the cognitive-complexity lint on every PR. -D warnings promotes every clippy warning to a hard error, so a function exceeding the complexity threshold fails the PR exactly as a failing test would, rejecting hard-to-reason-about code regardless of who wrote it. Teams adopting this pattern should be explicit about the local-CI gap, or developers may believe they passed locally when only CI enforces it.

  check:
    name: Check Format & Lint
    runs-on: ubuntu-24.04-arm
    needs: changes
    timeout-minutes: 10
    if: (needs.changes.outputs.code == 'true'
      || github.event_name != 'pull_request')
      && github.actor != 'renovate[bot]'
    steps:
      # checkout, rust-toolchain, rust-cache omitted
      - name: Check formatting
        run: cargo fmt --check
      - name: Run Clippy lints
        run: |
          cargo clippy --locked --profile ci \
            -- -D warnings \
            -W clippy::cognitive_complexity
      - name: Build examples
        run: cargo build --examples --locked -p aptu-core --profile ci.github/workflows/ci.yml

Dual-Mode Security Scanning: Shift-Left and Persistent Record

PR scanning and the post-merge scan reuse the same binary: one gates the PR with transient, diff-scoped feedback; the other persists findings to Code Scanning as a queryable audit trail. The AI review step operates on structured scanner output, not raw diffs, consistent with the Tier 1 boundary in AI-Augmented CI/CD: AI analyzes linter and scanner JSON, never untrusted code directly. This is the shift-left-plus-persistent-record pattern with supply-chain provenance, as argued in AI Supply Chain Attack Vectors.

Local Guardrails: The Pre-CI Line of Defence

Local hooks are one enforcement point. A more complete guardrail pairs them with a recipe and an AGENTS.md file. Goose validates its own pipeline by running goose run --recipe goose-self-test.yaml before any release; its AGENTS.md defines contribution invariants every agent inherits. The aptu repository takes a CI-authoritative approach: a just check recipe approximates the CI gate locally, while CI remains the final enforcer. Both patterns are defensible; local guardrails reduce what CI has to catch, and CI enforces what local discipline cannot. For the structured handoff chain that makes decisions reconstructible, see Orchestrating AI Agents: A Subagent Architecture.

How Does the Attestation Chain Close the Loop?

The comprehension, review, and CI layers converge at release time. The attestation chain seals the evidence linking each artifact to its source, build, and required approvals.

From Commit to Release: A Named Human at Every Step

The aptu repository’s AI_POLICY.md, its machine-readable policy manifest enforced by CI, states: “This policy is backed by enforced controls: GPG-signed commits, Developer Certificate of Origin (DCO), required code owner review, SLSA (Supply-chain Levels for Software Artifacts) Level 3 build provenance, and OpenSSF Best Practices Silver. These are not decorative. They ensure that a named, verified human is accountable for every change that reaches users.” Each control maps to a named CI gate: a verify-tag-signature job blocks lightweight or unverified tags before release runs, CODEOWNERS enforces reviewer accountability, and an isolated reusable workflow produces SLSA Level 3 provenance.

Two Independent Signatures Per Release Artifact

Each release artifact carries two independently verifiable signatures (Figure 3): cosign’s resolves against the public transparency log, while GitHub’s native attestation resolves against a queryable SLSA provenance predicate. A user downloading any release binary can verify that the artifact matches what the CI build produced and that the signing event was publicly logged, addressing the risk covered in AI Supply Chain Attack Vectors.

      - name: Sign tarball with cosign
        run: |
          cosign sign-blob --yes \
            --bundle "${{ steps.upload-cli.outputs.tar }}.bundle" \
            "${{ steps.upload-cli.outputs.tar }}"
      - name: Upload bundle to release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh release upload $RELEASE_TAG \
            "${{ steps.upload-cli.outputs.tar }}.bundle" --clobber
      # actions/attest-build-provenance v4 (full commit SHA pin)
      - name: Attest build provenance
        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373
        with:
          subject-path: ${{ steps.upload-cli.outputs.tar }}.github/workflows/build-and-attest.yml

How Should Engineering Leaders Measure the Stack?

Engineering leaders should measure the governance stack with provenance-backed KPIs, not raw AI activity metrics. Two studies that appear contradictory resolve once governance scaffolding maturity is accounted for.

Reconciling the METR and Enterprise Longitudinal Results

A 19% measured slowdown (Becker et al., 2025) and a 31.8% cycle-time reduction (Kumar et al., 2025) are not contradictory. METR measured experienced open-source contributors working in their own repositories with early-2025 tooling; Kumar measured a mature in-house platform over a full year with adoption ramp-up and later models. Differences in scaffolding maturity and model generation are plausible contributors to the gap; neither study isolates either variable. The direction is consistent: governance infrastructure compounds over time.

Five KPIs That Require Provenance, Not Just Metrics

Five observable KPIs track the stack’s effect rather than the technology’s raw output. Each requires decision provenance, the AI Observability Gaps pattern of event-level logs reconstructing who reviewed a change, under what context, and with what outcome. A minimal event record covers the review-side essentials: {pr_id, actor, decision, context_tokens, cost_usd, timestamp}; specification errors can pass CI while still breaking end to end. Without that infrastructure, these become lagging indicators no one can act on. Vendor-cited leaderboard scores are directional signals, not procurement criteria. SWE-bench Pro shows frontier models reaching at most 23% success on long-horizon tasks, against 70%+ on the prior easier benchmark (Deng et al., 2025). This gap is exactly what these KPIs are designed to surface.

The KPIs also surface two organizational shifts worth tracking: real-world productivity gains typically run 5-15%, not 10x (getDX, 2026). Results can be higher in bounded workflows with explicit measurement, and the bottleneck moves from code production to specification quality and reviewer capacity. Planning sessions should shift time from task estimation to problem framing and output contracts. These five KPIs are scoped to the governance stack; burnout and adoption signals belong to the program layer covered in AI Adoption for Engineering Leaders.

Where Does the Governance Stack Go Next?

Engineering leaders should instrument decision provenance, cap automated iteration depth, and track cost-per-resolved-PR before expanding AI code generation volume.

Three Concrete Steps for Engineering Leaders

First, instrument before automating: deploy decision-provenance observability along the AI Observability Gaps pattern before expanding AI code generation volume, since the KPIs above depend on that infrastructure already being in place. Second, gate iteration depth: enforce a bounded refinement cap, for example three refinement cycles per PR, in CI before a change is escalated; security-degradation research documents a 37.6% increase in critical vulnerabilities across five iterative AI refinement rounds and recommends human validation between iterations (Shukla et al., 2025). Add the cap as a hard CI failure condition, not a cultural norm that erodes under deadline pressure. Third, price the stack explicitly: track cost-per-resolved-PR over time. Absolute cost will fall as inference costs decline (Gundlach et al., 2025), but the value of review discipline embedded in the stack will not.

The Governance Stack Is the Scaffolding, Not the Tax

AI code tooling is not the bottleneck; the quality of its governance scaffolding is. Confirm three conditions before scaling further: decision provenance is instrumented; automated iteration is capped at three refinement cycles per PR before escalation; and cost-per-resolved-PR is tracked as a longitudinal baseline. Leaders who can answer yes to all three can scale with evidence. Those who cannot are scaling risk.

References

• Becker, J. et al. (METR), “Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity” (2025): https://arxiv.org/abs/2507.09089
• Cemri, M. et al. (UC Berkeley), “Why Do Multi-Agent LLM Systems Fail?” (2025): https://arxiv.org/abs/2503.13657
• Cihan, U. et al., “Automated Code Review In Practice” (ICSE 2025): https://arxiv.org/abs/2412.18531
• Deng, X. et al., “SWE-Bench Pro: Can AI Agents Solve Long-Horizon Software Engineering Tasks?” (2025): https://arxiv.org/pdf/2509.16941
• getDX (Noda, A. & Reock, J.), “AI productivity gains are 10%, not 10x” (2026): https://getdx.com/blog/ai-productivity-gains-are-10-percent-not-10x/
• Gundlach, H. et al., “The Price of Progress: Algorithmic Efficiency and the Falling Cost of AI Inference” (2025): https://arxiv.org/abs/2511.23455
• Kumar, A. et al., “Intuition to Evidence: Measuring AI’s True Impact on Developer Productivity” (2025): https://arxiv.org/abs/2509.19708
• Mei, L. et al., “A Survey of Context Engineering for Large Language Models” (2025): https://arxiv.org/abs/2507.13334
• Shukla, S. et al., “Security Degradation in Iterative AI Code Generation: A Systematic Analysis of the Paradox” (2025): https://arxiv.org/abs/2506.11022
• Sun, T. et al. (ByteDance), “BitsAI-CR: Automated Code Review via LLM in Practice” (FSE 2025): https://conf.researchr.org/details/fse-2025/fse-2025-industry-papers/24/BitsAI-CR-Automated-Code-Review-via-LLM-in-Practice
• Zhang, Q. et al., “Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models” (2025): https://arxiv.org/abs/2510.04618