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

```bash
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:

```bash
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:

```bash
# 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

```bash
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:

```bash
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`:

```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:

```yaml
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:

```bash
#!/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:

```toml
[governance]
enabled = true
```

### 4.2 Pattern Promotion Flow

When Aphoria learns a new pattern from code:

```bash
# 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:

```bash
# 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

```markdown
## 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

```bash
# 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:

```bash
# 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:
```bash
# Use strict mode for high-confidence only
aphoria scan --strict
```

Or acknowledge legitimately different patterns:
```bash
aphoria ack "code://..." --reason "Legacy system, tracked in JIRA-1234"
```

### "Scans are too slow"

Use ephemeral mode for quick checks:
```bash
aphoria scan  # Fast, no persistence
```

Only use `--persist` for baseline comparisons.

### "Developers don't understand conflicts"

Enable debug output for education:
```bash
aphoria scan --debug
```

Shows full conflict resolution trace.

### "Standards need updating"

Update your Trust Pack and redistribute:
```bash
# 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](./multi-team-policy-governance.md) - Scale to multiple teams
2. [Policy Audit Trails](./policy-audit-trails.md) - Compliance workflows
3. [Federating Truth](./federating-truth.md) - Cross-organization standards