01 — What ARG Is and Why It Exists

01 — What ARG Is and Why It Exists

The problem

Brian (the agent) had grown organically across many sessions. Knowledge of "what accounts exist," "where credentials live," "what services are reachable," "what can I publish to," and "what must I never do" was scattered across:

• MEMORY.md and 200+ atomic theme files (hand-written, prone to drift)
• /opt/agent/data/CC_skills.md, OC_skills.md, capabilities.md (curated lists, no live state)
• Inline .env env vars (no metadata about scope, owner, expiry, renewal procedure)
• system-changelog.sh log entries (chronological, not queryable)
• Hard rules embedded in PreToolUse hooks (code-as-truth, hard to introspect)
• Ad-hoc scripts that knew things ("probe this URL", "send to that bot") with no shared registry

Symptoms:
- Capabilities Brian had but didn't know he had → "I can't do X" when X was already wired.
- Capabilities Brian thought he had but didn't → tool calls failing at runtime instead of plan time.
- Boundary violations slipping past: $41.68 paid-LLM leak (2026-04-30) because the rule existed in MEMORY.md but no runtime gate enforced it.
- New sub-agents reinventing existing access paths instead of resolving against a registry.

The thesis

A single living layer that knows:

1. Atoms — every account, key, host, data store, product, channel, subsystem, sub-agent in one place.
2. Access — which entity grants which permission to which other entity.
3. Capabilities — composed actions, declared as (deps × side_effects × risk × cost × idempotency × policy).
4. Boundaries — negative space, hard rules with hook enforcement.
5. Health — every atom probed on a cadence; live state always retrievable.
6. Observability — append-only event journal, sub-agent proposal inbox.

The data is JSON files on disk. A Python CLI (arg) is the only way to read or modify the registry. A PreToolUse hook reads the boundaries file at runtime to gate tool calls.

Design principles

What ARG is NOT

• Not a feature flag system. Capabilities aren't feature flags; they're "can I do this RIGHT NOW given current creds and policy."
• Not a secrets store. Keys reference where the value lives (env var, file, container env), not the value itself.
• Not a deployment tool. It describes state; it doesn't reconcile to it (autofix is a thin layer on top, not a Kubernetes-style controller).
• Not a permissions system for end-users. Brian is the only consumer. The "policy" layer is Brian's own self-imposed guardrails.

Why JSON, not a database

Three reasons:

1. Git-friendly. Every change is a diff; rollback is a checkout.
2. No process required. No daemon to keep running, no schema migrations, no connection pool.
3. Human-readable under failure. When everything else is broken, you can cat resources/accounts.json | jq '.rows[]' and see the truth.

Cost: no transactions across files, no secondary indexes. Acceptable at the scale of one agent's self-knowledge (~3,000 rows total across all files).

How ARG relates to other Brian systems

Origin

Phase 1 (skeleton + seed): 2026-05-02 morning. Phase 2 (registry + probes + resolver + journal + inbox + hook + discovery): 2026-05-02 evening. Phase 2.5 / 2.6 (audit fixes + smoke-test bug-fix wave): 2026-05-02 → 03 overnight. Phase 5 items 3/4/7 (jsonschema + bypass-hardening + invariants): same overnight.