AEGIS Dogfooding Guide

How AEGIS governance is wired into Undercurrent engineering workflows.

Status: Phase 2 (Shadow Mode) active on aegis-governance CI. Phase 3 (undercurrent-core) ready for activation. Phase 4 (Enforcement) pending calibration data.

Architecture Overview

AEGIS has 6 integration channels. Dogfooding uses three of them:

Developer writes code
        |
        v
Claude Code session (MCP tools available)
        |
        |-- /aegis-evaluate (slash command, interactive)
        |
        v
Push to branch -> Open PR
        |
        v
CI Pipeline runs quality gates (lint, type, security, test)
        |
        v
AEGIS Shadow Evaluation (after CI success)
        |
        |-- Classifies change type (docs/config/deps/code/infra)
        |-- Derives AEGIS parameters from diff stats
        |-- Calls pcw_decide() in shadow mode
        |-- Writes decision to GitHub Actions step summary
        |
        v
PR Summary: "AEGIS Shadow Evaluation: PROCEED (confidence: 0.95)"

For AI Agents (Claude Code, Codex)

MCP Tools Available

When working in any Undercurrent repo, you have 7 AEGIS MCP tools:

Recommended Flow

1. Call aegis_get_scoring_guide(domain="cicd") to understand parameter derivation
2. Analyze the changes (files, modules, change type)
3. Derive parameters using the CI/CD domain mapping (see below)
4. Call aegis_evaluate_proposal with shadow_mode=true
5. Report the per-gate breakdown to the user

Parameter Derivation (CI/CD Domain)

Novelty by change type:

Estimated impact by file count:

Key Gotchas for Agents

1. complexity_score is inverted: HIGHER means SIMPLER. A complex 50-file refactor gets ~0.5 (barely passing the floor)
2. novelty gate passes for HIGH novelty: G(0.85) = 0.82 >= 0.6. Routine changes (low novelty) fail this gate by design
3. Utility requires synthesis: The SDK path needs explicit utility synthesis (the MCP server does this automatically). The shadow script handles this
4. Shadow mode always exits 0: Never blocks the pipeline. The decision is advisory only
5. The /aegis-evaluate slash command does all the derivation work for you

For Humans

What You'll See on PRs

After all CI gates pass, the AEGIS Shadow Evaluation job runs and adds a summary to the GitHub Actions page:

### AEGIS Shadow Evaluation

Decision: PROCEED (confidence: 0.95)
Change type: code | Files: 8

| Gate       | Result | Value  | Threshold | Message              |
|------------|--------|--------|-----------|----------------------|
| risk       | PASS   | 1.6    | 2.0       | P(delta>=2.0) = 0.03 |
| profit     | PASS   | 0.0    | 2.0       | P(|delta|>=2.0) = 0  |
| novelty    | PASS   | 0.82   | 0.6       | G(N=0.85) = 0.82     |
| complexity | PASS   | 0.76   | 0.5       | Met                  |
| quality    | PASS   | 0.85   | 0.7       | Passed               |
| utility    | PASS   | 0.001  | 0.0       | LCB=0.00             |

Shadow mode: advisory only, does not block the pipeline.

Decision Meanings

Phase Transition: Shadow to Enforcement

After collecting ~20 PRs of shadow data:

1. Review the shadow decisions — at least 50% of non-docs PRs should get PROCEED
2. If < 30% get PROCEED, adjust the novelty derivation or threshold (ask-first trigger)
3. To activate enforcement, modify tools/ci/aegis_shadow_evaluate.py:
   • Change shadow_mode=True to shadow_mode=False
   • Add exit code logic: exit 1 only on HALT decisions
4. Add continue-on-error: true for one week buffer
5. Remove continue-on-error after confirming no false positives

Local Testing

Run the shadow evaluation locally to see what it would report:

cd Projects/aegis-governance
python tools/ci/aegis_shadow_evaluate.py

This analyzes your current branch diff against HEAD~1 and prints the decision to stdout.

Infrastructure

API Keys

MCP Server Configuration

The MCP server is configured in .claude/settings.json at each repo root:

{
  "mcpServers": {
    "aegis": {
      "command": "/Users/joshuakirby/.pyenv/versions/3.12.11/bin/aegis-mcp-server",
      "args": []
    }
  }
}

Note: The path is machine-specific. If the pyenv version changes, update these files:

• Undercurrent-Holdings/.claude/settings.json
• undercurrent-core/.claude/settings.json

Files Reference

Calibration Targets

After ~20 PRs of shadow data, review these metrics:

Onboard a New Repository

This section is a cookbook for adding AEGIS governance to a repository that doesn't have it yet. Pick one or more integration paths below.

Decision Tree

Recommendation: Start with A + B for internal Python repos. Use C for non-Python or external repos.

Path A: MCP Server Setup

1. Verify aegis-mcp-server is on PATH:

   which aegis-mcp-server

   If missing, install from a licensed source checkout:

   git clone <your-aegis-repo>
   cd aegis-governance
   pip install -e ".[mcp]"

2. Add .claude/settings.json to the repo root:

   {
     "mcpServers": {
       "aegis": {
         "command": "aegis-mcp-server",
         "args": []
       }
     }
   }

   pyenv note: If Claude Code can't find aegis-mcp-server, use the full path from which aegis-mcp-server. The path is machine-specific and will break on pyenv version changes — prefer keeping aegis-mcp-server on a stable PATH.

