Skip to main content

GOV 11 AGENT LEGIBILITY AND IN-REPO TRUTH

This page embeds the canonical rule text and adds commentary after each section to explain why the section exists.

Governance: Agent Legibility and In-Repo Truth​

If durable operating knowledge is not discoverable in repository artifacts, it is not reliable system knowledge.

Governed systems should optimize for agent legibility by making intent, constraints, invariants, and prior decisions discoverable in versioned repo truth.

Commentary: Makes discoverable repo truth the default memory model for repeatable agent execution.

Core Principle​

  • GOV-11-LEG-001 Governed repositories should treat repo-local, versioned artifacts as the primary operating memory for agents.
  • GOV-11-LEG-002 Durable decisions, constraints, invariants, and execution norms should be promoted into repository truth instead of remaining trapped in chat, review comments, or private human memory.
  • GOV-11-LEG-003 Agents should prefer discoverable repo truth over transcript archaeology or informal conversational recall when both exist.

Commentary: Establishes where trustworthy knowledge should live and what should take precedence.

Reliable Knowledge Rules​

  • GOV-11-LEG-004 If an instruction or decision is important enough to affect future work repeatedly, it should be encoded into a durable repo artifact.
  • GOV-11-LEG-005 Acceptable durable artifacts include governance rules, architecture docs, project intent docs, feature specs, execution plans, reference docs, templates, tests, and lint/config enforcement.
  • GOV-11-LEG-006 Knowledge that exists only in transient chat history should be treated as fragile until promoted.
  • GOV-11-LEG-007 Agents should not assume hidden human context, unwritten team norms, or remembered chat context will still be available on the next run.

Commentary: Turns “we talked about this before” into explicit promotion duties.

Promotion Expectations​

  • GOV-11-LEG-008 Repeated human corrections should trigger promotion into durable repo truth when they describe reusable behavior rather than one-off preference.
  • GOV-11-LEG-009 Durable promotion should happen at the narrowest authoritative layer that fits the fact, for example spec, project doc, governance rule, reference doc, test, or lint rule.
  • GOV-11-LEG-010 When promotion does not happen immediately, the missing promotion path should be tracked explicitly rather than assumed away.

Commentary: Ensures feedback compounds into system memory instead of resetting each run.

Discoverability Expectations​

  • GOV-11-LEG-011 Important repository knowledge should be organized so a future agent can find it without reading the full repository or relying on external narration.
  • GOV-11-LEG-012 Entry-point files should act as maps to deeper source-of-truth artifacts rather than attempting to be giant manuals.
  • GOV-11-LEG-013 Knowledge architecture should support progressive disclosure: brief entry points, structured deeper docs, and stable canonical locations.
  • GOV-11-LEG-014 When durable knowledge moves, links and references should be updated so discoverability does not silently degrade.

Commentary: Keeps knowledge legible at scale instead of collapsing into one stale instruction blob.

Enforcement Orientation​

  • GOV-11-LEG-015 When a repeated rule or invariant is mechanically enforceable, governed systems should prefer enforcing it through code, tests, or linting over relying only on prose reminders.
  • GOV-11-LEG-016 Human review should be treated as a source of new invariants to encode, not only as a one-time correction channel.

Commentary: Pushes repeatable human taste from comments into enforceable controls.

Legible Execution and Bounded Autonomy​

  • GOV-11-LEG-017 High-agency execution profiles should optimize for interrupt-efficient legibility: enough visible state for an operator to understand progress, risk, and decision boundaries without forcing the agent into constant narration.
  • GOV-11-LEG-018 Meaningful execution checkpoints should surface start or resume, major plan change, blocker or risk state, validation outcome, and closure outcome when those states occur.
  • GOV-11-LEG-019 Agents should act autonomously on clear, reversible internal work, but decision boundaries must remain visible for destructive, external, privacy-sensitive, irreversible, or judgment-dependent actions.
  • GOV-11-LEG-020 Silence is not inherently better than chatter. The governed target is concise, high-signal visibility rather than either status spam or opaque black-box execution.
  • GOV-11-LEG-021 Throughput-oriented prompting or harness design must not suppress the visibility needed for accountability, recoverability, or safe interruption.

Commentary: Converts "talk less" into a governed rule about showing the right state at the right time instead of choosing between noise and opacity.

Anti-Patterns​

Avoid these failure modes:

  • relying on chat logs as the main system of record
  • leaving architectural decisions only in pull request discussion
  • expecting future agents to infer unwritten norms from scattered examples
  • storing critical intent in one giant unstructured instruction file
  • keeping durable rules in people’s heads instead of repo artifacts
  • treating silence as superior to operator-legible checkpoints
  • optimizing throughput by hiding meaningful risk, validation, or decision-boundary state
  • applying high autonomy to destructive or externally consequential actions without making the decision boundary visible

Commentary: Calls out the exact hidden-knowledge and hidden-state patterns that break agent reliability.