# 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**.