stemedb/applications/aphoria/docs/guides/enterprise-pilot-guide.md

Enterprise Pilot Guide

Run a successful Aphoria pilot with measurable outcomes for stakeholders.

Who This Guide Is For

• Security Teams evaluating Aphoria for organizational adoption
• Platform Engineering considering Aphoria for developer experience
• Compliance Officers assessing audit trail capabilities

---

Pilot Goals

Define success before you start. Common pilot objectives:

Objective	Metric	Target
Find existing violations	Conflicts detected across pilot projects	>50 findings in first week
Reduce time-to-detection	Days between code merge and violation detection	<1 day (shift left)
Validate audit trail	SOC 2 auditor acceptance of Aphoria reports	Pass audit review
Developer acceptance	Post-pilot NPS from pilot team developers	>7/10

---

Phase 1: Environment Setup (Day 1)

1.1 Install Aphoria

git clone https://github.com/orchard9/stemedb.git
cd stemedb/applications/aphoria
cargo install --path .

1.2 Create Standards Repository

Dedicated repo for your organization's security standards:

mkdir acme-security-standards && cd acme-security-standards
git init

cat > aphoria.toml << 'EOF'
[project]
name = "acme-security-standards"
version = "1.0.0"

[episteme]
data_dir = ".aphoria/db"

[governance]
enabled = true
default_workflow = "standard_review"

[[governance.workflows]]
name = "standard_review"
description = "Standard pattern review for production"
overall_timeout_hours = 168

[[governance.workflows.stages]]
name = "security_review"
label = "Security Review"
required_approvers = ["security-team"]
min_approvals = 1
timeout_hours = 48

[[governance.workflows.stages]]
name = "architecture_review"
label = "Architecture Review"
required_approvers = ["arch-team"]
min_approvals = 1
EOF

aphoria init
git add . && git commit -m "Initial security standards setup"

1.3 Define Initial Standards

Start with high-value, low-controversy standards:

# TLS certificate verification (universally required)
aphoria bless "code://standard/tls/cert_verification" \
  --predicate enabled --value true \
  --reason "Certificate verification required per OWASP ASVS 9.1.1"

# TLS minimum version (clear RFC guidance)
aphoria bless "code://standard/tls/min_version" \
  --predicate version --value "1.2" \
  --reason "TLS 1.2 minimum per NIST SP 800-52 Rev 2"

# JWT audience validation (common vulnerability)
aphoria bless "code://standard/jwt/audience_validation" \
  --predicate enabled --value true \
  --reason "JWT aud claim must be validated per RFC 7519"

# Debug mode in production
aphoria bless "code://standard/debug/production" \
  --predicate enabled --value false \
  --reason "Debug mode must be disabled in production per OWASP"

1.4 Export Trust Pack

aphoria policy export \
  --name "Acme-Security-Standards-Pilot" \
  --output acme-pilot-v1.0.pack

---

Phase 2: Pilot Team Selection (Day 2-3)

Selection Criteria

Choose 2-3 teams that:

• Have active development (commits weekly)
• Mix of languages/frameworks (Python + JavaScript, for example)
• Include at least one team with known security debt
• Have supportive tech leads (early adopters)

Pilot Team Onboarding

For each pilot team:

cd pilot-project
aphoria policy import path/to/acme-pilot-v1.0.pack
aphoria scan

Initial Scan Results

Capture baseline metrics:

• Total conflicts detected
• BLOCK vs FLAG breakdown
• Top 5 conflict types

---

Phase 3: Integration (Week 1)

3.1 Pre-Commit Hooks

Add to each pilot project's .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: aphoria
        name: Aphoria security check
        entry: aphoria scan --staged --exit-code
        language: system
        pass_filenames: false

3.2 CI/CD Integration

GitHub Actions example:

name: Security Scan
on: [push, pull_request]

jobs:
  aphoria:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Aphoria
        run: cargo install aphoria

      - name: Import Security Policy
        env:
          SECURITY_PACK_URL: ${{ secrets.SECURITY_PACK_URL }}
        run: |
          curl -sL "$SECURITY_PACK_URL" -o policy.pack
          aphoria policy import policy.pack          

      - name: Run Scan
        run: aphoria scan --persist --exit-code --format sarif > results.sarif

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: results.sarif

3.3 Daily Standup Check

Run scans centrally and report trends:

#!/bin/bash
# daily-security-report.sh

for project in project-a project-b project-c; do
  cd "$project"
  echo "=== $project ==="
  aphoria scan --format json | jq '.summary'
  cd ..
done

---

Phase 4: Governance Workflows (Week 2)

4.1 Enable Governance

Update aphoria.toml in each pilot project:

[governance]
enabled = true

