stemedb/applications/aphoria/docs/guides/golden-path-loop.md

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.

// 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.

$ 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."

$ 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.

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

# aphoria.toml
policies = ["https://internal.acme.com/policies/acme-backend.pack"]

They try to cut corners and use insecure HTTP:

// billing-service/main.go
grpc.WithInsecure()

They run the pre-flight check (or the Agent runs it automatically):

$ 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.