Enforce AI Rationale footer for files with high AI density

attribution is secondary to cognitive ownership. The data proves that teams can safely leverage AI at high densities if they enforce design memory preservation and complexity gates.

Core Solution

Mitigating cognitive debt requires a shift from passive AI consumption to an Accountability-First Workflow. This involves automated attribution tracking, immutable design memory, and cognitive ownership gates. The solution treats AI-generated code similarly to third-party dependencies: it must be validated, documented, and monitored.

1. Automated Attribution Engine

Manual git blame inspection is insufficient for large codebases. You need a programmatic way to quantify AI density, particularly in critical paths. The following TypeScript utility parses git porcelain output to generate a machine-readable attribution report. This enables CI integration and trend analysis.

// tools/ai-attribution-reporter.ts
import { simpleGit } from 'simple-git';
import { glob } from 'glob';
import fs from 'fs/promises';

export interface AttributionMetrics {
  filePath: string;
  totalLines: number;
  aiAttributedLines: number;
  density: number;
  lastAiCommitHash: string;
}

export async function generateAttributionReport(
  repoRoot: string,
  pattern: string
): Promise<AttributionMetrics[]> {
  const git = simpleGit(repoRoot);
  const files = await glob(pattern, { cwd: repoRoot, absolute: true });
  const reports: AttributionMetrics[] = [];

  for (const file of files) {
    try {
      const blame = await git.blame(['--porcelain', file]);
      const lines = blame.split('\n');
      let aiLines = 0;
      let lastAiHash = '';

      // Parse porcelain output to identify AI-authored lines
      // Assumes AI commits are tagged with a specific author or email pattern
      const aiSignature = /AI-Assistant|claude-code/i;

      for (let i = 0; i < lines.length; i++) {
        const line = lines[i];
        if (line.startsWith('author-mail')) {
          if (aiSignature.test(line)) {
            aiLines++;
            // Extract hash from the header line preceding the author-mail
            const headerMatch = lines[i - 1]?.match(/^([0-9a-f]{40})/);
            if (headerMatch) lastAiHash = headerMatch[1];
          }
        }
      }

      const totalLines = lines.filter(l => !l.startsWith('\t')).length;
      reports.push({
        filePath: file,
        totalLines,
        aiAttributedLines: aiLines,
        density: totalLines > 0 ? aiLines / totalLines : 0,
        lastAiCommitHash: lastAiHash,
      });
    } catch (error) {
      console.warn(`Failed to analyze ${file}: ${error}`);
    }
  }

  return reports.sort((a, b) => b.density - a.density);
}

Rationale: This approach uses simple-git for robust parsing and outputs structured JSON. Unlike shell scripts, this integrates easily into Node-based CI pipelines and allows for complex filtering logic. The aiSignature regex can be configured to match your team's convention for AI commits.

2. Domain-Specific Filtering Configuration

Not all code carries equal risk. Boilerplate and configuration files have lower cognitive debt than domain logic. A configuration file defines the scope of accountability enforcement.

// .ai-attribution.config.json
{
  "highRiskPatterns": [
    "src/domain/**/*.ts",
    "src/services/**/*.ts",
    "src/handlers/**/*.ts",
    "src/lib/crypto/**/*.ts"
  ],
  "lowRiskPatterns": [
    "src/generated/**",
    "src/config/**/*.ts",
    "**/*.test.ts"
  ],
  "thresholds": {
    "maxAiDensityHighRisk": 0.40,
    "requireRationaleAboveDensity": 0.20
  }
}

Rationale: This configuration allows teams to set density thresholds. If AI density in highRiskPatterns exceeds 40%, the CI pipeline can block merges or require elevated review. The requireRationaleAboveDensity flag triggers mandatory design memory documentation.

3. Immutable Design Memory via Commit Hooks

Design memory is lost when AI context is not preserved in the commit history. You must enforce a commit convention that captures the "why" behind AI-generated decisions. A commit-msg hook ensures this metadata is present before code enters the repository.

// .husky/commit-msg
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# Enforce AI Rationale footer for files with high AI density
# This script runs during commit-msg hook

AI_RATIONALE_PATTERN="AI-Rationale:"
COMMIT_MSG_FILE="$1"
COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")

# Check if commit touches high-risk files
# (Simplified check; production should use git diff --cached --name-only)
if git diff --cached --name-only | grep -qE "src/domain|src/services"; then
  if ! echo "$COMMIT_MSG" | grep -q "$AI_RATIONALE_PATTERN"; then
    echo "❌ ERROR: AI-generated changes in critical paths require an 'AI-Rationale:' footer."
    echo "Example:"
    echo "  AI-Rationale: Used exponential backoff with jitter to handle rate limits."
    echo "  AI-Rationale: Chose recursive CTE over loop for hierarchical data retrieval."
    exit 1
  fi
fi

Rationale: This hook enforces traceability at the source. By requiring an AI-Rationale: footer, the design context becomes searchable in git log and survives the deletion of chat histories. This transforms ephemeral AI context into permanent engineering documentation.

4. The Cognitive Ownership Gate

Automation supports but does not replace human judgment. Teams must enforce a Complexity Cutoff: if a developer cannot explain the implementation logic of a code block in two sentences without re-reading the source, the code must not be committed.

• Implementation: Add a checklist item to the Pull Request template:

  [ ] Cognitive Verification: I can explain the algorithm, trade-offs, and edge cases of the AI-generated code without referring to the original prompt.