4.2 Pattern Promotion Flow

When Aphoria learns a new pattern from code:

# View pending approvals
aphoria governance pending

# Review a specific request
aphoria governance status --pattern <pattern-id>

# Approve (security team)
aphoria governance approve <request-id> --comment "LGTM, aligns with RFC"

# Or reject
aphoria governance reject <request-id> --reason "Conflicts with existing standard"

4.3 Audit Trail Export

For compliance review:

# Export full audit trail
aphoria audit export -o governance-audit.json -f json

# View specific pattern history
aphoria audit trail --pattern <pattern-id>

---

Phase 5: Measurement (Week 3-4)

Key Metrics

Metric	How to Measure	Target
Detection Rate	Conflicts found / week	Trending down (good)
Fix Rate	Conflicts resolved / conflicts found	>80%
False Positive Rate	ACKs that were unnecessary / total ACKs	<10%
Time to Resolution	Days from detection to fix/ack	<3 days
Developer Friction	Survey: "Did Aphoria slow you down?"	<20% "yes"

Weekly Report Template

## Aphoria Pilot Week N Report

### Summary
- Projects scanned: 3
- Total conflicts: 47 (down from 62 last week)
- New conflicts this week: 8
- Resolved this week: 23

### By Category
| Category | Count | Trend |
|----------|-------|-------|
| TLS | 12 | -5 |
| JWT | 8 | -2 |
| Debug | 3 | -1 |

### Top Issues
1. `verify=False` in API client (3 instances)
2. JWT validation disabled in dev config (leaked to prod)
3. TLS 1.0 still accepted in legacy service

### Developer Feedback
- "Caught a real bug before it shipped" - Team A
- "Pre-commit hook is fast" - Team B
- "Would like more context on why this is a conflict" - Team C

---

Phase 6: Remediation Tracking

Track Fix Progress

# Set current scan as baseline
aphoria baseline

# After fixes, show changes
aphoria diff

Remediation Workflow

1. Triage: Daily standup reviews new conflicts
2. Assign: Security team assigns to owning team
3. Fix or ACK: Dev team has 3 days to resolve or acknowledge
4. Verify: Next scan confirms resolution

Escalation Path

Day 0: Conflict detected
Day 3: Reminder to owning team
Day 7: Escalate to security team
Day 14: Escalate to engineering leadership

---

Phase 7: SOC 2 Validation

Auditor Evidence Package

Generate for your SOC 2 auditor:

# Full audit trail export
aphoria audit export -o soc2-evidence/governance-trail.json -f json

# Convert to CSV for spreadsheet review
aphoria audit export -o soc2-evidence/governance-trail.csv -f csv

# Policy snapshot
aphoria policy export --name "Audit-Snapshot-$(date +%Y%m%d)" \
  --output soc2-evidence/policy-snapshot.pack

Evidence Contents

The export includes:

• All approval requests with timestamps
• Approver identities and decisions
• Comments and reasons
• Pattern promotion history
• Exception acknowledgments with justifications

Auditor Presentation

Key points for your auditor:

1. Continuous enforcement - Scans run on every commit
2. Cryptographic attribution - Every conflict traces to specific policy
3. Approval workflow - Multi-stage review before pattern promotion
4. Immutable audit log - Append-only, JSONL format

---

Go/No-Go Decision

Success Criteria

Mark as GO if:

• Detection rate > 50 findings in pilot period
• Fix rate > 80%
• False positive rate < 10%
• Developer NPS > 7/10
• SOC 2 auditor accepted evidence format
• No blocking performance issues

Rollout Phases

1. Pilot Complete: 2-3 teams, 4 weeks
2. Early Adopter: 10 teams, 8 weeks
3. General Availability: All teams, ongoing

---

Common Pilot Issues

"Too many false positives"

Tune sensitivity:

# Use strict mode for high-confidence only
aphoria scan --strict

Or acknowledge legitimately different patterns:

aphoria ack "code://..." --reason "Legacy system, tracked in JIRA-1234"

"Scans are too slow"

Use ephemeral mode for quick checks:

aphoria scan  # Fast, no persistence

Only use --persist for baseline comparisons.

"Developers don't understand conflicts"

Enable debug output for education:

aphoria scan --debug

Shows full conflict resolution trace.

"Standards need updating"

Update your Trust Pack and redistribute:

# In standards repo
aphoria bless "code://standard/new/pattern" ...
aphoria policy export --name "Acme-v1.1" --output acme-v1.1.pack

# In each project
aphoria policy import acme-v1.1.pack

---

Next Steps

After successful pilot:

1. Multi-Team Policy Governance - Scale to multiple teams
2. Policy Audit Trails - Compliance workflows
3. Federating Truth - Cross-organization standards