Decision Governance for Coding Agents

What is decision governance for coding agents?

Decision governance for coding agents is a control system for carrying engineering authority from the moment a team makes a choice to the moment an agent-authored change is reviewed and merged. The system records the choice and its rationale, determines whether it applies to the work in front of the agent, delivers that authority before the affected code is designed, and checks the consequences that can be established objectively.

The important word is governance. A repository can contain excellent documentation and still leave an agent guessing. Governance requires an explicit owner, a current lifecycle state, a defined scope and observable evidence that the relevant record reached the task. It also requires honest boundaries: a passing dependency rule can prove that a forbidden import is absent, but it cannot prove that an interface is calm, maintainable or appropriate for every user.

This makes decision governance narrower than general AI governance and more operational than an ADR archive. It governs technical choices inside a software-delivery workflow. Model selection, data handling, permissions and deployment approval remain important adjacent controls, but they answer different questions.

Why permissions are not decision governance

Coding-agent controls are often framed around capability: whether an agent may write files, run commands, access a network, open a pull request or deploy software. Those boundaries reduce operational risk. They do not tell the agent that desktop state belongs in SQLite, that domain code must not import infrastructure, or that conflicting synchronisation updates require explicit user resolution.

A sandbox can prevent an agent from touching production while still allowing it to make the wrong architectural choice inside the repository. A review gate can require human approval while giving the reviewer no visible record of the prior decision. A longer prompt can remind the model of a rule while omitting why the rule exists, which paths it governs and whether it was superseded yesterday.

Permission governance therefore answers what the agent is allowed to do. Decision governance answers which human-approved technical choices govern the change, why they govern it and how compliance will be evaluated. Mature agent workflows need both, with neither presented as a substitute for the other.

The control loop: record, route and enforce

The practical model has three layers. Record preserves authority. Route delivers applicable authority into the task. Enforce evaluates the subset of consequences that can be proved. Each layer has a separate failure mode, so collapsing them into one document creates ambiguity about what the system actually guarantees.

Without recording, important choices decay into memory, code archaeology and repeated debate. Without routing, the repository may contain the right decision while the agent never sees it. Without enforcement, objective rules remain review suggestions that can be overlooked under delivery pressure. Without human judgement, qualitative concerns are either ignored or misrepresented as machine-verifiable facts.

• Record: a reviewed decision with stable identity, status, context, scope, consequences and ownership.
• Route: a reproducible match between the task or changed paths and the live records that govern them.
• Enforce: a deterministic check linked to a specific, objectively testable consequence.
• Review: named human judgement for conflicts, exceptions and consequences that cannot be reduced safely to a boolean rule.

Layer 1: record authority, not every conversation

A decision record should preserve choices whose loss would cause costly rework, an unsafe change, an incompatible interface or a recurring argument. It should not attempt to store every implementation observation or every token of a design conversation. The durable unit is the accepted choice together with enough context to understand its boundary and reconsider it responsibly.

At minimum, record a stable ID, status, context, decision, consequences, owner and scope. Add rejected alternatives when they are plausible enough to return later. Add review triggers so a team can distinguish a durable constraint from an assumption that should be revisited when scale, regulation or product behaviour changes. When a decision is replaced, preserve history and connect the new record through an explicit supersession relationship.

Keep prose for human reasoning and structure for machine use. A coding agent benefits from the explanation, but a router cannot reliably infer lifecycle and applicability from prose alone. Machine-readable fields should make the boundary explicit without turning the record into an opaque policy object.

# DEC-014: Use SQLite for desktop workspace state

## Status
Accepted

## Context
Desktop workspaces must remain available without a network connection.
State is local to one user and does not require multi-host writes.

## Decision
Use SQLite for persistent desktop workspace state.

