Chapter 2: The Self-Improving Repository¶
Building the Repository That Holds Your Three Structures¶
1. The Shape of the Repository¶
In most organisations, a repository is a passive archive. It stores code, waits for a human to decipher it, and relies on tribal knowledge or scattered wiki pages to explain how things work. Rules are fragmented: a lint rule here, a pipeline check there, a convention that lives only in the memory of a senior engineer. The knowledge is real, but it lacks a unified arrangement.
A self-improving repository is fundamentally different. It is an active control surface. It does not just store work; it directs it.
Chapter 1 established the theory: AI quality is not decided by the model, but by the three structures surrounding it โ prompt, engineering and workflow. This chapter provides the mechanism. Those structures cannot live in a person's head or a disconnected document; they must be materialised, version-controlled and enforced within the repository itself.
We organise this material by the three structures for a plain, practical reason: it reduces the cognitive load required to work in the codebase. Reducing complexity is the primary job of software design. Other arrangements are possible, but this one is easy to explain, easy to check, and directly maps to the argument of this book.
This arrangement demands something concrete of every structure:
- Constraints must be written down โ the Law and the Map.
- The shape of the work must be visible where a reviewer, human or AI, can point to it.
- The result must be verified by gates that run, not assumed.
The day-one acceptance test: clone the repository, read the front door, run
make help, and know what is true. If a repository cannot explain itself to a new team member or a new agent without a verbal briefing, it is merely storing work, not directing it.
The rest of this chapter builds that repository, file by file.
๐ฏ What You'll Learn¶
- Structures as an organising principle โ why this book arranges a repository by the three structures, and what that choice asks of each part of it
- The Documentation Contract โ the set of documents, each with one job, that makes a repository readable by humans and AI alike
- The Day-One Experience โ why
clone โ help โ start workingis the acceptance test of a well-built repository - Control Plane vs. Application โ the difference between the repository that governs many repos and the repos it governs
Software Architecture First, AI as the Enhancer¶
Before the first file, one principle governs this chapter's design: the repository is built with timeless software architecture, platform engineering, and DevOps practice โ not with AI novelty. AI agents are powerful tools that leverage this foundation; they never replace it.
The impedance mismatch. Good software design โ modularity, clear boundaries, idempotency, reuse, and strict testability โ is precisely what prevents friction with AI. A well-structured repository gives an agent clean boundaries to work inside. A messy one gives the agent nothing but mess to automate: ask an assistant to work inside a tangle of one-off scripts and it will happily generate more tangle, faster. This is Chapter 1's platform-engineering insight applied to the repository itself: build the road well, and the vehicle โ human or AI โ stays on it.
The Repository That Stores Code vs. The Repository That Directs AI¶
Most repositories are passive: they store code and wait for someone to read them. A self-improving repository is active โ it directs how work happens, because it holds the rules, the context, the commands, and the gates that every contributor (human or AI) must follow.
| Passive Repository | Self-Improving Repository |
|---|---|
| Stores whatever was committed | Holds rules that shape what gets committed |
| Each contributor remembers the conventions | The repository documents and enforces them |
| Tools own the workflow | Stable commands own the workflow; tools plug in underneath |
| Quality depends on who reviewed what | Gates run on every change, automatically |
| Knowledge lives in people's heads | Knowledge lives in version-controlled documents |
The acceptance test: clone the repository, run
make help, and be productive without asking anyone. If the repository cannot explain itself, it is not yet a self-improving repository.
What a Repository Holds¶
So what does a repository hold? Each of the three structures needs something concrete, and a newcomer or an assistant will ask the same question about each:
| What it holds | The question it answers | Examples | The structure it serves |
|---|---|---|---|
| The work itself | what is the actual work? | code, infrastructure definitions, documentation | engineering โ the shape the work must fit |
| The checks | how do I know it is correct? | quality gates, security scans, test suites | workflow โ what decides it is right |
| The rules and the context | what are the rules and the context? | AGENTS.md (the Law), AI_CONTEXT.md (the Map) |
prompt โ the constraints a request must satisfy |
| The way they run | how do I run the workflow? | the command surface: thin targets over scripts | workflow โ the checks run without anyone remembering |
The rules and the context deserve the most attention: they are what AI assistants read first, and what most repositories get wrong. The next section covers it in depth.
Configuration as a Contract, Not a Tweak¶
A common failure in infrastructure is treating configuration as mutable, environment-specific tweaks. In a self-improving repository, configuration is a strict contract. The fundamental purpose of this contract is to ensure the exact same software logic runs reliably across all environments. We achieve this by strictly separating the logic (immutable, version-controlled automation definitions) from the environment context: the variables, secrets, and endpoints an environment supplies. The contract dictates what state must be true. If an environment attempts to apply invalid parameters, or if configuration drift occurs, the deployment fails fast. This guarantees deterministic execution and eliminates the technical debt of ad-hoc environment modifications.
The Documentation Contract¶
These are the files that fill those places โ each one serves a structure, and the documents are what the rest of this chapter builds.
The "four files" framing that most guides teach (AGENTS.md, AI_CONTEXT.md, validate.sh, Makefile) under-counts what a production repository actually needs. In practice, a self-improving repository ships a documentation contract โ a set of documents, each with one role that every reader (human or AI) can find by name:
| Kind | File | Role | The question it answers |
|---|---|---|---|
| Front Door | README.md |
The entry point โ overview, quick-start, and explicit links routing humans and AI to the governance files | "Where do I start, and what is this repository for?" |
| Core Blueprint | architecture.md |
The source of truth for structural design โ components, data flow, constraints | "How is this system designed, and what may not change?" |
| Governance | AGENTS.md |
The Law โ symbolic constraints and non-negotiable rules | "What must I always do, and what must I never do?" |
| Governance | AI_CONTEXT.md |
The Map โ current state, conventions, environmental context | "How is this built today, and where are the conventions?" |
| Governance | PLAYBOOK.md |
The Playbook โ step-by-step procedural tasks, each with a human approval gate | "How exactly do I perform this procedure safely?" |
| Product & Business | docs/features.md |
The Cockpit โ the roadmap: planned and released work, each with a lifecycle | "What are we building, and where does each item stand?" |
| Product & Business | docs/capabilities.md |
The Driver โ the business outcomes and strategic value behind the work | "Why does this repository exist, and what outcome does it serve?" |
| Operational | observability.md |
The Mirror โ human-facing operational signals (compliance, inventory, execution), distinct from any application dashboard | "Is the system healthy right now, by evidence?" |
| Operational | operations.md |
The Runbook โ maintenance, incident response, troubleshooting | "When something breaks, what do I do?" |
| Records | CHANGELOG.md |
The Record โ what changed and why, per release | "What has this repository changed, and why?" |
| Records | docs/decisions/<slug>.md |
The Decision โ the choice, the options rejected, the trigger that would reopen it | "Why is it built this way, and what would make us change it?" |
The Law and the Map are the two files that govern AI behaviour directly. The Playbook turns procedures into repeatable, gated steps. The Product & Business documents keep the work honest about why it exists and what it is delivering. The Operational documents prove the whole thing holds in production. Together they form the repository's permanent memory โ the same way a good engineering team keeps its decisions in version control instead of in tribal knowledge.
Beyond the everyday contract lie the append-only records โ the change log, the prompt-regression log (Section 11), and the AI execution log (Section 8) โ evidence written by the loop and read on demand, not loaded by default.
๐งญ Key Insight โ Chapter 1's chain, made concrete. Every file above carries one link of Chapter 1's chain:
docs/capabilities.mdnames the capabilities;docs/features.mdis the delivery plan; the governance trio (AGENTS.md,AI_CONTEXT.md,PLAYBOOK.md) holds the three structures โ the Law for Prompt structure, the Map plusarchitecture.mdfor Engineering structure, the Playbook plus the gates for Workflow structure; andobservability.mdwithoperations.mdhold the outcome. Chapter 1 said the repository moves the driver to the outcome โ this contract is how.
Control Plane vs. Application Repository¶
One repository holds the three structures for a single project. A control plane holds them for an entire organisation. The distinction matters because the control plane is where the self-improving loop gets its leverage:
graph TB
CP["Control Plane<br>(governs the org)"]
APP1["App Repo 1"]
APP2["App Repo 2"]
APP3["App Repo N"]
CP -->|"shared foundation<br>(rolled out)"| APP1
CP -->|"shared foundation"| APP2
CP -->|"shared foundation"| APP3
APP1 -->|"evidence + feedback"| CP
APP2 -->|"evidence + feedback"| CP
APP3 -->|"evidence + feedback"| CP
style CP fill:#e3f2fd
style APP1 fill:#f3e5f5
style APP2 fill:#f3e5f5
style APP3 fill:#f3e5f5
The control plane holds a single source of truth โ a description of every repository, its role, its permissions, and its capabilities โ and rolls the shared foundation out to each one, collecting evidence as it goes. This chapter builds the application repository: the unit every control plane governs. Section 11 returns to the control-plane idea, and Part Three shows how that machinery is built. This chapter deliberately stays with one repository so the foundation is solid before it is ever multiplied.
The Day-One Experience¶
The repository's README states its day-one experience in one line: "Clone this repo โ see the commands โ start working." That is not marketing โ it is the acceptance test of the whole design.
git clone <repository-url>
cd <repository>
make help # every command, self-documented
make setup # verify required tooling is present
Three properties make this possible, and every self-improving repository should aim for them:
| Property | What It Means | How It Is Achieved |
|---|---|---|
| Self-documenting | The command surface explains itself | help renders every command and its intent |
| Self-sufficient | Setup is one idempotent command | setup verifies tooling in a single step |
| Consistent | The same verbs work in every repository you touch | Shared command names โ same intent, same command |
๐ก Key Insight: If a new machine, a new human, or a new AI tool can reach "productive" in one command, the repository's structure is doing its job. If it cannot, no amount of AI will fix the gap โ the structure is the fix.
2. The Intelligence Layer: Law and Map¶
Two files govern AI behavior, and they serve fundamentally different purposes. Getting this separation right is the single highest-leverage decision in the repository, because it mirrors how AI models process context.
Law vs. Map: When to Use Which¶
Use AGENTS.md (The Law) |
Use AI_CONTEXT.md (The Map) |
|---|---|
| "Never commit secrets or API keys" | "Our services are written in Python with typed request models" |
| "Always run validation before commit" | "Database migrations live under migrations/" |
| "Follow the repository's formatting rules" | "Authentication uses signed tokens with expiring sessions" |
| "Every automation must be safe to re-run" | "Webhooks are handled in scripts/handlers/" |
The rule: AGENTS.md contains rules that do not change based on what you are working on. AI_CONTEXT.md contains facts that vary by project, service, or component.
Why the separation matters. When you ask an AI assistant to "add a new endpoint," it needs two things at once:
- Behavioral constraints (from the Law): validate input, follow conventions, never commit secrets
- Architectural context (from the Map): the service is Python, endpoints live in
routes/, migrations use Alembic
Without the separation, the AI either follows rules but lacks context โ writes perfect Python for a Node.js service โ or has context but ignores rules โ knows the structure, but commits secrets. With it, the AI has both guardrails and situational awareness.
Reusable Building Blocks: The Same Law and Map, Many Repositories¶
The evidence from real multi-repo work adds a second split that most guides miss: inside each governance file, reusable content and repository-specific content live side by side. The reusable part โ the rules and context that apply to every repository โ should stay identical wherever it appears; the specific part belongs to that repository alone.
The classification rule. When a new rule or fact is written, classify it first: does it apply to every repository, or only this one? A repository-specific layout rule drifting into the reusable part is the classic failure โ it silently makes the shared block non-reusable. The same discipline applies to the Map, to scripts, and to commands: shared building blocks stay generic, and the specific implementation lives where it is used. Reuse without duplication โ the oldest rule in software, applied to governance.
๐งญ Key Insight: A shared block is a living artefact, not a memory. It improves in one place and is consumed everywhere โ one source of truth, many consumers. How the sharing is mechanised โ a template directory, a scaffold command, a roll-out step โ is an implementation detail this book deliberately leaves to Part Three. The principle is timeless: keep the reusable block reusable, and let nothing repository-specific drift into it.
The Alignment With How AI Models Process Information¶
This separation is not an arbitrary convention โ it maps to how AI systems actually process input:
| AI Layer | Function | Repository Equivalent |
|---|---|---|
| System/Instruction Layer | Behavior, constraints, guardrails โ loaded first, minimal size | AGENTS.md (the Law) |
| Context/Knowledge Layer | Specific knowledge, patterns, architecture โ loaded as needed | AI_CONTEXT.md (the Map) |
| Session/Interaction Layer | Current conversation, temporary state | Chat history, temporary files |
The repository structure mirrors the model architecture, which is why the pattern survives model changes: any model, today or tomorrow, still needs behavioral constraints, contextual knowledge, and temporary state. Structure the repository for that permanence and you stop re-architecting every time a new model ships.
The Context Economy: Why the Split Pays¶
The document set is also economical to load, and context is never free. The Law is small and static โ cheap to include on every request and friendly to caching. The Map is larger and task-dependent โ read only when the task touches that part of the system. Keep the Law small and static, keep the Map organised by area so a reader can pull only the relevant section, and every interaction stays focused.
๐ก Deferred, not ignored. The economics of models and routing โ what each tier costs, when to escalate, how to meter usage โ matter, and Part Two considers them properly. The design principle here stands on its own: load little, load the right thing, and the size of the bill follows the size of the context.
The Law and the Map are the substrate, not the whole system. The six sections that follow are the capabilities a repository builds on top of them: routing the context an agent loads, carrying work across sessions, composing multi-step work safely, bounding when an agent must stop, economizing what enters the prompt, and auditing what the agent actually did. Each is a repository pattern โ the same in every repository, regardless of which assistant reads it.
3. Context Routing: Progressive Disclosure and Reference Mapping¶
Section 2 established the split: the Law is small and static, the Map is large and task-dependent. This section turns that split into an instruction. Progressive Disclosure means loading the smallest part of the Map that makes the current task correct. Reference Mapping is the declared table that says which part is which: a task type in, a set of Map sections out.
The Routing Rule: Task Type to Map Sections¶
The mechanism is a table, declared once and read by every agent:
| Task type | Load from the Map | Why that slice |
|---|---|---|
| Documentation change | Conventions, terminology, chapter format | Prose is governed by voice, not architecture |
| Service or component change | Components, data flow, test boundaries | A change must respect the blueprint it lands in |
| Infrastructure change | Environments, deployment, secrets handling | The blast radius is environmental |
| Pipeline change | Build, release, runners, gates | The failure mode is an unguarded pipeline |
| Governance change | The Law and the Feature Catalogue | It alters the rules every other reader follows |
The table stays small deliberately. A routing table that needs its own lookup has already failed.
The Obligation Lives in the Law; the Mapping Lives in the Map¶
The obligation โ classify the task, load only the routed sections, never guess at relevance โ is timeless, so it belongs in the Law. The mapping is a fact about one repository's Map, so it belongs beside the sections it names. Put the mapping in the Law and the Law turns repository-specific โ exactly the drift Section 2 warned about.
What Breaks Without It¶
Context bloat is the common failure: every task loads every section, because loading is easy and deciding relevance is not. The agent reasons across a Map far larger than its problem, paying in focus and tokens for material that cannot affect the answer.
The opposite failure is subtler โ routing that is stale or wrong, so the agent loads a plausible slice that omits the constraint that mattered. Neither failure produces caution; both produce confident guessing.
Implementing It¶
Declare the mapping as a named section of the Map, and state the obligation once in the Law.
## Task Routing
| Task type | Load from this Map |
|:---|:---|
| Documentation change | ยงConventions, ยงTerminology |
| Infrastructure change | ยงEnvironments, ยงDeployment, ยงSecrets |
| Pipeline change | ยงBuild, ยงRelease, ยงGates |
The Law's half is one sentence: classify the task first, load only the routed sections, and state which sections you loaded.
โ What to Check¶
Give an agent a task, then read its Context and Action Summary (Section 8). The sections it read must match the routing table for that task type.
๐งญ Key Insight: A repository that declares its own routing needs no retrieval feature from any tool: the Map is the index, the Law states the obligation, and any reader can fetch precisely.
4. Session Continuity: The Gitignored Session Artefact¶
Every assistant keeps some notion of a session, and every one of those notions is private to that assistant. Switch tools, and the working state โ what was read, what changed, what was decided, what comes next โ is gone, even though the work is not finished. Session Continuity is the repository-level answer: one disposable, human-readable artefact that any reader can pick up.
The artefact is a baton, not a record: it lets the next reader โ another agent, another model, or the Orchestrator returning after lunch โ resume without being re-briefed.
The Handoff Between Tools¶
sequenceDiagram
participant A as Agent A
participant S as Session artefact
participant B as Agent B
A->>S: write task, decisions, next step
A-->>A: session ends mid-task
B->>S: read the artefact
S-->>B: task, files touched, gate status
B->>B: continue from the next step
The sequence is unremarkable by design: no tool knows about another; both know about the artefact. Continuity lives in the repository, so it survives every change of reader.
What Breaks Without It¶
Without an artefact, continuity is replaced by re-briefing: the Orchestrator re-explains the task to the next tool, which re-reads files it has already read and re-derives decisions already made. The sharper failure is silent loss โ a session ends mid-task with an edit half-applied and no note of where it stopped.
Implementing It¶
Keep the schema minimal:
| Field | Purpose |
|---|---|
task |
One line describing the work in flight |
status |
in-progress / blocked / awaiting-approval / complete |
files-read |
What this session has read โ the routing evidence |
files-modified |
What this session has changed โ never guess at this |
decisions |
Each key decision and its reason, one line each |
next-step |
The exact next action, written for a different reader |
gate-status |
The last gate run and its observed result |
Add the artefact's location to .gitignore. It is derived state, never a second source of truth: if it disagrees with Git, Git wins.
โ What to Check¶
Start a task in one tool, stop deliberately mid-task, then open a second tool and ask it to continue. It should read the artefact, state the next step correctly, and resume without being told what happened. Then confirm git status does not mention the artefact.
๐งญ Key Insight: Sessions belong to tools; continuity belongs to the repository. A short artefact any reader can parse buys the freedom to change tools mid-task โ the only way "tools are transient" survives a real deadline.
5. Workflow Orchestration: Safe Multi-Step Composition¶
Single edits are easy to review. Sequences are where agents go wrong: five files changed, one validation at the end, and a failure that could have come from any of them. Safe Multi-Step Composition is the rule that makes chaining safe โ every step ends in a gate, and every gate passes before the next step begins.
The home for these sequences already exists in the documentation contract: the Playbook. A procedure is a named, repeatable sequence with declared gates and declared approval points.
The Anatomy of a Procedure¶
Each step carries four things, and omitting any one of them is how procedures rot:
| Element | What it declares | Why it is required |
|---|---|---|
| Action | What this step does | A step that cannot be described cannot be reviewed |
| Gate | The command that proves the step worked | Validation between steps is what stops error compounding |
| Approval | Human or automatic | The steps needing judgment are named, not assumed |
| Stop condition | When to abort the sequence | Prevents pushing through a broken premise |
A procedure without gates is a to-do list. A procedure without a stop condition is a trap.
What Breaks Without It¶
The signature failure is compounded error: an agent chains edits without validating between them, each built on the previous step's unverified assumption, until the final gate fails and the whole sequence must be unpicked by hand. Gating each step keeps the failure surface at one change โ the gate ladder of Section 10 applied across time instead of across a diff.
Implementing It¶
Every procedure is named, triggered, and gated:
## Procedure: <name>
**Trigger:** <when this procedure is the right one>
**Steps:**
1. <action> โ gate: <command> โ approval: <human|automatic>
2. <action> โ gate: <command> โ approval: <human|automatic>
**Stop condition:** <the observation that aborts the sequence>
**Rollback:** <how to return to the last known-good state>
Write one procedure before writing ten; the first proves the pattern.
โ What to Check¶
Run a procedure end to end and watch the boundaries, not the output. Every gate must execute, and every approval: human step must halt and wait. Then break step one on purpose: the procedure must stop rather than improvise around it.
๐งญ Key Insight: Composition is not dangerous because agents are careless; it is dangerous because it hides the moment a wrong assumption entered. A gate between steps keeps that moment visible โ exactly when it is still cheap to fix.
6. Escalation Policy: Enforcing Human Authority¶
Section 12 states the authority: AI may read, run, and propose; only the human may write, commit, and release. But a principle that lives only in a paragraph is interpreted differently by every reader. An escalation policy is the set of declared conditions under which an agent must stop and report instead of proceeding โ and they are the reason a sensible orchestrator can let an agent run at all.
The Conditions, and the Required Response¶
| Condition | The agent must | The agent must not |
|---|---|---|
| Irreversible โ a delete, a force-push, a tag, a migration with no down path | Stop before it, and report | Act, then explain |
| Security or production โ a credential, a trust edge, a permission widening, work that reaches production | Stop and hand over; name the exact change | Read, copy, or transmit it |
| Ambiguous authority โ contradictory requirements, two sources of truth, an architectural choice with several valid options | Present the options and stop | Pick an interpretation and proceed |
| A governance change โ the change would alter the Law or the Map | Propose the change and stop | Edit governance on its own authority |
| Out of scope โ the work grew past what was approved | Report the scope violation and re-plan | Widen its own scope |
| A gate that cannot be resolved โ the check cannot run here, or failed N attempts to clear | Report the failure and the command | Loosen the gate or call it green |
The threshold N is a repository decision, and it should be chosen once and stated. An unstated limit is not a limit.
What Breaks Without It¶
Three failures appear in real work, and all three are the same failure in different clothes โ an agent deciding something that was never delegated to it.
The agent that fixes what it was not asked to fix sees an unrelated wart, improves it, and hands over a change nobody reviewed. The agent that quietly edits the Law resolves a conflict by rewriting the rule, and the guardrail it weakened is now invisible. The agent that commits because the task said "proceed" treats an instruction to continue as an instruction to ship.
Implementing It¶
Declare the conditions in the Law, where they cannot vary by task:
## Escalation Conditions
Stop and report to the human when:
- Requirements are ambiguous or contradictory
- Several valid approaches exist and the choice is architectural
- The change would alter the Law or the Map
- The work touches secrets or production
- A gate fails and iterate-to-green cannot resolve it within N attempts
- The task requires a file outside the declared scope
Reporting has a shape, which keeps it honest: the condition that fired, the evidence, the options considered, and the decision being requested.
โ What to Check¶
Trigger one condition deliberately โ hand an agent an ambiguous requirement, or ask it to change a rule. It must stop and report, without making the edit. If it proceeds, the boundary is prose rather than a boundary.
๐งญ Key Insight: Boundaries exist because good intentions are not enforcement. Declaring where your authority begins in advance is what makes granting an agent autonomy safe rather than merely hopeful.
7. Context Economy: Context Budgeting by Task Scope¶
Section 2 explained why the Law/Map split pays. This section makes that economy governable: Context Budgeting is sizing the context to the task. The practice โ two budgets, the always-loaded set, spend in the log โ is the economy chapter's subject; here it is the capability. what enters the prompt to the scope of the task, not to the size of the repository. The repository owns one side of the cost equation, and it is the side you can actually change โ what enters the prompt is a decision you make today; what the model charges is a market you observe.
Scope Determines the Budget¶
| Task scope | The Law | Map sections | Relative context cost |
|---|---|---|---|
| One-line fix | Full โ it is small | The one area the file belongs to | Lowest |
| Single-component change | Full | That component, its interfaces, its tests | Low |
| Cross-cutting change | Full | Several areas plus the conventions | Moderate |
| Architectural change | Full | The blueprint, the conventions, the catalogue | Highest |
The Law is loaded on every task, and that is affordable because it is small. The Map is loaded by scope, because it is organised to be read in slices.
What Breaks Without Budgeting¶
The obvious failure is loading everything for a small task: the whole Map enters the prompt to change one line, and the agent pays for context that cannot affect the result. Cost rises while accuracy does not.
๐ฐ Cost Check: Context Budgeting Loading an entire Map for a small change is the most common avoidable token cost in a governed repository โ and it compounds, because every retry re-sends the same oversized context. The Fix: route by task scope first (Section 3), then choose the tier. Escalation is for reasoning difficulty, not for context volume.
Implementing It¶
Budgeting needs no dashboard and no metering โ only three rules, all declared in files you already have:
## Context Budget
- The Law is always loaded; keep it small enough that this stays cheap.
- The Map is loaded by task scope; never load a section the task cannot touch.
- State which sections were loaded, so the budget is reviewable.
Tier pricing, escalation thresholds, and metering are Part Two's material โ deferred, not ignored. This chapter owns the input side of the equation: right-sized input, chosen deliberately, and recorded.
โ What to Check¶
Compare the Context and Action Summaries (Section 8) of a small task and a large one. The context each loaded should be proportional to its scope. If both loaded the same sections, routing is not being applied โ and the cost is paid on every task.
๐งญ Key Insight: Cost discipline is a governance property, not a tool setting. A repository that declares what loads when has made its own spending predictable โ with no dashboard, no meter, and no per-tool configuration.
8. Execution Transparency: The Context and Action Summary¶
Governance you cannot observe is governance you cannot trust. Sections 3 through 7 ask an agent to route its context, resume from an artefact, follow procedures, respect boundaries, and budget what it loads โ none of it verifiable unless the agent says what it did. The Context and Action Summary is that statement: a structured, append-only entry recording the files read, the rules applied, the decisions made, the gates run, and the outcome. It is the agent-side artefact that keeps the loop's structured-feedback chain (Section 11) intact.
What Each Field Proves¶
| Field | What it proves |
|---|---|
timestamp |
When the work happened, comparably recorded |
task |
What the agent understood it was asked to do |
files-read |
That routing (Section 3) was followed, not improvised |
rules-applied |
Which rules of the Law governed the work |
decisions |
Why the change looks as it does |
gates-run |
That validation happened, with results |
outcome |
green, blocked, or escalated |
next-step |
What the next reader should do, or what is requested |
A summary whose files-read list does not match the routing table is a finding, not a formality.
What Breaks Without It¶
Without a summary, the first question after any agent task โ why did it change this? โ has one answer: read the whole diff and guess. Worse, governance becomes unverifiable: the Orchestrator who cannot see which sections were read cannot tell whether routing was applied or whether boundaries held.
Implementing It¶
Keep the log tracked, append-only, and required:
## AI Execution Log
| timestamp | task | files-read | rules-applied | decisions | gates-run | outcome | next-step |
|:---|:---|:---|:---|:---|:---|:---|:---|
| 2026-01-14T09:20Z | Fix broken internal link | ยงConventions | Truthful docs | Replaced dead link target | make validate โ
| green | none |
Whether it is appended directly or summarized from the session artefact is an implementation choice; what matters is that it is durable, structured, and readable without the conversation that produced it.
โ What to Check¶
After any agent task, read the entry. Every field must be present, and the outcome must match what the gates actually reported โ a summary claiming green where the gate failed is worse than no summary, because it looks like evidence.
๐งญ Key Insight: Transparency turns the other capabilities from intentions into observed behaviour. Routing, budgeting, and boundaries are all claims until an agent records the evidence โ and a recorded claim can be checked by anyone, at any time.
9. The Command Surface Contract¶
Chapter 1 introduced the command surface contract: quality commands, improvement commands, evolution commands โ a stable interface with pluggable implementation. This section shows how a real repository implements that contract with time-tested developer tools โ a Makefile of thin targets, optionally surfaced through a lightweight CLI โ and where the line between "shared" and "repository-owned" sits. Commands are shown here as Make targets; a repository that surfaces the same verbs through its own thin CLI keeps the identical contract โ the verb is the contract, not the wrapper.
The Senior Engineer's Insight¶
A stable command surface is the abstraction layer. It shields you from tool churn.
The pattern separates three things:
| What | Purpose | Example |
|---|---|---|
| Command | What you type | make validate, make pre-commit, make ci |
| Interface | The stable contract | A thin Makefile target |
| Implementation | The pluggable backend | A script that can be rewritten without changing the command |
The command stays the same. The implementation underneath changes. When the AI tool changes โ today's assistant, tomorrow's harness, next year's something else โ the commands you type and the documentation that references them do not.
Thin Targets, Real Logic¶
The rule that keeps the abstraction honest: the Makefile stays thin; all logic lives in scripts. A target is a one-line delegation, never a shell script embedded in the Makefile.
## validate โ the structural gate: script syntax, help render,
## configuration consistency, tooling smoke tests.
validate:
@./scripts/validate.sh
Why this matters for AI: an AI assistant reading the repository sees a stable surface โ a small set of named commands with documented intent. The complexity hides behind the interface, where it can be reviewed, tested, and improved without changing the contract.
Two Surfaces: the Repository's and the Operator's¶
The most common mistake is putting everything in one place. A real system needs two surfaces, and they differ in scope, not in what kind of thing they do โ both of them check, and both of them act.
The second one needs a name, and this book calls it orch: the Orchestrator's console, one copy on the machine,
resolved from whichever repository you are standing in. make belongs to the repository; orch belongs to you.
make โ the repository's surface |
orch โ the operator's surface |
|
|---|---|---|
| defined in | this repository's Makefile |
one copy on the machine, resolved from the working directory |
| knows about | this repository | every repository |
| verbs | validate ยท build ยท dev ยท deploy ยท audio-generate |
commit ยท release ยท sync ยท status ยท diff |
| who may run it | anyone, an agent included | the verbs that change history are the human's |
Two consequences follow from the scope, and they are the reason both surfaces have to exist. A repository's Makefile
can only answer questions about itself โ so a verb that must behave the same way in every repository cannot live in
any one of them. And the verbs that change history belong to the operator, not to the repository โ a Makefile is a
file the agent may edit; the command that ships is not.
๐งญ Key Insight โ the second surface exists for four reasons, and convenience is not one of them.
- One interface for everyone. The human, the agent, the pipeline and the console call the same verbs. One vocabulary, so nothing has to be translated from what a person types into what CI runs.
- One grammar, few verbs.
orch <noun> <verb>is a handful of things to learn; thirty-oneMakefiles are not. The shared surface is what makes the operator's job narrower, not just faster.- Uniformity across repositories. A verb is implemented once, so a fix lands everywhere at once. Measured in one estate: a per-repository
citarget ran eight different bodies of work across twelve repositories, because there was nothing shared to be uniform with.- The authority boundary. The verbs that change history sit outside the repository the agent edits. The rule AI never stages, commits or pushes is enforced by the surface a human uses, not by a target an agent could rewrite.
orch is the human's instrument. An agent may read its output; it does not run its mutating verbs. That distinction is what keeps a common interface from becoming a common authority.
โ ๏ธ Pitfall โ the duplicated verb: if a repository redefines something the shared surface already provides (its own commit wrapper, its own release script), the two drift and nobody can say which one is authoritative. A shared verb is used, never copied.
Same Intent, Same Command¶
The command surface contract only pays off if it is consistent across repositories. The rule of thumb: same intent โ same command. Before adding a new target, check whether another repository already does that intent under a different name โ if so, align to the existing name. A repo-specific spelling is only justified when the intent itself is repo-specific.
| Intent | Command | Surface |
|---|---|---|
| One-time environment setup | make setup |
repository |
| Local preview / dev server | make dev |
repository |
| The gates | make pre-commit / make ci / make deployment-gate |
repository |
| Stage, commit, release | git add ยท orch commit ยท orch release tag=v1.2.3 |
operator |
| See where you are | orch status / orch diff |
operator |
The payoff: the Orchestrator never has to remember two commands for the same thing, and an AI assistant can move between repositories without re-learning the surface.
๐ค One Surface for Humans and Agents¶
The command surface has two audiences, and both are first-class. Humans want readable output; agents need structure they can parse. The resolution is not two surfaces โ it is one surface with two output modes.
| Audience | Default Experience | What It Needs |
|---|---|---|
| Human | Formatted tables, clear logs, colour-coded status | Commands that feel familiar and explain themselves |
| AI agent | Machine-readable output (--output json), predictable exit codes |
Idempotent commands, self-documenting help, parseable results |
The rule: every command a human can run, an agent can run โ and vice versa. There are no "human-only" or "agent-only" verbs. A human developer can run the exact command the agent used and see the same result in the format they prefer.
๐งญ Key Insight โ dual usability is what makes the agent coachable and the human verifiable. The agent chains commands, reads structured state, and reports exactly what it did; the Orchestrator re-runs the same commands and sees exactly what the agent saw. When a test command is invoked by an agent, its results default to a machine-parseable form; humans still get their readable summary. That single discipline is what makes the self-improving loop possible โ see Section 10.
The Staged VCS Flow¶
The version-control workflow is where the contract meets the guardrails. It is deliberately staged and gated:
git add <paths> # staging is manual, by design
make pre-commit # the commit gate: validate + staged secrets scan
orch commit # runs the gate, then commits ONLY staged files
git push
orch release tag=v1.2.3 # gates โ clean tree โ tag โ push the tag
| Step | What Happens | What It Prevents |
|---|---|---|
Manual git add |
You choose exactly what ships | Accidental wholesale commits |
orch commit |
The staged gate (make pre-commit) runs first |
Bad or secret-laden changes entering history |
Tag-based orch release |
Clean-tree check โ tag โ push tag only | Untested "releases" and half-built tags |
โ ๏ธ The boundary you hold (from Chapter 1): AI never stages, commits, or pushes. The AI drafts and edits files, then reports "changes ready for review" (
git status/git diff) and stops. The ship flow is the Orchestrator's action โ even when the task says "proceed." This is the review boundary from Chapter 1, applied to the command surface.
10. The Validation Gates¶
Validation is what turns "AI generated this" into "AI generated this and it is correct." But validation has a failure mode of its own: the fake gate.
Gates Real or Absent¶
The hard-won lesson from real projects: a gate that always passes is worse than no gate at all. A stub that prints "skipping" while the pipeline reports "all gates passed" gives false confidence โ and both humans and AI treat green as green. The rule:
A gate is a promise. A gate that always passes is a lie. Ship real gates, or ship none.
| Fake Gate | Real Gate |
|---|---|
| Prints "โ passed" without checking anything | Actually runs the check and fails on violation |
| Gives false confidence in CI | Fails the pipeline loudly, with a fix path |
| Hides the problem until production | Surfaces the problem at the cheapest point |
The Gate Ladder¶
Gates are not a flat pile โ they are a ladder of moments, each with its own budget:
flowchart TD
A["Atomic Moments<br/>one concern each<br/>(fast, any time)"] --> B["Commit Gate<br/>the staged diff<br/>(seconds, locally)"]
B --> C["Full Gate<br/>everything CI runs<br/>(local == CI)"]
C --> D["Scheduled<br/>(nightly: exhaustive, slow)"]
D --> E["Release<br/>(gates โ clean tree โ tag โ push)"]
style A fill:#e3f2fd
style B fill:#fff3e0
style C fill:#f3e5f5
style D fill:#e8eaf6
style E fill:#e8f5e9
| Stage | Command | When You Run It | Scope |
|---|---|---|---|
| Atomic | make validate, make security-scan |
Any time you want one concern checked | Fast, one concern each |
| Commit gate | make pre-commit |
Before every commit โ what orch commit runs |
Staged diff only, so it stays fast |
| Full gate | make ci |
Before push / release | Everything a push must satisfy โ identical to what CI runs |
| Scheduled | the nightly workflow | On a timer | The exhaustive or slow checks no one waits for at a merge |
| Release gate | orch release tag=โฆ |
Shipping a version | Merge gate + clean tree + tag |
Give the gate an adjective. Gate alone names a family, never a specific check โ so in prose it carries the word that says what it guards: a quality gate guards the code, a security gate guards secrets and dependencies, a release gate guards what leaves the building, a commit gate guards the staged diff, a console gate guards a caller's session at an API edge. Bare gate is fine only where the adjective is already established by the sentence or the list around it.
And the door is not a gate. The identity entrance is the door โ a different object with a different job, named differently on purpose, so a reader never has to work out which metaphor is in play. The discipline is the same one the book applies to the Law and the Map: one word, one thing, and the qualifier says which.
The key design decision is the full vs. staged split (the commit gate scans only the staged diff, the full gate scans everything). Without it, the commit path is either slow (full scan on every commit) or dishonest (no scan at all). With it, the commit path is fast and honest, and the release path is exhaustive.
๐ Security as a Gate¶
Security belongs in the ladder, not as an afterthought. The security scan runs at the atomic moment, in staged form on the commit path, and in full form on the CI path:
| Risk | What the Gate Catches |
|---|---|
| Secret leakage | Hardcoded credentials committed to the repo |
| Supply chain | Suspicious dependencies, missing lock files |
| Misconfiguration | Wide-open permissions, unsafe defaults |
The same discipline that governs the quality gates applies here: the scan is real, it fails loudly, and its failures carry a fix path. (Security and compliance get their own depth later in the book; this chapter just wires the gate into the ladder.)
The Iterate-to-Green Loop¶
The final piece of validation is the loop that makes AI self-correcting. It is a non-negotiable working rule for every AI agent:
AI work is not done because it was written โ it is done when the gate is green.
1. RUN the gate for the change
2. READ the failure โ the error output is the spec for the fix
3. FIX the root cause โ never mask, skip, or bypass the gate
4. RE-RUN, and repeat until green
5. Only then report success โ stating what was run and the result
A red gate is a finding to fix, not a reason to claim success. If a gate cannot run in the current environment, the AI reports it as blocked with the exact command โ never as passing. This loop is what turns "the repository validates" from an aspiration into an observed property of every change.
๐ก Testability Is the AI's Feedback Signal¶
Testability is not a standalone document โ it is a contract woven through the repository, and it is the AI's primary feedback mechanism:
| Where | The Contract |
|---|---|
| The Rule (in the Law) | AI-generated code includes appropriate tests |
| The Boundary (in the blueprint) | Testing boundaries and coverage expectations are defined |
| The Evidence (in the gates) | Test suites run through the command surface; the gate ladder fails any change that lacks evidence |
Why structure matters. Test results are not only evidence for humans โ they are the primary structured feedback that drives the self-improving loop. Their output must be machine-parseable โ structured results, machine-readable CLI output โ so an agent can read what failed, why it failed, and where it failed, then fix and re-run. A gate whose output is prose only a human can interpret is a gate that blinds the agent.
The closed loop:
AI generates โ the command surface runs the tests โ AI parses the structured results
โ AI fixes the failure โ AI re-runs to green โ AI proposes a governance update โ human approves
11. Documents Are Artefacts Too โ the consumer you didn't know you had¶
That sentence is obvious for code and strange for prose, and the strangeness is why this section exists. Once a markdown file is committed into a governed repository it stops being prose and becomes a source file: something reads it, and that reader has a failure mode of its own.
There are exactly three kinds of reader, and each produces a different failure.
| Kind | What it does | The failure it causes | Does it tell you? |
|---|---|---|---|
| Projection | transforms the document into artefacts | the artefact disagrees with its source | yes โ the build fails |
| Enumeration | holds a whitelist the document must fit | an unexpected file or directory | yes โ the gate refuses |
| Byte-compare | fingerprints the text against a canonical copy | one repo's copy drifts from the rest | yes โ the comparison fails |
Three failures, all loud. And then there is the fourth reader, the one that matters:
| Kind | What it does | The failure it causes | Does it tell you? |
|---|---|---|---|
| Projection without a schema | a view renders the document's rows or keys | a row silently disappears from a screen | no |
A console that builds a "feature catalogue" from a table, or a "plans" view from front-matter, is a projection with no contract. Rename a column, drop a key, and nothing fails: the view simply shows less. The reader โ a person โ notices weeks later that something is missing, and there is no record of when it went.
This is the whole practical lesson: declare the consumer, and give a check only to the consumer that fails quietly.
> **Consumers:** none
> **Consumers:** projection:scripts/project-features.sh
> **Consumers:** console-ledger:config/console-nav.yaml
> **Consumers:** topology:book/docs-topology.json
> **Consumers:** byte-compare:tools/canonical.sh
Consumers: none is not decoration. It records that the absence was checked โ the difference between "nothing
reads this" and "nobody looked".
Three rules follow, and they are the section in full:
- Declare the consumer in the document, not in the tool. A consumer that exists only in a script's import path is the same defect as a rule that exists only in a runtime's memory: it cannot be reviewed where the document is reviewed.
- Check only the silent ones. A projection that fails the build, a whitelist that refuses the commit and a byte-comparison that names the drift are already gates. Adding machinery to them buys a better error message, not a prevented defect. The view with no schema buys a prevented defect.
- The universal check is the cheapest one: an identifier and a state for every row; the keys the view reads, present in the front-matter. Two assertions, no schema engine, no dependency graph.
What this is not¶
It is not a documentation system, and it is not a dependency graph. The moment a "document build orchestrator" appears, it becomes the next artefact that drifts โ and it will be invisible, because nobody thinks of the orchestrator as documentation.
It is also not a reason to write more documents. Every consumer is a contract someone must keep; the same reasoning that says declare the consumer says delete the document nothing reads.
The connection to Chapter 14. The integration charter says: decide the boundary once, then let something check it. A document's consumers are its boundary. Same shape, smaller scale โ and the same rule: the boundary exists whether or not you wrote it down; the only question is whether you find out at build time or at reading time.
Evidence: one gate that fails when a catalogue loses its state column or a plan loses its front-matter keys; and one
document whose Consumers: line is none, checked rather than assumed.
Template: the Consumers: header line, and the two-assertion console check.
12. The Self-Improving Loop at Org Scale¶
A self-improving repository improves itself. A control plane makes that improvement compound across an entire organisation: improve the foundation once, sync it everywhere, collect evidence, repeat.
The Manifest: One Source of Truth¶
The control plane's core artefact is a manifest โ a declarative file that describes every repository, its tier, its class, its owner, its lifecycle, its policy, and the teams and permissions that apply. It is the single source of truth for the organisation:
| The Manifest Declares | What It Drives |
|---|---|
| Repos, tiers, classes, lifecycle | Cloning, workspace file, foundation-sync eligibility |
| Teams and permissions | Access and onboarding (planned sync) |
| Runner groups and profiles | Execution capacity and trust boundaries |
Because the manifest is declarative and validated, the answer to "what is the state of the org?" is always read the file, run the gate โ never "ask the person who knows." AI assistants read the manifest before touching org tooling; the Orchestrator changes the file and validates.
Reusable Building Blocks: The Roll-Out Discipline¶
The foundation standard โ the documentation contract, the governance templates, the command-surface verbs, the reusable scripts โ lives in one place and reaches every repository through a disciplined roll-out: assess the current state, preview what would change, apply it idempotently. The roll-out never edits a repository's own surface โ the repository's gates and its specifics stay its own. How this machinery is built is Part Three, which assumes the vocabulary introduced here and builds on it rather than re-teaching it; this is the self-improving loop from Chapter 1 made concrete:
flowchart LR
A["Improve the foundation<br/>(one place)"] --> B["Validate<br/>(gate green)"]
B --> C["Roll out to every repo<br/>(assess โ preview โ apply)"]
C --> D["Collect evidence<br/>(what worked, what drifted)"]
D --> A
style A fill:#e3f2fd
style B fill:#fff3e0
style C fill:#f3e5f5
style D fill:#e8f5e9
The multiplier made real. One humthe Orchestrator, one control plane, and the same foundation rolls out across every repository. The book's claim in Chapter 1 โ that the Orchestrator's leverage comes from systems, not effort โ is exactly this loop. (The quantified multiplier โ "Nร faster" โ is a claim this book only makes once measured across a release milestone; treat marketing numbers elsewhere with suspicion.)
โจ Self-Documenting Automation: The Timeless Intent Pattern¶
For the loop to work, every artefact must be reviewable by human or AI at any time, on the surface where it is actually reviewed. This is the Timeless Intent pattern โ the invariant each artefact maintains, stated where it is read:
| Surface | The Contract |
|---|---|
| Automation run output | Every step: a timeless โถ intent (the invariant it maintains), short action lines, a โ
/โ outcome, and on failure a โ FIX: next action with a doc pointer |
| Code definition site | The file/function header states the invariant the code maintains; error messages carry the actionable โ FIX: shape |
| Status dashboards | Every critical invariant is observable as a live signal, consuming the same check logic as the gates โ never a second source of truth |
Timeless over incident. The intent is the enduring contract ("this hostname must always answer unauthenticated"), never the bug that prompted the fix ("your zone had sign-on enabled"). Incident detail โ error codes, symptoms โ belongs in the FIX line or the runbook, where it is timeless troubleshooting.
๐ก Why this matters for AI: an artefact that only makes sense in light of the last incident is not maintainable โ by a human or an AI. The Timeless Intent pattern is what lets an AI agent read any workflow's output, spot a deviation, and propose the fix without a conversation history.
The Feature Catalogue: Making Status Observable¶
Every repository maintains a Feature Catalogue (features.md): each feature has a lifecycle state, a validation, and a dashboard signal. The states form a standard ladder:
planned โ in-progress โ implemented โ configured โ healthy โ degraded โ deprecated โ removed
The catalogue is the organisation's honesty surface. A capability is "healthy" only when its validation passes and its dashboard signal is live โ status is observed, not asserted. This is the workflow-structure counterpart to the validation gates: enforcement on one side, visibility on the other.
The Instrument That Reads the Manuscript¶
A repository that validates its build and not its book has instrumented the wrong artefact. Gates prove the site is consistent; they cannot tell you the argument is. So the self-improving loop gets one more reader, pointed at the manuscript itself.
It asks five questions, each answered by a check that can fail, and whose failure names the sentence to change. Four run today; the fifth is on probation โ it earns its place or it is cut:
| Check | The question | What a failure means |
|---|---|---|
| Term integrity | Does the prose name a thing the way the repository names it? | Two names for one thing, or one name for two |
| Pointer integrity | Does a sentence that points at a file still describe what is in it? | The abstraction goes concrete and lands on the wrong file |
| Promise โ payoff | What does the text promise that the manuscript never pays? | A reader waits for a chapter that is not coming |
| Source coverage | Which claims assert evidence and cite nothing? | A sentence that sounds proven and is not |
| Section role (probationary) | Does this section advance the argument, or decorate it? | Prose that could be cut without loss |
It refuses more than it measures, and every refusal is a measurement rather than a taste:
| Refused | Why the measurement refuses it |
|---|---|
| Redundancy scan | Zero repeated body sentences of twelve words or more across the published edition; eight-gram overlap between page pairs is 0.8 %, 0.3 % and 0.2 %. It would report zero and consume attention. |
| Thesis-word density | It ranked a legitimately mechanical section lowest โ and the section only looked thin because a heading inside a code fence had split it in two. A proxy that mislabels good prose teaches the editor to skip the report. |
| Reader telemetry | It needs per-reader tracking, which this book's privacy boundary forbids; at current readership an aggregate would be too noisy to change a decision. |
| Search-query instrumentation | Search is client-side โ queries never reach a server, so there is nothing to record without adding a third-party service. |
| External link rot | The published edition has zero external links. A check over zero links can only pass โ and a gate that always passes is worse than no gate at all. It becomes real when source coverage adds the first citation. |
| Build-size budget | The deploy already enforces the file limit through the audio check. A second check would be a second source of truth. |
| Authorship metrics | Forbidden by this book's own rule โ never measure output volume, lines or commit counts โ and two chapters have no distribution to measure. |
The instrument earns its place by finding things, not by reporting green. Three findings from the published chapters, each one a sentence an editor could act on โ and did:
| Finding | What the check compared | What it changed |
|---|---|---|
| One catalogue, one name | the capability catalogue and the feature catalogue are separate files with separate jobs; a third name for either is a second source of truth | Pick one term per document, and use it everywhere |
| A pointer that describes the wrong file | The sentence "docs/capabilities.md names the driver" โ the file names no driver |
Fix the sentence, or make the file do what the sentence says |
| A promise with no payoff | "the book's closing chapter walks this list" โ there is no closing chapter, and the outline records it blocked | Hedge the sentence, or mark the promise open until the chapter exists |
A fourth finding taught the design its most important lesson. A naive scan reported eight sections in this chapter missing their key-focus line; seven of those "sections" were headings inside fenced code blocks โ samples of governance files, not prose. The scan was wrong, not the chapter. A check that cries wolf gets ignored, which is why the instrument reads fences before it reads sections.
๐งญ Key Insight: The manuscript already holds its readers to "an ability without evidence is a claim, not a property." The instrument turns that sentence on the book itself: status is observed, not asserted โ including the status of the argument.
That is the whole claim: not analytics, and not a dashboard. A list of the sentences that decide whether the prose is good, so the rewrite, cut, merge and add-source decisions are made from evidence instead of memory.
๐ The Feedback Architecture¶
The self-improving loop runs on structured outputs. Each link in the chain โ test results, validation-gate output, command responses โ must be machine-readable, so the agent can locate a failure and act on it without a human interpreting the output first. If a single link outputs unstructured prose that only a human can interpret, the agent's ability to self-improve is severed at that point. Build the chain once โ generate โ run โ parse โ fix โ propose โ and every improvement after it is automatic.
๐ฉบ The Post-Mortem Auto-Update Rule¶
When an AI-generated change fails a validation gate, fixing the code is only half the work. The rule: the agent also proposes a specific update to a governance file โ the Playbook, the Map, the runbook, or the change log โ so the same failure cannot recur. The trigger is the structured failure output: the agent reads it, diagnoses the root cause, applies the fix, and proposes the governance update that encodes the lesson. A failure that fixes the code but forgets the lesson is a failure that will repeat.
๐งช Prompt Regression Testing¶
How do you know the Law is actually obeyed? By testing it. Prompt regression testing deliberately prompts the AI to violate a rule in a sandbox, verifies the constraint holds, and logs the result. Each test is logged to a dedicated regression log (docs/prompt-regression-log.md) โ date, rule tested, the violation attempt, and the outcome โ so the proof that the Law holds is reviewable by human and agent alike and stays out of the everyday context. If the Law can be talked out of enforcing its own rules, the problem is in the Law, not in the prompt: strengthen the constraint and re-run the regression. Adversarial testing in depth belongs to Part Two โ the principle belongs here: a rule you have never tried to break is a rule you do not yet trust.
13. AI Agents in the Governed System¶
Everything so far โ the Law, the Map, the command surface, the gates โ exists so that AI can work inside a governed system. This section shows how the agents plug in, how to route their work across model tiers, and where the lines are.
The Agent as Reader, Not Owner¶
The AI assistant โ a CLI tool, an IDE agent, or a harness โ is a reader of structure. It does not remember the rules; it reads them. It does not own the workflow; it invokes the commands. That is what makes assistants interchangeable โ the same tool-centric-versus-repository-centric contrast Chapter 1 drew, now built rather than described.
๐งญ Key Insight: The book does not claim a specific assistant is more "reproducible" than another โ that is a tool property to verify on your own bench, not a foundation claim. The foundation claim is stronger: any reader of the repository inherits its structure, so the workflow survives the tool.
The 3-Tier Strategy: Routing Work to the Right Model¶
Model selection is fitness for purpose, not loyalty to a brand. The 3-Tier strategy is the routing rule used throughout this book's own production workflow:
| Tier | Role | Use It For |
|---|---|---|
| Tier 1 โ Architect | Complex reasoning, system design | Architectural planning, deep structural reviews |
| Tier 2 โ Editor | High-volume, repetitive execution | Default (~80% of tasks): editing, boilerplate, validation fixes |
| Tier 3 โ Sovereign | Zero data egress, absolute privacy | Sensitive code, secrets, offline environments |
The default is Tier 2 โ most work is routine. Escalate to Tier 1 only for complex reasoning. Mandate Tier 3 for anything sensitive: for sovereign work, models run locally, so nothing leaves the machine. The tier is defined by where the model runs, not by any one model or registry โ pull a verified open-weight model and serve it on your own hardware. What each tier costs, when to escalate, and how to meter usage are economics this book considers properly in Part Two. The routing rule itself is durable: right-size the model to the task.
The Agent Harness Pattern¶
When work scales past a single interaction, the most advanced systems use a harness โ a framework that orchestrates multiple agents toward a goal. The repository itself can act as one:
| Layer | Component | Role in the Loop |
|---|---|---|
| 1. Router | Makefile targets (make validate, make improve) |
Directs tasks to the right command and workflow |
| 2. Context Manager | AGENTS.md + AI_CONTEXT.md |
Shared state and rules; every agent reads from here |
| 3. Agent Pool | CLI assistants, IDE agents, validation scripts | Execute tasks; learn from feedback; improve over time |
| 4. Feedback Loop | Git history + validation results | Records outcomes; informs the next iteration |
The loop is the self-improving pattern from Chapter 1 in action: validation failures make the Law clearer, successful patterns enrich the Map, repeated tasks become new commands, and Git history shows what is working.
The AI Workflow Loop¶
Inside the governed system, every AI task follows the same sequence โ the loop this book has been building toward:
- Read the Law (
AGENTS.md) โ the non-negotiables - Read the Map (
AI_CONTEXT.md) โ the architecture and conventions - Read the manifest when the task spans repositories โ the org's source of truth
- Make the smallest coherent change
- Run the gate and iterate to green โ never declare success on unverified work
- Stop and report โ the boundary from Section 9: never stage, commit, or push
| Boundary (from Chapter 1) | Applied Here |
|---|---|
| Review before anything ships | AI output is treated like a junior engineer's PR |
| The repository is the source of truth | Agents read the Law and the Map; they don't own them |
| Validation is automated, not assumed | Gates run on every change; iterate-to-green is mandatory |
| Model work is right-sized | The 3-Tier strategy routes the task to the model that fits |
| Human authority is final | AI suggests; the human approves every write, commit, and release |
๐ก๏ธ The Human Orchestrator Authority¶
The self-improving loop has a last gate, and it is not automated. Human Orchestrator Authority: an AI agent may read, parse, suggest, execute commands, and propose fixes โ but every change to the repository ultimately rests with the humthe Orchestrator. The agent operates inside a sandbox of read / execute / suggest; the write / commit / merge authority is reserved for the human.
| The AI May | Only the Human May |
|---|---|
| Read the Law, the Map, and the state | Change the Law, the Map, and the contracts |
| Run commands and parse results | Commit, merge, and release |
| Propose fixes and governance updates | Approve or reject every proposal |
| Suggest a release | Ship it |
The workflow: AI generates โ AI runs the tests โ AI reads the results โ AI proposes fixes โ AI proposes governance updates โ the human reviews and approves โ changes are committed. Every step is automated except the final authority, which remains human.
๐ The safety net: this is what keeps the "self-improving" loop from ever becoming a "self-destructing" loop. The human can reject, modify, or override any proposal. The AI is a powerful assistant, not an autonomous decision-maker โ and every procedure in the Playbook carries an explicit human approval gate before anything is committed. The AI does ninety-five percent of the work; the human signs the final five percent.
14. Synthesis: The Repository as the Ultimate Force Multiplier¶
The six capabilities are not six features. They are one operating loop, and each step is what keeps the next honest:
flowchart LR
R["Read<br/>(Law + Map)"] --> RO["Route<br/>(load the slice)"]
RO --> A["Act<br/>(follow the procedure)"]
A --> V["Validate<br/>(gate each step)"]
V --> L["Log<br/>(context & action summary)"]
L --> E{"Escalate<br/>or complete?"}
E -->|"condition fired"| H["Human decides"]
E -->|"green"| D["Done"]
H --> RO
style R fill:#e3f2fd
style RO fill:#e3f2fd
style A fill:#fff3e0
style V fill:#fff3e0
style L fill:#f3e5f5
style E fill:#e8f5e9
Routing and budgeting (Sections 3 and 7) decide what enters the prompt; act and validate (Sections 5 and 10) decide how the work is done. Log (Section 8) records it, and escalate (Section 6) hands the loop back to the human. The heartbeat from Chapter 1 โ propose, validate, apply, repeat โ is this loop seen from the repository's side.
The Order Is a Dependency, Not a Preference¶
Routing precedes economy: you cannot budget a context you do not control. Continuity precedes transparency: there is nothing to summarize if state does not survive. Boundaries precede orchestration: chaining steps is safe only once stop conditions exist. Transparency sits over all of it.
Implement in this order: routing, continuity, orchestration, boundaries, economy, transparency.
The Maturity Model: Minimum Viable, Then Full¶
No repository adopts all six at once. Start with the minimum; take the full pattern when the work justifies it.
| Capability | Minimum viable | Full pattern |
|---|---|---|
| Context Routing | One routing table | Per-task-type routing, verified |
| Session Continuity | Artefact with task and next step | Full schema with decisions and gate status |
| Workflow Orchestration | One named, gated procedure | A library with stop conditions and rollback |
| Escalation Policy | Six declared stop conditions | Conditions plus tests that trigger them |
| Context Economy | The Law/Map split alone | Task-scope budgeting, reviewed per task |
| Execution Transparency | An append-only log with the core fields | The full summary, checked against routing |
The minimum column is a real implementation, not a placeholder: each row closes its failure mode.
Why This Elevates Any Tool¶
A repository built this way does not depend on a capable assistant; it supplies what the assistant lacks โ session memory, context selection, workflow support, guardrails, cost control, and audit history. A modest tool plugged into it therefore behaves like a better one, because the structure it lacks was never the tool's job. This is the chapter's opening claim โ the repository is the hero โ demonstrated, not asserted.
๐งญ Key Insight: You do not wait for a tool to gain these capabilities. You build them once, in the repository, and every tool you plug in inherits them โ the practical meaning of "tools are transient, the repository is permanent."
15. Putting It Into Practice¶
Build or Clone: The Bootstrap¶
You have two valid starting points:
| Path | When to Choose It | First Steps |
|---|---|---|
| Clone a control plane | A foundation already exists (team, org, or your own past work) | git clone โ make help โ make setup โ start |
| Build your own | Starting fresh, or the existing repos are unstructured | Follow the 30-minute bootstrap below |
The 30-minute bootstrap, compressed to what actually matters:
# 1. Initialize (5 min)
git init && touch README.md .gitignore
# 2. The Law, the Map, and the Playbook (10 min)
# AGENTS.md โ rules that never change; AI_CONTEXT.md โ architecture and facts;
# PLAYBOOK.md โ the procedures that must be repeatable and gated.
# If you manage more than one repo, keep the reusable parts generic โ how
# they are shared is a later-part concern, not part of this bootstrap.
# 3. The command surface (5 min)
# Makefile with thin targets: help, setup, validate, pre-commit, ci,
# plus the VCS surface (status, sync, log, diff, commit, release).
# 4. The gates (5 min)
# scripts/validate.sh โ a REAL check. A stub that prints success is a lie.
# 5. The first loop (5 min)
make validate && git add <paths> && orch commit
โ Foundation Checklist¶
โก README.md โ the front door: what this repo is, how to start, links to governance
โก architecture.md โ the core blueprint: design, components, constraints
โก AGENTS.md โ the Law: rules that never change
โก AI_CONTEXT.md โ the Map: current state, conventions, key file locations
โก PLAYBOOK.md โ the Playbook: procedures with explicit human approval gates
โก docs/features.md โ the delivery-plan catalogue: planned and released work
โก docs/capabilities.md โ the drivers: the business outcomes behind the work
โก observability.md โ the operational mirror (when the repo is operated)
โก operations.md โ the runbook (when the repo is operated)
โก CHANGELOG.md โ a record of what changed and why
โก The command surface โ thin targets / CLI verbs that delegate to scripts/
โก scripts/ โ the real logic, including a REAL validate gate
โก Structured test results โ machine-parseable output the agent can read
โก docs/prompt-regression-log.md โ the rule-violation regression log (adopt with prompt regression testing)
โก The staged flow โ manual git add, gated commit, tag-based release
โก An AI assistant configured to read the Law and the Map
โก A human approval gate on every write, commit, and release
โก Context routing rules โ task type โ Map sections
โก `.session/` in `.gitignore` โ the session artefact
โก One named, gated Playbook procedure
โก Escalation conditions in the Law โ the stop-and-report rules
โก Context-loading rules โ what loads when
โก `docs/ai-execution-log.md` โ the action summary log
โก A verification step for each capability โ one check you can run
Quick Reference¶
Commands are illustrated as Make targets; the same verbs are surfaced through your CLI where one exists โ the verb is the contract.
| Action | Command |
|---|---|
| See every command | make help |
| Fast commit gate | make pre-commit |
| Full gate (local == CI) | make ci |
| Commit staged changes | orch commit (custom message: m="..." orch commit) |
| Tag-based release | orch release tag=v1.2.3 |
| Review the staged diff | make diff-staged |
| Sync with upstream | make sync |
Common Issues & Fixes¶
| Issue | Likely Cause | Fix |
|---|---|---|
| Gate passes but nothing was checked | Stub gate | Replace with a real check โ a fake gate is a lie |
orch commit refuses to run |
Staged gate failed | Read the failure, fix the root cause, re-run (iterate to green) |
| AI "completed" without running the gate | No enforcement | Require iterate-to-green; treat unverified work as blocked |
| Different commands in different repos | Surface drift | Align to the standard names; same intent โ same command |
| High token spend | Context bloat / wrong tier | Use the Law/Map split; route with the 3-Tier strategy |
| Entire Map loaded for a one-line change | No context routing | Add task-type routing |
| A new tool cannot continue previous work | No session artefact | Create .session/current.md; gitignore it |
| Edits chained without validating between steps | No Playbook procedure | Write one named, gated procedure |
| Agent "fixed" something outside its scope | No escalation policy | Declare stop-and-report rules |
| Small tasks cost as much as large ones | No task-scope budgeting | Add context-loading rules per task scope |
| Cannot verify the agent followed the routing | No execution log | Add the log; require the summary |
16. ๐ Chapter Summary¶
What You Learned¶
This chapter built the repository that holds Chapter 1's three structures:
- The repository is the hero โ the work, the checks, the rules and the context, and the way they run, plus the documents that make make it readable by humans and AI alike โ and it carries every link of Chapter 1's chain, from driver to outcome
- The Law, the Map, and the Playbook โ
AGENTS.mdholds the rules,AI_CONTEXT.mdholds the context,PLAYBOOK.mdholds the gated procedures โ and reusable building blocks keep all three identical across many repositories - The command surface is a contract โ one dual-usable surface for humans and agents over pluggable scripts; shared blocks stay identical, repository-owned gates stay local
- Gates are promises โ real or absent, arranged as a ladder (atomic โ commit โ full), with the Iterate-to-Green loop and machine-readable results making AI self-correcting
- The loop compounds at scale โ the control-plane concept (a single source of truth, reusable building blocks, a disciplined roll-out) turns one improvement into an organisation-wide improvement; structured feedback, the Post-Mortem Auto-Update Rule, and prompt regression testing keep the loop honest
- Agents are readers, not owners โ they inherit the structure, are routed by the 3-Tier strategy, and work inside the boundaries you hold โ with Human Orchestrator Authority as the final gate
- The repository operates the agent โ six capabilities (routing, session continuity, orchestration, escalation policy, context economy, execution transparency) turn a governed repository into an operating environment that any tool inherits
The Universal Pattern¶
Any repository + AI + Git + Validation = a self-improving system
Where: - Every change is auditable (Git commits) - Every change is validated (real gates) - Every change improves the system (the loop feeds back) - The workflow itself evolves (templates + sync)
Your Next Steps¶
1. Build or clone your self-improving repository (30 minutes)
- Law, Map, Playbook, command surface, real gates
2. Run your first improvement cycle (15 minutes)
- Improve โ validate โ iterate to green โ human approves โ commit
3. Expand to your actual work (ongoing)
- Any repository: the pattern is portable
4. Scale to a control plane (when you manage more than one repo)
- One source of truth โ shared blocks โ roll-out โ evidence
17. Where This Leads: From One Repository to Many¶
What Comes Next¶
You now hold the governed repository: the unit of orchestration. Chapter 4 gives it a command surface โ the thin layer over the tools you already drive, so the rules this chapter wrote down can run. The book continues in three practice parts, and the patterns you built here are the ones every later chapter reuses:
- Part Two โ The Instrument is what the agent works with, in the order it meets it: the language that names things, the command surface that acts, the context it reads and what that costs, the session it cannot remember, the procedure that sequences a change, the boundary where its authority ends, and the log that proves it all happened.
- Part Three โ The Boundary takes the workbench outward: what you do not own โ an upstream product, a provider's commodity, the integration charter, contracts, sovereignty, and the exit drill that proves the boundary holds.
- Part Four โ The Guarantees is what one system must be able to prove before it is asked to scale: show its state, survive its loss, refuse a bad change.
- Part Five โ The Delivery System makes it organisational: version control as the portfolio's source of truth, the control plane as a product, versioning and release management, governance the machines enforce, the agent plane at scale, portfolio operations, the fleet, and measurement.