1cc453c97b
- Add PolicySourceStore for tracking where policies come from - Implement claim extraction skill and API endpoints - Add community UI text selection extractor component - Create Go SDK aphoria client for policy operations - Document patent specifications and legal disclosures - Add guides: golden path loop, policy audit trails, pre-flight checks - Expand Unreal Engine config extractor with source tracking - Add UAT reports for policy source tracking validation - Refactor tests.rs into modular test files Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
125 lines
3.7 KiB
Markdown
125 lines
3.7 KiB
Markdown
# Guide: The "Golden Path" Loop — Automating Architectural Standards
|
|
|
|
**Target Audience:** Staff Engineers, Platform Leads
|
|
**Goal:** Turn "Best Practices" from a wiki page into an automated, enforceable, distributed guardrail in < 5 minutes.
|
|
|
|
---
|
|
|
|
## The Problem: The "Lost Memo"
|
|
|
|
You, the Staff Engineer, spend a week designing the perfect Authentication pattern for your company.
|
|
* It uses gRPC.
|
|
* It handles retries correctly.
|
|
* It propagates trace contexts.
|
|
|
|
You write a Confluence page: *"How to do Auth (v2)."* You announce it in Slack.
|
|
|
|
**Six months later:**
|
|
* New hires are copying the old v1 pattern from existing repos.
|
|
* Contractors are hardcoding HTTP calls.
|
|
* Your "Standard" exists only in your head and a stale wiki.
|
|
|
|
You need a way to say: **"I built it right *here*. Make everyone else do it *this way*.**"
|
|
|
|
---
|
|
|
|
## The Solution: The Aphoria Loop
|
|
|
|
This guide walks you through the "Golden Path" loop:
|
|
1. **Codify:** Point Aphoria at your "perfect" implementation.
|
|
2. **Bless:** Acknowledge the patterns as the new Standard.
|
|
3. **Distribute:** Export a Trust Pack.
|
|
4. **Enforce:** Agents and CI pipelines pick it up instantly.
|
|
|
|
---
|
|
|
|
## Step 1: The Reference Implementation
|
|
|
|
You have a repo `auth-service-v2` where you did everything right.
|
|
|
|
```go
|
|
// auth-service-v2/client.go
|
|
func NewClient() {
|
|
// Correct: gRPC with mTLS
|
|
opts := []grpc.DialOption{
|
|
grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig)),
|
|
}
|
|
}
|
|
```
|
|
|
|
Run Aphoria to see what "Truths" it extracts from this code.
|
|
|
|
```bash
|
|
$ cd auth-service-v2
|
|
$ aphoria scan .
|
|
```
|
|
|
|
*Result:* Aphoria sees `code://go/grpc/tls = enabled`.
|
|
|
|
## Step 2: Bless the Pattern
|
|
|
|
This is the moment you turn code into policy. You aren't just saying "this code passes"; you are saying **"This code defines the Standard."**
|
|
|
|
```bash
|
|
$ aphoria ack "code://go/grpc/tls" \
|
|
--reason "Standard: All internal services MUST use mTLS gRPC."
|
|
```
|
|
|
|
You have now created a signed assertion in your local database:
|
|
* **Subject:** `code://go/grpc/tls`
|
|
* **Predicate:** `enabled`
|
|
* **Object:** `true`
|
|
* **Authority:** You (Tier 3 Expert)
|
|
|
|
## Step 3: Distribute the Policy
|
|
|
|
You don't want this policy stuck on your laptop. You want it in the registry.
|
|
|
|
```bash
|
|
$ aphoria policy export --name "Acme Backend Standard" --output acme-backend.pack
|
|
```
|
|
|
|
Upload this `.pack` file to your internal policy URL:
|
|
`https://internal.acme.com/policies/acme-backend.pack`
|
|
|
|
## Step 4: The Agent Feedback Loop (Immediate Enforcement)
|
|
|
|
Now, a junior developer (or an AI Agent) starts a new project `billing-service`.
|
|
|
|
They configured their project to use your standard:
|
|
```toml
|
|
# aphoria.toml
|
|
policies = ["https://internal.acme.com/policies/acme-backend.pack"]
|
|
```
|
|
|
|
They try to cut corners and use insecure HTTP:
|
|
```go
|
|
// billing-service/main.go
|
|
grpc.WithInsecure()
|
|
```
|
|
|
|
They run the pre-flight check (or the Agent runs it automatically):
|
|
|
|
```bash
|
|
$ aphoria scan
|
|
```
|
|
|
|
**The Result:**
|
|
```
|
|
BLOCK code://go/grpc/tls
|
|
Your code: insecure (main.go:12)
|
|
Standard: mTLS Required
|
|
Source: Acme Backend Standard (signed by @staff-eng)
|
|
Conflict: 0.95
|
|
```
|
|
|
|
The feedback is instant. The developer sees: *"I am violating the Acme Backend Standard."*
|
|
|
|
## Why This Wins
|
|
|
|
1. **No New Syntax:** You didn't learn Rego (OPA) or write a custom linter plugin. You just wrote **Code** and said "This is right."
|
|
2. **Provenance:** The error message doesn't say "Computer says no." It says *"Source: Acme Backend Standard."* It links the rejection to your authority.
|
|
3. **Speed:** You went from "I fixed it in one repo" to "Everyone is blocked from doing it wrong" in the time it took to run `export` and `upload`.
|
|
|
|
This turns your Reference Implementation into a **Living Standard**.
|