• Review Process: Treat AI-generated code as a third-party dependency. Reviewers should focus on verifying correctness, security implications, and alignment with domain invariants, rather than just syntax.

Pitfall Guide

Pitfall	Explanation	Fix
The "Green Build" Mirage	Developers assume code is safe because tests pass. AI can generate code that satisfies tests but contains subtle logic errors or performance bottlenecks.	Enforce the Complexity Cutoff. Tests verify behavior, not understanding. Require manual explanation of logic before merge.
Context Amnesia	AI conversation history is deleted or inaccessible, leaving no record of why a specific approach was chosen.	Use the AI-Rationale commit footer. Embed design decisions directly in the commit message to create immutable design memory.
DCO Non-Compliance	Contributing AI-generated code to projects with a Developer Certificate of Origin (DCO), such as the Linux Kernel or FSF projects, may violate contribution policies.	Verify project contribution guidelines before submitting AI-assisted PRs. Some projects explicitly prohibit AI-generated contributions.
License Contamination	AI models may inadvertently reproduce code snippets from GPL or other restrictive licenses, creating legal risk.	Integrate license scanning tools (e.g., Snyk, FOSSA) into the CI pipeline. Monitor for license violations in AI-generated blocks.
Metric Myopia	Teams track velocity or lines of code but ignore "AI Density" or "Debug Readiness," leading to unmanaged cognitive debt.	Implement the Attribution Reporter to track AI density trends. Set alerts when density in high-risk patterns exceeds thresholds.
The "Human Proxy" Error	When incidents occur, blame falls on the human committer, who may not understand the code. This erodes trust and slows resolution.	Tag AI-generated code in attribution reports. Ensure postmortems reference the AI-Rationale footer to reconstruct decision chains.
Over-Reliance on Legal IP	Focusing solely on copyright ownership distracts from the immediate operational risks of unmaintainable code.	Shift engineering metrics toward postmortem readiness, traceability, and cognitive ownership. Legal IP is a secondary concern.

Production Bundle

Action Checklist

• Deploy Attribution Reporter: Integrate the TypeScript attribution utility into your CI pipeline to generate weekly AI density reports.
• Configure Risk Patterns: Define highRiskPatterns and thresholds in .ai-attribution.config.json based on your domain architecture.
• Enable Commit Hooks: Install the commit-msg hook to enforce AI-Rationale footers for changes in critical paths.
• Update PR Templates: Add a "Cognitive Verification" checklist item to all Pull Request templates.
• Scan for Licenses: Configure license scanning tools to flag potential reproduction of restrictive licenses in AI-generated code.
• Train Reviewers: Educate code reviewers on treating AI-generated code as third-party dependencies requiring rigorous validation.
• Monitor Trends: Review attribution reports monthly to identify files or modules with escalating AI density and schedule refactoring or documentation sprints.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Boilerplate / Config	AI-Assisted (Unchecked)	Low cognitive risk; high ROI for velocity.	Low
Core Domain Logic	AI-Assisted (Accountability-First)	High cognitive risk; requires traceability and design memory.	Medium
Security / Crypto	Manual Development	Zero tolerance for opaque logic; AI may introduce subtle vulnerabilities.	High
Open Source Contribution	Policy-Compliant Review	DCO and license restrictions may prohibit AI code; strict compliance needed.	Variable
Legacy Refactoring	AI-Assisted (Accountability-First)	AI can suggest improvements, but rationale must be documented to preserve intent.	Medium

Configuration Template

Commitlint Configuration Enforce the AI-Rationale footer using commitlint.

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'footer-missing': [2, 'never'],
    'ai-rationale-required': [
      2,
      'always',
      {
        pattern: /^AI-Rationale:\s+.+$/m,
        message: 'AI-Rationale footer is required for AI-generated changes.',
      },
    ],
  },
  plugins: [
    {
      rules: {
        'ai-rationale-required': (parsed, when = 'always', value) => {
          const hasAiRationale = parsed.footer && value.pattern.test(parsed.footer);
          return when === 'always' ? [hasAiRationale, value.message] : [true, ''];
        },
      },
    },
  ],
};

Attribution Config Template Copy this to .ai-attribution.config.json and adjust patterns.

{
  "highRiskPatterns": [
    "src/domain/**/*.ts",
    "src/services/**/*.ts",
    "src/handlers/**/*.ts"
  ],
  "lowRiskPatterns": [
    "src/generated/**",
    "**/*.test.ts"
  ],
  "thresholds": {
    "maxAiDensityHighRisk": 0.40,
    "requireRationaleAboveDensity": 0.20
  }
}

Quick Start Guide

1. Install Dependencies: Add simple-git, glob, and husky to your project.

   npm install --save-dev simple-git glob husky
   

2. Initialize Husky: Set up git hooks.

   npx husky init
   

3. Add Commit Hook: Create .husky/commit-msg with the script from Section 3. Make it executable.

   chmod +x .husky/commit-msg
   

4. Run Baseline Scan: Execute the attribution reporter to establish current AI density metrics.

   npx ts-node tools/ai-attribution-reporter.ts --config .ai-attribution.config.json --output report.json
   

5. Review and Iterate: Analyze report.json to identify high-density files. Update PR templates and train the team on the Cognitive Ownership Gate.