D.8 Brownfield Migration Drill
Most organizations already possess fragments of a Governed Engineering Environment: documentation, tests, review rules, CI checks, ownership files, runbooks, deployment policy, and expert knowledge. Brownfield migration asks three questions: Which engineering knowledge needs stronger representation? Which obligations already have effective authority? Where do gaps still force people to reconstruct what the environment should know?
When a wiki carries important system knowledge, link its claims to the implementation and evidence they concern. Check mechanically decidable claims automatically. Give stronger structure only to knowledge whose future use justifies the cost. Chapter 4.2 gives the full treatment.
Joining the wiki to the code
Four additions can make a wiki a more trustworthy engineering entry point. Add them only where future use justifies the added maintenance burden.
| Element | Required behavior |
|---|---|
| Bidirectional links | Wiki pages name the code and tests that back their claims; code and tests name the pages that explain their purpose. This bidirectional relation provides traceability between claims and the implementation or tests that support them. |
| Agent briefs | Tell agents how to locate, traverse, cite, and maintain the relevant wiki material. |
| Design templates | Name the wiki pages the work touches, and record when a missing page has to be created, before implementation begins. |
| Definition-of-Done checks | Before work is accepted, compare affected pages with the current repository rather than relying on the agent's report that they were updated. |
Add metadata only when a defined consumer uses it. Tags, backlinks, ownership fields, and machine-readable mirrors should feed an audit, brief, retrieval step, analysis, or gate; otherwise they add another surface that can drift.
The migration path
The migration has four stages—Audit, Synchronize, Govern, and Extend—and each has an exit criterion. Advance when the criterion is met, not when enough time has passed.
| Stage | Work | Exit criterion |
|---|---|---|
| Audit | Inventory important engineering knowledge, implementation surfaces, and existing controls. Classify which claims have evidence or authority, which rely on convention, which disagree with the system, and which implementation regions legitimately fall below the grain of any useful explicit model. Keep this stage advisory. | Important gaps are classified rather than merely counted. |
| Synchronize | Repair high-value correspondence during ordinary work. When an agent or engineer touches a linked surface, re-check nearby claims, repair stale anchors, and surface semantic disagreements explicitly. | The representations you intend to trust have explicit, credible correspondence to their subjects. |
| Govern | Give selected obligations authority at the earliest boundary where the required property is decidable. Some obligations can be checked directly over artifacts or actions; others depend on the representations strengthened in earlier stages. | The high-value obligations selected for governance no longer depend primarily on someone remembering to inspect them. |
| Extend | Add richer representations, broader evidence, stronger mechanization, or additional authority only where expected return exceeds carrying cost. | Every addition has a named consumer or engineering question and a stated reason to exist. |
The promotion rule
Audit → reconcile → trust → govern → extend selectively.
Do not give an inaccurate representation authority. Do not require an explicit model where a local control already settles the obligation economically. Do not add structured metadata without a defined consumer. Add structure only when it is worth the cost: it should reduce repeated reconstruction or bring an important obligation under control.
Orphan triage
Classify each unlinked region into one of three states so coverage reflects the intended model grain rather than raw implementation count.
- Missing representation — a real subsystem with no explaining page or model; write or propose one.
- Missing anchor — the representation exists, but the link back from the code is absent; add the join.
- Below the grain — implementation too fine-grained or generic to warrant its own representation, such as typed-ID aliases, configuration loaders, or enums.
See Chapter 4.2 for top-down and bottom-up model construction, lint-and-cover preparation, the Missing-Model Metric, and cost-based governance sizing.