Methodology · v1.0
The ceremonies, values, and guardrails.
A shop manual, not a sales brochure. The full ceremony lifecycle, the six values that give it its spirit, and the six guardrails that make it enforceable. Each list is closed; nothing appears in both.
Artifacts
The three-artifact model.
Three deliberately distinct artifacts, unified by a shared node-identifier scheme rather than blurred into a single representation. Each answers a different question.
The Graph
What should exist. A structural representation of call shape and data shape, produced by deterministic analysis. Proposed before code is written; regenerated and diffed against that proposal once code exists; used as the live map once the system is deployed.
The Test Manifest
What should happen. A behavioral contract expressed in Given / When / Then form. Ordinary test semantics; not correlated to graph nodes by any shared ID scheme. Checked at the same gate as the graph, but as a separate, ordinary contract.
The Execution Trace
What actually did happen. A structured record correlated to graph nodes by stable IDs. Parent-span references reconstruct the call chain across distributed execution, so one user action reads as one trace, not a set of fragments.
Structural and behavioral correctness are different signals. Merging them into a single check makes each one less precise. The three-artifact separation is what lets the Fidelity Check fail for structural reasons and the test manifest fail for behavioral reasons, independently — and lets an engineer see which one broke.
Lifecycle
The ceremony lifecycle.
Three macro-phases, mapped explicitly onto Deming's Plan-Do-Check-Act. Each phase has a specific ceremony and a specific artifact; nothing advances until the artifacts agree.
Phase 1
Plan & Build
- Sketch. Fast comprehension check for small, low-risk changes. The agent edits a lightweight duplicate of the current graph; the human does an informal go/no-go. No formal sign-off.
- Blueprint. Full ceremony for larger or higher-risk changes: Brief → Survey → Calibration → Formalization. Ends with real sign-off. No code before this point.
- Build. Implement against the plan. Two independent gates run on completion.
Phase 2
Check & Handover
- Fidelity Check. Structural diff between the proposed graph and the regenerated graph from real code. Continuous, not a one-time gate.
- Punch List. Heavier staged review for higher-risk changes. Each remaining discrepancy is worked through one at a time.
- Handover. Deploy. Deterministic IDs injected into the running system; the graph becomes the live map.
Phase 3
Operate & Maintain
- In Service. Traces stream and correlate to graph nodes by stable ID. Ongoing, queryable record of real behavior.
- Service Call. Debugging grounded in what actually happened, not a stack-trace guess.
- Renovation. Refactoring guided by real usage rather than the original design alone.
- Walkthrough. Onboarding — human or agent — from graph + trace.
Non-negotiables
Definition of Done
- Blueprint sign-off before Build begins.
- Both Fidelity Check and Test Manifest green before a Gate Commit.
- Only a marker for coinciding with a verified checkpoint — incremental commits continue as normal.
- If a gate fails and the cause is the plan, return to Blueprint — not to another Build attempt.
Values
Six values.
These set the spirit the ceremonies are conducted in. They are not the ceremonies themselves — treat them as the terrain, not the map. Each traces back to a specific point in the Deming tradition; the discipline is not improvising a philosophy.
-
Build quality in; don't inspect it in after the fact.
The whole discipline exists to move the check earlier than a finished diff. (Deming, Point 3.)
-
Improve the system, forever — not the output of any one change.
The shape of the loop is Plan-Do-Check-Act. A single successful change is not the point; the point is that the process continues to hold.
-
Drive out fear.
A detected mismatch is useful information, not a verdict. The tool's language and behavior, not just this document, has to make that true. (Deming, Point 8.)
-
Symmetrical grounding.
Neither party in a human-agent pair is the infallible one. The codebase — read directly, not recalled from memory or training — is the arbiter for both. The agent's job includes correcting the human's stale assumptions; the human's job includes noticing when an agent's confidence has outrun its evidence.
-
Constraints before requirements.
An agent given its guardrails first reasons better than one given them as an afterthought. This ordering, tried repeatedly, produces better results than the more natural instinct of stating the goal first.
-
The methodology stays free and open.
Vendor-neutral, versioned, citable, disagreeable. The discipline is not the product. Whatever commercial tooling gets built on top of it sits alongside it, never in front of it.
Guardrails
Six guardrails.
Values are the terrain. Guardrails are the fences. These are the concrete, operational rules that decide what the tool will refuse to do — not the philosophy behind them.
-
No gate-skipping.
Blueprint needs sign-off before Build starts. Build needs both Fidelity Check and the Test Manifest to pass before a Gate Commit. The gate runs in a pipeline the agent under evaluation cannot alter, and its pass/fail is delivered through a channel the agent cannot fabricate or bypass.
-
The graph's scope stays strict.
Structure only — call edges, containment, inheritance, data shape. Never behavior. Behavioral correctness belongs to the test manifest. Mixing the two makes each weaker; keeping them separate is the point of having both.
-
Diagnostic signals are never quotas.
Fidelity Score and every signal like it exists for the human-agent pair doing the work — never for ranking people, teams, or vendors. Every diagnostic this discipline produces is a signal for the pair, not a management metric. (Deming, Point 11.)
-
The Lexicon is real, not decorative.
A living glossary of the terms, module names, and patterns the codebase actually uses — extracted during Survey, adopted during Calibration. If a human's own vocabulary drifts from the Lexicon mid-Blueprint, that's a real signal worth stopping for, not pedantry.
-
The human keeps stop-and-redirect authority.
At every ceremony, always, regardless of how much of the loop becomes automatable over time. This is not a fallback — it is a design assumption. Human oversight is concentrated at Blueprint sign-off and gate checkpoints, not exercised continuously.
-
The discipline checks build-matches-proposal — not proposal-matches-truth.
A deliberately deferred scope boundary, not an oversight. Adjudicating whether the spec itself was correct stays out of scope for now: the tool's job is to make disagreements visible, not to decide who's right. That leaves "who's right" as a human judgment call — which is exactly where human judgment is still needed.
Shop Rules
The cross-cutting policy.
Shop Rules are the standing policy governing which ceremony a change requires (Sketch vs. Blueprint), where an agent may propose changes unsupervised versus needs a human in the loop, and how the handoff protocol works day to day.
Shop Rules are not the methodology. They are what each team writes for itself on top of the methodology. The methodology prescribes artifacts and ceremonies; Shop Rules prescribe the org-specific thresholds and behaviors that bind them to a specific codebase, team, and risk appetite.
Shop Rules should not be treated as a substitute for Fidelity Check. Recent research on instruction-following shows adherence degrades substantially as constraint count or density grows — and that under some conditions, explicitly telling an agent to avoid a behavior can measurably increase its frequency.
Shop Rules are important for coordination and clarity. They are not the mechanism that catches drift. That is what the Fidelity Check is for. See problem classes for the research behind this.
The full lifecycle, at a glance.
Plan & Build feed the Fidelity Check. Check & Handover feed In Service. Operate & Maintain feed the next Sketch or Blueprint. The loop does not close — it continues for as long as the system runs.