Files
archie/docs/architecture/policy.md
T
sam fd4420a038 docs(architecture): record decisions recovered from the pre-migration tracker
Eight approved decisions existed only as beads memories and were lost when
the tracker was removed. Recovered from a backup taken six minutes before
8bf0f6b and folded into the docs that own them, rather than a new document.

- migration-decisions: recorded position as of 2026-07-29, the deferred
  private-input-DTO compromise, and the agreed internal/app/{archied,
  agentworker} next step
- configuration: missing credential degrades a capability, only invalid
  config is fatal; config generation moves from install.sh to archied setup
- identity: the three-layer invariants/SOUL/representation model, and why
  a curator may only propose SOUL changes
- agent-system: the curator isolation invariant (curators are peers, never
  on a chat turn's critical path)
- messaging-and-work-intake: semantic search over messages is an explicit
  non-goal, with the measurements behind it
- safe-change-and-recovery: the /restart deadlock and lockout constraints
- plugins-and-extensions: dates the surprisal deferral

Also replaces the dead `**Beads issue:** archie-core-5d7` frontmatter across
all 12 documents with the GitHub issue it migrated to (#73), and rewrites
every other beads identifier to its issue number.
2026-08-09 18:10:12 +10:00

1.8 KiB

Policy System

Status: Approved foundation; exact API is deferred
Date: 2026-07-28
Tracking issue: #73

Purpose

Retry limits, authorization, gates, commands, protected paths, tool availability, and similar rules define or constrain what Archie may do. They need consistent consumption, composition, evidence, and audit without erasing their different domain meanings.

Ownership

internal/policy is an explicitly approved shared application contract. It is not infrastructure and it is not a generic domain that owns every rule.

The shared policy system owns:

  • policy identity, version, scope, and applicability;
  • typed evaluation invocation;
  • deterministic composition and precedence;
  • common evaluation states such as satisfied, violated, indeterminate, and not applicable;
  • reasons and evidence;
  • evaluation audit records;
  • registration, discovery, and lifecycle.

Each consuming domain owns:

  • its policy vocabulary and typed inputs;
  • its concrete policy definitions;
  • its evaluators;
  • the meaning and consequence of an evaluation.

Access therefore owns principals, resources, actions, and authorization consequences. Task lifecycle owns retry eligibility and exhaustion. Task execution owns gate requirements. Workspace mutation owns protected-path effects. Tool execution owns tool and command constraints.

These policies use consistent evaluation mechanics without pretending their decisions are semantically interchangeable.

Infrastructure

Infrastructure MAY load, persist, distribute, and audit external policy representations. It MUST NOT define what Archie allows or assign the meaning of a domain policy result.

The exact Go API, composition operators, precedence rules, and representation format require a focused policy design pass.