3. Restart Claude Code (or start a new session).

4. Verify: run the aegis_check_thresholds MCP tool — it should return all 6 gates.

Path B: CI Shadow Job (aegis-governance repo)

This path uses the shadow evaluation script that ships with aegis-governance. It requires the AEGIS source (BSL-1.1 licensed) — the script imports integration.pcw_decide at runtime.

For repos that do not have AEGIS source access, use Path C (REST API) or Path D (GitHub Action) instead.

The aegis-shadow job in .github/workflows/python-ci.yml is the reference implementation:

  aegis-shadow:
    name: AEGIS Shadow Evaluation
    needs: [ci-success]  # run after all quality gates pass
    if: needs.ci-success.result == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2  # needed for HEAD~1 diff

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install AEGIS from source
        run: pip install -e ".[engine]"

      - name: Run AEGIS shadow evaluation
        env:
          PR_TITLE: ${{ github.event.pull_request.title || '' }}
        run: python tools/ci/aegis_shadow_evaluate.py

To add this to another internal repo with AEGIS source access:

1. Copy tools/ci/aegis_shadow_evaluate.py into the target repo.

2. Add a CI step that checks out aegis-governance and installs it:

         - uses: actions/checkout@v4
           with:
             repository: undercurrentai/aegis-governance
             path: aegis-governance
             token: ${{ secrets.GH_PAT }}  # private repo access
   
         - name: Install AEGIS
           run: pip install -e "./aegis-governance[engine]"

3. Add 'tools/ci/**' to your PR trigger paths so changes to the script trigger CI.

4. Push a test PR and verify the AEGIS summary appears in Actions.

Adaptation notes:

• The shadow script auto-classifies changes (docs/config/deps/code/infra) using file extensions and directory prefixes — works for any language.
• For non-src/ layouts: the script uses _CODE_DIRS and _CODE_EXTENSIONS sets. Fork the script if your code lives in a custom directory not already covered (lib/, app/, etc. are already included).
• Parameter derivation uses CI/CD domain defaults. For trading, moderation, or agent domains, see docs/integration/domain-templates.md.

Path C: REST API (Any Language)

1. Get an API key: sign up at portal.undercurrentholdings.com or request internal provisioning from the AEGIS team.

2. Store as GitHub Secret: AEGIS_API_KEY

3. Add a CI step that calls the REST API:

         - name: AEGIS shadow evaluation
           env:
             AEGIS_API_KEY: ${{ secrets.AEGIS_API_KEY }}
             PR_TITLE: ${{ github.event.pull_request.title || 'manual run' }}
           run: |
             PAYLOAD=$(python3 -c "
             import json, os
             print(json.dumps({
               'proposal_summary': os.environ['PR_TITLE'],
               'estimated_impact': 'medium',
               'risk_proposed': 0.1,
               'risk_baseline': 0.02,
               'profit_proposed': 0.98,
               'profit_baseline': 0.98,
               'novelty_score': 0.85,
               'complexity_score': 0.7,
               'quality_score': 0.85,
               'shadow_mode': True
             }))
             ")
             RESULT=$(curl -sf -X POST \
               https://aegis-api-980022636831.us-central1.run.app/evaluate \
               -H "Authorization: Bearer $AEGIS_API_KEY" \
               -H "Content-Type: application/json" \
               -d "$PAYLOAD")
             echo "### AEGIS Shadow Evaluation" >> $GITHUB_STEP_SUMMARY
             echo '```json' >> $GITHUB_STEP_SUMMARY
             echo "$RESULT" | python3 -m json.tool >> $GITHUB_STEP_SUMMARY
             echo '```' >> $GITHUB_STEP_SUMMARY

   For dynamic parameter derivation (like the shadow script does), compute file counts and types yourself. The REST API evaluates whatever parameters you send.

Path D: Reusable GitHub Action (Lambda-Backed)

For repos with AWS OIDC access to the AEGIS Lambda:

      - uses: undercurrentai/aegis-governance/.github/actions/aegis-gate@main
        with:
          proposal_summary: ${{ github.event.pull_request.title }}
          estimated_impact: "medium"
          risk_score: "0.1"
          complexity_score: "0.7"
          aws_role_arn: ${{ secrets.AEGIS_GATE_ROLE_ARN }}
          customer_id: "cust_your_id_here"

Outputs available to subsequent steps: status, confidence, rationale, decision_json.

Set fail_on_halt: 'false' for shadow mode (default is 'true' which blocks on HALT).

API Key Management

Internal dogfood customer ID: cust_6dc3a2ddedb6 — for Undercurrent repos, use this for usage aggregation.

Onboarding Checklist

• Choose integration path (A: MCP, B: CI Shadow, C: REST, D: GitHub Action)
• MCP (if Path A): .claude/settings.json added, aegis_check_thresholds returns 6 gates
• CI Shadow (if Path B): AEGIS source checkout in CI, aegis-shadow job added, test PR shows summary
• REST API (if Path C): API key in GitHub Secrets, health check passes, test evaluation returns decision
• GitHub Action (if Path D): AEGIS_API_KEY secret configured, action runs, outputs available
• First PR evaluated: Shadow decision visible in GitHub Actions summary
• Calibration started: Tracking PROCEED rate on first 20 non-docs PRs