## Applies To
- apps/desktop/**
- packages/local-store/**

## Consequences
Do not add another database client in the governed paths.
Hosted service persistence is outside this decision.

## Revisit When
- workspaces require concurrent multi-user writes
- state must be shared across devices in real time

Layer 2: route only the decisions that apply

Routing turns a decision library into task context. Before implementation, inspect the proposed change surface: repositories, packages, files, capabilities and interfaces. Resolve that surface against accepted decisions with declared scope, then give the agent a focused brief containing the matched records and the evidence for each match. A database decision for a desktop package should not appear merely because a server task also contains the word persistence.

Path scope is especially useful because it is deterministic and visible in a diff. Capability and topic signals help before exact files are known or when a concern crosses directories. The resolver should preserve both kinds of evidence and should not hide conflicts. If two live records claim the same boundary incompatibly, return the conflict for human resolution instead of allowing semantic similarity or file proximity to choose authority silently.

Run routing twice. The planning pass constrains design before code is written. The final-diff pass catches files and boundaries introduced during implementation. A routing result should include stable IDs, source paths or URLs, lifecycle state and the scope entries that matched so an agent or reviewer can challenge a mistaken result.

task:
  intended_paths:
    - apps/desktop/src/storage/workspace.ts
    - services/sync/src/push.ts
    - packages/protocol/src/workspace.ts

applicable_decisions:
  - id: DEC-014
    reason: apps/desktop/** matched desktop persistence scope
  - id: DEC-027
    reason: services/sync/** matched offline-first synchronisation scope
  - id: DEC-031
    reason: packages/protocol/** matched conflict handling scope

Layer 3: enforce only what can be proved

Some consequences translate cleanly into executable checks. A repository can test forbidden imports, dependency direction, schema compatibility, approved licenses, configuration values, migration reversibility or the presence of required tests. The check should name its governing decision, exact scope, evidence and remediation so a failure explains the architecture rather than producing an unexplained red build.

Other consequences require judgement. A calm operational interface, an understandable conflict-resolution experience or an appropriate service boundary cannot be proved reliably by a generic model score. Keep those decisions visible in the brief and require review by the named owner. Labelling judgement as advisory is not a weakness; it prevents a weak automated proxy from becoming false assurance.

AsDecided separates record validation from code enforcement. The gate can validate the decision corpus, while code-aware checks evaluate explicit constraints against changed or full-tree source. The authoritative product documentation defines the supported commands and exit contracts; the decision record explains why the linked rule exists.

# Validate the decision record and relationships.
decided gate decisions/

# Include scoped code constraints for the pull-request diff.
decided gate decisions/ --code --base origin/main

# Run the code-enforcement surface directly when needed.
decided sentry decisions/ --base origin/main

Where AGENTS.md belongs

AGENTS.md belongs at the operating layer. It can explain repository structure, authoritative commands, generated-file boundaries, review expectations and the steps an agent must follow before claiming completion. Nested instruction files can narrow those working rules for a package or directory. This is valuable persistent context.

The file should point to the decision workflow rather than absorb the complete decision history. Copying every architecture choice into one instruction file creates stale duplicates, sends irrelevant context to unrelated tasks and removes the lifecycle relationships that distinguish an accepted decision from a superseded one. Keep the instruction concise: retrieve applicable decisions before planning, cite them in the change, route the final diff and run the required checks.

# Agent instructions

## Before implementation
- List the paths this task is likely to change.
- Retrieve the accepted decisions that govern those paths.
- Cite each applicable decision in the implementation plan.
- Stop for review if current decisions conflict.

## Before completion
- Re-run decision routing against the final diff.
- Run decided gate decisions/ --code --base origin/main.
- Report unresolved guidance, exceptions and failed checks.

Manage lifecycle, supersession and conflict

A decision system must distinguish current authority from history. Proposed records can inform a discussion but should not govern code by default. Accepted records are live. Superseded and deprecated records remain useful evidence, yet retrieval must not present them as current merely because their wording matches a task closely.

Supersession should be additive and traceable. Create or accept the replacement, connect it to the prior record, and preserve the old rationale in version control. A router can then return the current record while allowing a reviewer to follow the lineage. Quietly rewriting an old ADR destroys the explanation of why the system changed and makes earlier code reviews harder to reconstruct.

Conflicts need an explicit precedence rule and a human resolution path. A narrower repository decision does not automatically override an organisation-wide security rule. A later timestamp does not automatically make a proposal authoritative. When two live records cannot both be satisfied, block the claim of readiness and ask the owners to supersede, clarify scope or approve a bounded exception.

Make exceptions explicit and expiring

Delivery sometimes requires a controlled deviation from a current decision. The safe response is not to edit the check until it passes or leave a comment that future teams will miss. Record an exception with the governing decision, exact repository and path scope, reason, owner, approver, compensating controls and expiry date.

An exception narrows the default for a known period; it does not erase the default. Retrieval should show both records. CI should apply the exception only where its scope matches and should surface expiry before the workaround becomes permanent architecture. Closure should link to the code or evidence that restored compliance. Renewal should require a fresh reason and approval.

Exception volume is also a governance signal. Repeated exceptions may indicate that the decision is poorly scoped, the enforcement rule is detecting the wrong fact, or the architecture has changed enough to require a new decision. Treat the pattern as feedback rather than normalising an expanding list of suppressions.

• Identify the governing decision and precise deviation.
• Limit scope to the affected repository, path, service or capability.
• Name an owner, approver, compensating control and evidence source.
• Set an expiry and define closure, renewal or supersession explicitly.

Preserve decision provenance in the change

Governance becomes inspectable when the change retains a compact evidence chain. Record the repository revision used for routing, the decision IDs returned, the agent plan or pull-request declaration, changed paths, checks and human approvals. If an exception altered the normal path, record its ID and expiry. This is decision provenance.

Do not confuse provenance with retaining every prompt or hidden reasoning trace. A transcript may contain sensitive data, implementation noise and model speculation. The durable question is whether a later reviewer can reconstruct which authority applied and which observable checks or approvals supported the merge. Stable IDs and source revisions provide stronger anchors than a generated summary.

Provenance also helps diagnose failure. If an agent violated a decision, the evidence can distinguish a missing route, an incorrect scope, an ignored brief, a broken detector and an approved deviation. Those are different operational problems and should not be collapsed into the conclusion that the model was simply unreliable.

Worked example: add cloud synchronisation

Suppose an agent is asked to add cloud synchronisation to desktop workspaces. The intended change crosses desktop storage, a hosted synchronisation service and a shared protocol. The repository has accepted decisions requiring SQLite for local workspace state, PostgreSQL for hosted persistence, offline-first operations, explicit user resolution of conflicts and idempotent background jobs.

The planning route returns those five records because their path or capability scope matches the proposed surface. The brief makes the boundaries explicit: local writes remain available offline; desktop state remains in SQLite; hosted state may use PostgreSQL; conflicts are not resolved silently; and retries do not duplicate effects. The agent can now propose an implementation without treating one global database instruction as the architecture.

The final diff is routed again. Objective consequences become dependency checks, database migrations, an offline integration test, a conflict fixture and idempotency tests. The user-facing conflict experience remains a human design review because no deterministic check can establish that it is understandable. If an old client cannot satisfy the protocol immediately, the team records a narrow, expiring compatibility exception instead of weakening the decision for every client.

• Plan: retrieve decisions for desktop, sync service and protocol paths.
• Implement: cite the returned IDs and preserve each stated boundary.
• Verify: route the final diff and run the linked objective checks.
• Review: evaluate conflict handling and any temporary compatibility exception.

A tool-neutral repository architecture

Decision governance does not require one agent vendor or one documentation platform. Keep the source records in a versioned repository, expose a read-only retrieval contract, and let each coding tool use a thin adapter. The same stable decision IDs should survive whether the task is handled by Codex, Claude Code, Copilot, Cursor or a human developer.

A minimal layout separates authority, instructions, checks and evidence. The exact filenames can vary, but ownership should not. Decision records are changed through review. Instruction files describe operating procedure. Policies and tests implement bounded checks. Pull requests or build artefacts retain citations and results.

repository/
├── AGENTS.md                  # how agents work here
├── decisions/                # reviewed engineering authority
│   ├── DEC-014-sqlite.md
│   └── EXC-006-legacy-sync.md
├── policies/                 # deterministic rule definitions
├── tests/architecture/       # executable consequences
├── .github/workflows/        # validation and enforcement
└── src/                      # implementation governed by scoped records

Adopt decision governance in 30 days

Begin with a small, observable loop rather than reconstructing the organisation's entire architectural history. Choose one boundary that repeatedly consumes review time or creates meaningful risk. Record it with status and scope, test that a representative task retrieves it, and connect one objective consequence to an existing check. The first success is not the number of ADRs written; it is one decision that reliably reaches the work it governs.

During the second phase, add lifecycle and provenance. Define how records become accepted, superseded or deprecated. Require the pull request to cite applicable IDs and record the final routing result. During the third phase, add exception handling and a small fixture suite for expected matches, exclusions and conflicts. Only then expand to more repositories or semantic discovery.

• Days 1–7: select one costly boundary; record its rationale, owner, status and scope.
• Days 8–14: retrieve it from representative paths and give agents a focused brief before planning.
• Days 15–21: link one objective consequence to CI and report the governing decision on failure.
• Days 22–30: add final-diff routing, citations, an exception template and regression fixtures.

Measure whether governance works

Measure the control loop rather than the size of the context file. For labelled tasks, track whether the expected live decision was retrieved, whether stale or out-of-scope records were excluded, whether the agent cited the governing record and whether required checks ran. Record routing latency and context size so improvements in recall do not quietly create unusable briefs.

Review exception volume, expired deviations, orphaned checks and decisions with no owner. A low retrieval count is not automatically good if relevant authority is being missed; a high count is not automatically good if one important record is buried in noise. Use fixture tasks and known repository paths to test the resolver whenever scope or lifecycle logic changes.

The most useful operational metric is often repeated review work. If reviewers continue explaining the same accepted decision on successive pull requests, recording or routing is incomplete. If checks fail without helping developers identify the governing record and remediation, enforcement is technically present but operationally weak.

• Applicability recall and exclusion accuracy on labelled tasks.
• Decision citation completeness in plans and pull requests.
• Final-diff coverage and linked-check execution.
• Exception age, expiry and repeated violation patterns.
• Context size, routing latency and reviewer correction rate.

What should remain human judgement

Humans remain responsible for accepting and changing decisions, resolving genuine conflicts, approving exceptions and evaluating consequences that depend on experience or user context. Agents can draft options, identify affected paths, retrieve prior records and propose tests. Those capabilities improve the workflow without transferring authority silently to the model.

Human review should be concentrated where judgement adds value. A person does not need to inspect every import if a deterministic dependency rule reports the exact forbidden edge. They do need to decide whether a new service boundary is worth its operational cost, whether a migration risk is acceptable and whether an exception's compensating controls are adequate.

The division is therefore not human versus automated governance. It is explicit authority supported by appropriate evidence. Machines handle reproducible matching and bounded checks. People own intent, ambiguity, trade-offs and changes to the governing record.

How AsDecided implements the model

AsDecided keeps typed, human-readable records in Git and validates their structure and relationships with Core. The native CLI and read-only MCP server expose deterministic discovery without giving the retrieval surface authority to rewrite the record. Stable IDs, lifecycle values and source locations keep answers inspectable.

Path-scoped decision lookup is available through the decisions-for CLI command and the find_decisions MCP tool. The gate combines corpus validation with configured enforcement policy, while code-aware enforcement checks explicit constraints against changed or full-tree source. Pull-request surfaces can report which decisions apply without claiming that relevance alone proves compliance.

These capabilities supply the repository-native foundation, not every organisational process. Teams still choose owners, approval rules, risk thresholds and the qualitative decisions that remain human review. The public specification, product documentation, source and changelog are the canonical evidence for what AsDecided currently supports.

# Find the accepted decisions governing one path.
decided decisions-for src/users/repository.py decisions/ --json

# Validate records and include changed-code enforcement.
decided gate decisions/ --code --base origin/main

Decision-governance checklist

Use this checklist when evaluating an existing coding-agent workflow. A missing item is not automatically a reason to stop using agents. It identifies which part of the control loop currently depends on memory, prompt wording or unverified review.

• Authority: meaningful decisions have stable IDs, named owners and reviewed source records.
• Lifecycle: proposed, accepted, superseded and deprecated records are distinguishable.
• Scope: applicability is explicit enough to resolve from repositories, paths or capabilities.
• Routing: agents receive a focused cited brief before making the affected choice.
• Conflict: incompatible live records stop the workflow for explicit resolution.
• Enforcement: objective consequences link to bounded deterministic checks.
• Judgement: qualitative consequences retain a named human review path.
• Exceptions: deviations are narrow, approved, compensating and expiring.
• Provenance: the change preserves decision IDs, source revisions, checks and approvals.
• Regression: fixture tasks test expected matches, exclusions and final-diff coverage.

Conclusion

Coding agents make implementation faster, but speed increases the cost of leaving technical authority implicit. A repository instruction file can teach an agent how to operate. A sandbox can restrict its capabilities. An ADR can preserve rationale. None of those artefacts alone keeps a current decision attached to every change it governs.

Decision governance closes that gap. Record the decision with context, lifecycle and scope. Route the relevant authority before planning and against the final diff. Enforce the consequences that can be established mechanically, and keep human judgement visible for everything else. The result is not an agent that obeys a larger prompt. It is a software-delivery system in which people, agents and CI can inspect the same source of authority.