Chapter 20: From One System to a Portfolio¶
The Manifest as the Answer¶
Chapter 19 closed the gate estate for one system; this chapter asks the question only a portfolio can ask — what is the state of the organisation?
1. What Changes at Scale¶
The three structures worked for one system. A portfolio changes the question: not is this system correct? but what is the state of the organisation? — and that question has exactly one good answer: read a file, run a check.
Everything else is a conversation with whoever remembers.
🎯 What You'll Learn¶
- Why rules become registries, procedures become rollouts, gates become policy
- What the manifest is for — and what it must never become
- The portfolio map: owner, repository, lifecycle
Four Things That Stop Scaling¶
| At one system | At a portfolio | What replaces it |
|---|---|---|
| a rule in a document | a rule nobody can apply twice the same way | a registry |
| a procedure a person follows | a procedure with ten variants | a rollout |
| a check in one pipeline | a check applied to some repositories | policy |
| a mental list of what exists | a list that is wrong | the manifest |
None of these is a new tool. They are the same facts, moved from memory into a file, and made checkable.
flowchart LR
M["portfolio.yaml<br/>the manifest"] --> R["registries<br/>derived, never edited"]
M --> V{"validator<br/>in the gate"}
V -->|"passes"| S["the portfolio's state<br/>one command"]
V -->|"fails"| F["a row with no owner<br/>or an unknown tier"]
What this shows: one file, one derivation, one check — the only shape in which the answer is the same for everyone.
The Manifest¶
One file, one row per repository, and every row verifiable:
# portfolio.yaml — one row per repository
repositories:
- name: <repo>
owner: <who is accountable>
lifecycle: active | deprecated | retired
tier: <what it is allowed to break>
gate: <the command that proves its rows>
Cognitive load is the real budget. A human cannot hold twenty repositories, their owners and their states. Neither can an agent — and unlike the human, the agent will not say "I am not sure". It will read whatever it finds and act on it.
The Thinnest Viable Platform is the canon term for the right size: the smallest thing that answers the portfolio question, which is legitimately a curated file rather than software.
✅ What to Check¶
- Can you answer "what exists, who owns it, what state is it in?" from one file?
- Name a rule applied by memory in two repositories. That is the next registry row.
One fact changes shape at this scale, and it is not in the manifest: a restore replaces the project, not one schema. The suite shares one database, so recovering one service's data puts an older copy in front of every service that shares it — the blast radius of a data recovery is the project. That makes it a decision with a written case (chapter 25), never a repair command run by whoever noticed first.
2. The Source-of-Truth Model¶
A file becomes the source of truth when a command reads it and a check fails when it is wrong. Three properties:
- Every row is checkable — a named owner, a known tier, a real repository.
- Nothing else duplicates it — a second list (a wiki, a console) is a second truth.
- The gate reads it — the check is what makes the file authoritative.
Without the third property it is documentation; with it, it is state.
The Registers, Derived¶
| Registry | What it holds | Derived from |
|---|---|---|
| repositories | name · owner · lifecycle · tier | the manifest |
| ports | what is exposed, and where | the manifest + the services |
| surfaces | the public entry points | the manifest |
| environment variables | the names each service needs | the manifest |
Derived, not maintained. A registry edited by hand drifts from the manifest within a month — and the drift is invisible until a deploy fails on a variable nobody declared.
✅ What to Check¶
- Is any registry hand-maintained? That is the first drift.
- Does the gate read the manifest, or is the manifest a summary of the gate?
3. The Lifecycle Table¶
A lifecycle is a permission model: what a repository may do depends on where it is.
| State | Permits | Forbids |
|---|---|---|
| experimental | anything; no guarantees | public exposure |
| active | production traffic, on-call | unowned dependencies |
| deprecated | fixes, security patches | new features |
| retired | nothing; archived | deploys |
| planned | scaffolding, no traffic | production exposure |
The state is a row in the manifest, and the gate checks that a repository's behaviour matches it — a retired repository with a deploy pipeline is a finding, not an oversight.
✅ What to Check¶
- Does every repository have a lifecycle state?
- Is any retired repository still deployable? That is the gate's job.
4. The AI Delta¶
The manifest is an instruction to the agent, not a description for humans. A row that is missing is a decision the agent will make for you, confidently, and nobody will be able to check it afterwards.
An agent that can enumerate the estate will act on whatever the file says, at machine speed. That is why the file must be checkable by a command rather than readable by a person — a human notices an omission; an agent fills it in.
💰 Cost Check: a portfolio maintained by memory costs a question per repository per decision. A manifest costs the first afternoon and then pays on every question after it. The expensive failure is the row nobody wrote: the agent that adds a repository to the wrong tier, or the deploy that runs because a retired service still had a pipeline.
The Delegation Line¶
The agent reads the manifest, proposes rows, and derives the registries. The human owns the lifecycle and the tier — the two fields an agent must not set for itself. The system refuses a row without an owner, and refuses a registry without a schema.
The three subjects are different on purpose. An agent may propose that a repository is active; only a human may declare it.
5. Build the Delivery¶
Deliverables¶
| Artefact | Shape | Where it lives |
|---|---|---|
| portfolio manifest | one row per repository | portfolio.yaml |
| registry skeletons | one file per registry, stable ids | registry/*.yaml |
| lifecycle table | five states and their permissions | the manifest's documentation |
Decisions¶
| Choice | Default | What changes if you choose otherwise |
|---|---|---|
| where the source lives | one file, reviewed | per-repo fragments, which no single read can answer |
| what a row must carry | id · owner · lifecycle · tier | rows that cannot be checked |
| registries | derived, never edited | a second list that drifts |
| the lifecycle check | the gate | a retired service that still deploys |
✅ Gates¶
- The manifest validator refuses an unknown tier or a missing owner.
- The registry schema refuses a row without a stable id.
- A retired repository with a deploy pipeline is a finding.
Runbook¶
- Write the manifest for the repositories that exist. Checkpoint: every row has an owner and a tier.
- Derive the registries from it. Checkpoint: no registry row exists that the manifest does not imply.
- Wire the validator into the gate. Checkpoint: a planted bad row fails.
- Add the lifecycle column and the permissions it implies. Checkpoint: a retired deploy is a finding.
🎯 Proof¶
- A manifest that fails on a planted error.
- A portfolio question answered by one command.
- No registry maintained by hand twice.
6. 🔑 Chapter Summary¶
The portfolio question has one good answer: read the file, run the check.
- Rules become registries, procedures become rollouts, gates become policy — the same facts, in files.
- The manifest is the answer, and it is authoritative only when a command reads it and a check fails.
- Registries are derived, never hand-maintained — a second list is a second truth.
- Lifecycle is a permission model, and the gate enforces it.
- The agent reads the manifest as instruction — which is why an owner and a tier are a human's to set.