Software delivery doctrine public edition 62 rules, 28 earned from 21 distinct incident keys Core version 0.2, revised 2026-09-11 · volatile layer verified 2026-09-11 · page generated 2026-09-11
AI in the Software Lifecycle
How to use AI well at every stage of software delivery, greenfield and legacy, embedded to cloud, with every rule stamped by the evidence that earned it.
EarnedIncident-backed. Traces to a real, dated failure or outcome and generalizes. Dogma.
ReasonedFirst-principles. Sound case, not yet tested against a real incident. Provisional.
SpeculativeA cheap bet. Kept because it costs little and might pay off. Says so.
A doctrine for using AI well across the software development lifecycle. It is written to be adopted by any practitioner or organization: no single AI tool is the hero, and no single system is the subject.
Its authority comes from real incidents, not from a theory of AI in software. Every rule is stamped by three independent auditors: how justified it is (earned, reasoned, speculative), how general it is (neutral core, or a context-specific overlay), and where it came from and whether it is safe to publish. Rules the evidence has not yet earned are labelled so, explicitly.
Evidence base, stated plainly: 37 of the 62 rules cite the reference environment: an instrumented software delivery environment whose recorded incidents form the evidence base. The rest cite published industry sources verified live on the dates shown, rest on a single practitioner's account (labelled and ranked lowest), or are labelled hypotheses. The earned rules rest on 21 distinct incident keys, not 28; several rules share one event, one key is undated, and two keys name a family of related incidents rather than one. The spine is durable. The volatile layers at the end are dated and must be re-verified on read. Each rule opens with its statement; the receipt (cost, payoff test, evidence) unfolds beneath it.
A rule can come from a recorded incident and still be stamped reasoned: the provenance label says where a rule came from, the stamp says how much that event proves. Terms used throughout (escape, harness, incident key, greenfield, brownfield, context fill, and the doctrine's own words) are defined in the glossary in the volatile layer.
Use this document as a rules or constitution file for an AI development tool: keep it whole, keep the stamps, and add an overlay section of your own for organization-specific calibrations rather than editing the core.
·
Spine: cross-cutting principles
12 rules
The small durable core. These do not move when models or tools change.
1.earnedneutral corefield incident
The guarantee lives outside the model
A prompt only requests a property (stay in scope, be neutral, do not invent). The guarantee must live in the system around the model: a gate, a diff, a script that pulls evidence, a tool removed by the harness, a model chosen by configuration. Every real safeguard has a non-prompt backup.
Models comply probabilistically. Anything that must hold every time cannot be left to instruction alone.
Receipt: cost, payoff test, evidence
Cost to keep
medium, enforcement is code that must be tested and maintained.
Payoff test
For any safeguard, remove the prompt wording and keep the mechanism; the property must still hold. Outcome: count of policy violations that reached a real target per quarter, before and after the mechanism.
Outcome measure
violations reaching a real target (privacy leak, premature edit, unsafe command) per quarter.
Known limit
A text-based command guard has an obfuscation floor it cannot cross. Adversarial rounds keep finding new evasions, and static checks cannot resolve paths built at run time; so the tool-level deny rules are the real boundary and the text guard is defence in depth. And when false-positive cost is high, an advisory nudge can beat a hard block: one hard-blocking guard over-fired and was withdrawn before it was wired. Enforcement outside the model is necessary, not sufficient, and must be placed where it cannot over-fire.
Mechanism
harness-level tool scoping; pre- and post-action guards that can block; deny rules; configuration-selected models; freeze-proofs (a cryptographic fingerprint of the untouched facts, checked after every regeneration) and diffs.
Evidence
Two recorded cases. A never-read rule that lived only in instructions was bypassed by a recursive search, and held only once a pre-execution filter and an output filter existed. Later, a judging agent had its tools restricted at the harness level rather than by instruction, after the risk of steering it through what it reads was named.
2.earnedneutral corefield incident
Authority comes from incidents, not theory
Every rule traces to something that actually happened (an incident, a measured outcome) or is labelled unproven. Industry-norm vetting is a cross-check, never the primary source of authority. The doctrine stays thin and evidence-cited by design.
An AI-in-software doctrine built from polished theory reads as hype and cannot be falsified.
Receipt: cost, payoff test, evidence
Cost to keep
medium, every rule needs a receipt, which slows authoring.
Payoff test
Sample ten rules quarterly; each must resolve to a dated event or carry an unproven label. Outcome: time-to-diagnose on incidents where a rule was consulted, versus incidents where an uncited assertion was followed.
Outcome measure
time-to-diagnose; count of diagnoses steered wrong by an uncited assertion.
Evidence
A multi-day outage was prolonged by a design comment that stated a cause without evidence; everyone treated it as fact. The rule that followed requires every design-rationale comment to cite its evidence.
3.earnedneutral corefield incident
A durable core, dated volatile layers
Keep a small set of principles that do not move, and regenerate everything time-sensitive (per-tool guidance, capability ratings, the local-vs-cloud line) as dated, verify-on-read layers. Version the doctrine; every change to a volatile layer cites the evidence for the move.
Tool citations rot within months; principles do not. Mixing them makes the whole document look stale the first time a tool renames a feature.
Receipt: cost, payoff test, evidence
Cost to keep
low, a version line and a changelog.
Payoff test
Six months on, count how many principle cards needed substantive edits versus volatile entries. Outcome: principles changed by wording only, and no reader-reported stale claim in the core.
Outcome measure
substantive edits to the core per half-year; stale-claim reports.
Evidence
Model-selection policy in the evidence base is kept as a dated, evidence-cited document re-issued at each model release. A tool named in an early draft of this doctrine had been renamed months before the draft was written.
4.earnedneutral corefield incident
Sensitive artifacts never leave the machine
Proprietary or IP-bearing artifacts are processed only by models that never send them off the machine, where local capacity exists; where it does not, the same control becomes a contractual and procurement requirement. Keeping private data out of the model's context is a privacy control before it is a cost control. Anything that touched a secret is treated as exposed and rotated.
For crown-jewel code this is not a cost choice; it is the only option. A secret read routinely by an assistant is sent to the provider on every session.
Receipt: cost, payoff test, evidence
Cost to keep
high, a fenced boundary to police and, where used, a local model tier to run.
Payoff test
Audit a month of cloud requests: zero may contain a fenced artifact. Outcome: fenced artifacts found in outbound context per audit (target zero), and time from exposure to rotation.
Outcome measure
fenced artifacts in outbound requests; exposure-to-rotation time.
Evidence
A secret was found in a configuration file the assistant read routinely, so every session had already sent it off the machine; it was moved out, the path was fenced, and the secret was rotated.
5.earnedneutral corefield incident
Context discipline is a first-class practice
Feed the model only what the task needs; structure and cache stable context; keep private data out of the window entirely. Watch context growth and wind down or hand off before quality degrades, at a fill threshold set per harness and per model, rather than letting a session drift.
Both cost and privacy hinge on what enters the window; and long autonomous runs degrade silently past a fill level.
Receipt: cost, payoff test, evidence
Cost to keep
low, a guard and a habit.
Payoff test
Below the block threshold, measure drift symptoms (re-reads, contradictions, dropped instructions) per fill decile; on low-stakes work, raise the threshold deliberately for one week and compare. Outcome: defects and rework per unit of work by fill decile.
Outcome measure
rework and defects by context-fill band.
Evidence
An unattended AI session ran far past its intended context fill before anyone noticed; a hard threshold now blocks new autonomous work past a fill level.
6.earnedneutral corefield incident
Secrets never enter the window, and anything that touched one is rotated
Anything that touched a secret is treated as exposed and rotated, the same day. Exposure is a rotation event, not a risk discussion: a model will inline a key it has seen, and a transcript or log that held one has already shipped it.
Both cited exposures ended in a same-day rotation, and rotation belongs in a rule, not in the incident's footnote.
Receipt: cost, payoff test, evidence
Cost to keep
low, a scanner on both directions.
Payoff test
Count exposures that were NOT followed by rotation within a day (target zero). Outcome: exposure-to-rotation time.
Outcome measure
exposure-to-rotation time.
Mechanism
Proposed, not yet built in the evidence base: a credential-shape scanner on inbound context and outbound diffs, so the rotation event is raised by a mechanism rather than by someone noticing. Until it exists the reflex is the rule.
Evidence
Two recorded credential exposures were each followed by a same-day rotation; the rule makes that reflex mandatory.
7.reasonedneutral corepractitioner-sanitized
Route by capability only after routing by sensitivity
After sensitivity is settled (rule 4), route by capability: bounded, high-frequency mechanical tasks to a local model; frontier reasoning, novel architecture and synthesis to the strongest available model. A remote model may plan at the abstract level: it sees the specification, never the confidential material itself. Re-draw the line, with dated evidence, as local models improve.
The capability gap is real today and moves; the boundary rule keeps the crown jewels out of the planner's view regardless of where the line sits.
Receipt: cost, payoff test, evidence
Cost to keep
medium, two model tiers.
Payoff test
Quarterly, re-run a fixed task set on the current local and remote models; move the line when local matches remote on a task class. Outcome: task classes moved local per year, with no rise in rework on them. Retire the boundary rule (never the sensitivity rule) if two consecutive quarterly re-runs move no class and local matches remote on all of them.
Outcome measure
task classes served locally; rework on moved classes.
Evidence
Practised policy; the split point has not been measured against an alternative.
8.reasonedneutral corehypothesis
Automate the toil, augment the judgment
Sort every lifecycle activity into toil (bounded, repetitive, mechanical) or judgment (novel, high-stakes, ambiguous). Delegate toil fully to AI with human spot-checks; keep humans leading judgment with AI assisting. Win over a skeptical expert by naming their irreplaceable zone and handing back their hours, not by threatening it.
It reframes "how much can AI do" from a turf fight into a sorting task, and it is where AI is most credible today.
Receipt: cost, payoff test, evidence
Cost to keep
low, a classification habit.
Payoff test
Track expert hours before and after delegating a named toil item (harness upkeep, log parsing, regression re-runs); the rule pays if hours move to judgment work without a rise in escaped defects over two quarters.
Outcome measure
expert hours on toil; escaped defects.
Cross-check
Google SRE "toil" definition and the toil cap, supports; see the industry cross-check record, item 8.
Evidence
Practised routing policy in the evidence base: mechanical file work to the cheapest model, adversarial review to the strongest.
9.reasonedneutral corehypothesis
Three auditors, one job each
Three auditors, one job each. The rationale auditor asks how justified a rule is (earned, reasoned, speculative, with cost-to-keep and a falsifiable payoff). The core-vs-branch auditor asks how general it is (neutral core, or a context-specific overlay). The provenance and safety auditor asks where it came from and whether publishing it is safe. Never let one auditor do two jobs. One reviewer, human or AI, can run all three checks; the rule is that the questions stay separate, not the people.
One overloaded checker keeps a company-specific rule in the neutral core because it "felt earned": a placement call contaminated by a justification call. The same contamination shows up whenever authors grade their own rules: flagship rules get stamped earned against the evidence file's own grade, in the flattering direction, until an independent reviewer catches it.
Receipt: cost, payoff test, evidence
Cost to keep
low, three short fields per rule and a mechanical equality check.
Payoff test
Over the next four revisions, count stamps the grade-equality check forces to change or to carry an overrule line. Outcome: zero silent over-claims found by later adversarial passes.
Outcome measure
over-claims found by an independent pass per revision.
Evidence
An independent review of a first-draft rule set found rules stamped stronger than the evidence file graded them; an equality check between stamp and evidence grade now runs at build time.
10.reasonedneutral corefield incident
Never assert tool, model, version or vulnerability facts from memory
Any claim about a specific tool's feature, a model's capability, a version number or a security advisory is verified live against the source before it is written, and carries the date it was checked. Unverifiable claims are marked as such, never guessed.
These facts change monthly and models are trained on stale snapshots; a confidently wrong feature name discredits the whole document.
Receipt: cost, payoff test, evidence
Cost to keep
medium, every tool claim costs a fetch.
Payoff test
Re-verify a random five tool claims monthly. Outcome: number already wrong when written (target zero), and hours lost to a stale claim per quarter.
Outcome measure
stale claims per sample; hours lost to a stale claim.
Evidence
One recorded case: a behaviour change was blamed on the model for most of a day; the tool had auto-updated, and its own changelog explained the change.
11.reasonedneutral coreindustry-cited
Tool-neutral, not tool-equal: grade guarantee versus request
The doctrine is a constitution of tool-neutral principles; each tool gets a cited implementation, never a starring role. But do not abstract into mush: every serious tool converges on a persistent plain-language rules file plus enforcement outside the model. Grade each tool on how much of each principle it can guarantee (block outside the model) versus merely request (advisory), and do not pretend parity.
A doctrine that becomes one tool's torchbearer dies with that tool; one that flattens all tools to "write down your rules" says nothing.
Receipt: cost, payoff test, evidence
Cost to keep
medium, re-verify per tool release.
Payoff test
Two tools rated identically on a principle must enforce it in the same class of mechanism (both block outside the model, or both merely request); an identical rating over a different mechanism class is a finding, not a footnote. Outcome: reader-reported wrong grades per revision, and the number of grades that changed on re-verification.
Outcome measure
wrong grades reported; grades changed on re-check.
Evidence
See the tool scorecard in the volatile layer, verified against official documentation on the date shown.
12.reasonedneutral corehypothesis
Use neutral vocabulary and ship a glossary
Write principles in neutral terms (rules file, out-of-model enforcement, pre- and post-action guards, specialized sub-agents, gates) and ship a glossary mapping each neutral term to each tool's own name for it, and defining the doctrine's own terms. Never smuggle one tool's word in as if it were generic.
Vocabulary is how a tool becomes the hero without anyone deciding it.
Receipt: cost, payoff test, evidence
Cost to keep
low.
Payoff test
At every build, scan every core field the public edition renders (statement, why, mechanism, payoff test, outcome, known limit) for any tool's proprietary term; the generator runs it. Cross-check and evidence lines are exempt because rule 11 requires them to cite tools by name. Outcome: hits per build (target zero) and reader confusion reports on undefined terms.
Outcome measure
proprietary-term hits per build; undefined-term reports.
Evidence
The glossary in the volatile layer; the generator scans the core for vendor terms on every build.
1
Intake & scoping
3 rules
Before anything is built: who it is for, the weakest assumption, and whether the premise survives a poke.
13.reasonedneutral corefield incident
Pressure-test the premise before scoping closes
Before any build, answer in writing: who is it for, what is the weakest assumption, and what would count as validation theater: activity that looks like evidence but is not (agreement, enthusiasm, a show of interest). Call out research that has become avoidance. Only then commit. Once committed, commit fully.
Most wasted builds were doomed at the premise, not at the code.
Receipt: cost, payoff test, evidence
Cost to keep
low, one page.
Payoff test
Every retired tool's retrospective names which premise question would have caught it, or admits none would. Outcome: share of builds retired unused, before and after the questionnaire, over a year.
Outcome measure
builds retired unused per year.
Evidence
A long research effort produced nothing, and a self-audit found the assistant had never questioned the premise; a written pre-build questionnaire now gates every build. More than one later build was retired unused; whether the questionnaire would have caught them has not been checked.
14.reasonedneutral corepractitioner-sanitized
Open every build with the strongest reasoning available
The intake (scoping, premise test, the first architecture sketch) is the reasoning that matters most in the lifecycle. Spend the strongest model there, and spend cheaper models on the later stages according to what each stage needs.
Errors at intake compound through every later stage; errors in execution are local.
Receipt: cost, payoff test, evidence
Cost to keep
medium, the strongest model is the most expensive.
Payoff test
Compare rework volume for builds opened on the strongest model against builds opened on a mid-tier one. Outcome: rework hours per build, net of the model cost differential.
Outcome measure
rework hours per build.
Evidence
Standing policy: new builds are scoped on the strongest available model, then handed down. Not yet measured.
15.reasonedneutral corefield incident
Ask the process weight before executing a designed change
"Do it" answers whether, not how heavy. Before executing an already-designed change, state the process weight in one line (full pipeline, lean, or straight to code) instead of inheriting the project's default ceremony.
Running the full ceremony on a cosmetic change wastes the effort of a full pipeline; skipping it on a schema change loses far more.
Receipt: cost, payoff test, evidence
Cost to keep
low, one sentence.
Payoff test
Log the weight chosen and the outcome for twenty changes. Outcome: hours spent on process for changes later judged trivial, and escaped defects on changes run lean.
Outcome measure
process hours on trivial changes; escapes on lean changes.
Evidence
A cosmetic change was pushed through the full build pipeline; the rule now asks the process weight in one line first.
1b
Legacy on-ramp (spec mining)
7 rules
Brownfield only. A legacy system cannot start from a spec; it must reconstruct one first.
16.earnedneutral corefield incident
A mined spec is a hypothesis, not truth
A specification reverse-engineered from legacy code is an inherited theory. Falsify it against the running system (tests, production behaviour, a working peer) before anything is built on it.
Inherited theories rot; evidence does not.
Receipt: cost, payoff test, evidence
Cost to keep
low, one falsification test per mined claim.
Payoff test
Track mined claims that failed falsification. Outcome: escaped defects traced to a mined claim that was never tested (target zero); a zero failed-falsification count over many changes means the test is not being run.
Outcome measure
escapes traced to untested mined claims.
Evidence
The rule that any inherited explanation must be falsified before it is acted on came from a multi-day outage in which a stale explanation was believed instead of tested.
17.reasonedneutral coreindustry-cited
Brownfield cannot start from a spec: it must mine one first
Spec-driven development, as framed, assumes a spec exists and is written first. A legacy system has none, or a rotted one; its real spec is smeared across code, tests, tickets, tribal knowledge and production behaviour. Prepend a spec-mining phase that reconstructs only the slice of spec a change needs, verify it, then proceed spec-first on the change. Mining also manufactures the missing "as-is" baseline: the only way a legacy system can enter the intent-closure loop (rule 24, rule 58) at all.
Turns "legacy is not suited to spec-driven work" into a workable on-ramp, and gives the legacy reader a route into the requirements and closing rules.
Receipt: cost, payoff test, evidence
Cost to keep
medium, mining is real work per change.
Payoff test
On legacy changes, compare defect escape with and without a mined-and-verified slice spec over twenty changes. Outcome: escaped defects per change.
Outcome measure
escaped defects per legacy change.
Known limit
The payoff test cannot run in the evidence base, which is greenfield; it is owned by the first adopting organization with a legacy estate, with a review date of 2027-09.
Cross-check
Reverse-engineering taxonomy (Chikofsky & Cross) and characterization tests (Feathers): supports. Spec Kit, PARTIALLY: its philosophy document is greenfield-framed, but its "Adopting Spec Kit in an Existing Project" guide (verified live 2026-09-04) scopes the spec to one reviewable change and derives the constitution from existing evidence; it does not falsify the mined slice. See the industry cross-check record, item 5 (with correction).
Evidence
Derived from the reverse-engineering and design-recovery literature and from spec-driven toolkits' own framing; see the industry cross-check.
18.reasonedneutral corepractitioner-sanitized
Separate behaviour from intent, and keep a human on intent
Code is high-confidence on what a system does and low-confidence on what it was meant to do; it enshrines old bugs as requirements if allowed to. Tag every mined requirement as observed-behaviour or inferred-intent, and route every inferred-intent item through a human who decides: intended, bug kept for compatibility, or bug to fix.
A strange branch may be a defect or a load-bearing edge case nobody remembers.
Receipt: cost, payoff test, evidence
Cost to keep
medium, human review per inferred item.
Payoff test
Count inferred-intent items later reversed by a human, and escaped defects that were "requirements" mined from a bug. Outcome: bug-enshrined-as-requirement escapes per legacy change.
Outcome measure
escapes caused by mined bugs treated as requirements.
Known limit
The payoff test cannot run in the evidence base, which is greenfield; it is owned by the first adopting organization with a legacy estate, with a review date of 2027-09.
Evidence
An unverified single-source account: in long-lived systems the "why" layer is the weakest source, so intent is treated as a human decision rather than a mined fact.
19.reasonedneutral corepractitioner-sanitized
Trust running code first, tests next, records half, memory least
When mined sources conflict, rank them: running code is ground truth; passing tests are near-equal but only for what they cover; tickets and change history record the fix and rarely the why; human memory is sparse and lossy. Exact weights are a per-organization calibration. This hierarchy applies to the doctrine's own sourcing too.
Gives mining a deterministic tie-break instead of an argument.
Receipt: cost, payoff test, evidence
Cost to keep
low.
Payoff test
Over twenty mined changes, if lower-ranked sources win more than one conflict in five against higher-ranked ones and are later shown right, re-order the hierarchy. Outcome: conflicts resolved wrongly by the hierarchy.
Outcome measure
wrong tie-breaks per twenty changes.
Known limit
The payoff test cannot run in the evidence base, which is greenfield; it is owned by the first adopting organization with a legacy estate, with a review date of 2027-09.
Evidence
An unverified single-source account; the numeric weights are organization-specific and not published.
20.reasonedneutral corepractitioner-sanitized
Mine narrowly: scope by blast radius, not by file
Do not reverse-engineer a whole legacy system up front. Mine the slice a change touches, and the slice is bounded by coupling: every caller, every shared-state reader and writer, every implicit contract the change can ripple to. Stop when the blast radius is traced, not when the local file is read.
Boiling the ocean never ships, and coupling is the dominant legacy failure mode; under-mining the blast radius walks straight into it.
Receipt: cost, payoff test, evidence
Cost to keep
medium, tracing coupling is the work.
Payoff test
Classify legacy defects by cause for a year. Outcome: share of escapes caused by hidden coupling, before and after adopting the stop rule.
Outcome measure
coupling-caused escapes per legacy change.
Known limit
The payoff test cannot run in the evidence base, which is greenfield; it is owned by the first adopting organization with a legacy estate, with a review date of 2027-09.
Cross-check
Spec Kit's existing-project guide (verified live 2026-09-04) independently converges on the narrow half: "start with a feature, bug fix, or modernization slice that can be reviewed independently"; the blast-radius stop rule is the doctrine's addition. See the industry cross-check record, item 5.
Evidence
An unverified single-source account of what goes wrong in legacy changes: coupling invisible from the change site dominates.
21.reasonedneutral corepractitioner-sanitized
The expert is the primary oracle; the gap to automation is the frontier
In legacy work an automated regression net usually exists, yet expert humans still catch a large share of defects by hand. Gate AI changes to legacy on expert testing, not merely an automated pass. Then characterize what experts catch (record and classify it), automate the mechanical part, amplify the rest with parsed logs and candidate causes, and let AI's change-autonomy grow as the automated net grows.
Names honestly where AI can and cannot yet be trusted, and gives a program for moving the line.
Receipt: cost, payoff test, evidence
Cost to keep
medium, characterizing expert catches is ongoing work.
Payoff test
Measure the share of defects caught by automation versus experts quarterly. Outcome: automated share rising with escapes flat or falling.
Outcome measure
automation's share of caught defects; escapes.
Known limit
The payoff test cannot run in the evidence base, which is greenfield; it is owned by the first adopting organization with a legacy estate, with a review date of 2027-09.
Evidence
An unverified single-source account: the automated suite catches known-behaviour regressions; experts catch the novel, integration-coupled issues.
22.speculativeneutral corehypothesis
Reconstruct the code-to-defect link
Because code rarely cites the defect it fixed, a high-value automatable task is re-establishing which change fixed which defect and why, from code, commit history and tickets. This recovers the missing "why" layer and feeds the root-cause loop.
The why-gap is the weakest layer in every legacy trust hierarchy.
Receipt: cost, payoff test, evidence
Cost to keep
low, an analysis job, not a process.
Payoff test
Run it on one module by a fixed date; promote to reasoned if the recovered links change at least one mining decision or catch one intent error; retire if two runs change nothing. Outcome: mining decisions changed.
Outcome measure
mining decisions changed by recovered links.
Evidence
Untested hypothesis, stated as such.
2
Requirements
3 rules
The intent baseline the whole lifecycle is later diffed against.
23.earnedneutral corefield incident
Tag facts apart from framing in generated documentation
In every generated document, mark which spans are facts (frozen, never regenerated) and which are framing (mutable, audience-dependent). Only framing is ever sent to a model for regeneration; a freeze-proof (a cryptographic fingerprint of the fact spans) is checked after every run.
This is the precondition for audience views that cannot contradict the source.
Receipt: cost, payoff test, evidence
Cost to keep
medium, authors must mark spans.
Payoff test
The freeze-proof must match after every regeneration; cite the run count. Outcome: fact contradictions between generated views and source found by readers (target zero).
Outcome measure
reader-found fact contradictions.
Evidence
A document engine in the evidence base regenerates only marked mutable spans and proves the untouched facts byte-identical after every run.
24.reasonedneutral coreindustry-cited
Open with a one-page statement of intent
Every lifecycle opens with a one-page statement of intent (who, why, what done looks like, and the maximum investment before it is killed) kept as the baseline that the closing diff is measured against.
Without a written baseline, silent de-scoping and undocumented additions are invisible at the end.
Receipt: cost, payoff test, evidence
Cost to keep
low, one page.
Payoff test
At close, the diff must be producible; count closes where scope drift was found by the diff. Outcome: de-scoped or silently added items discovered at close versus discovered later by users.
Outcome measure
scope drift found at close vs found later.
Cross-check
Amazon working-backwards / PR-FAQ, supports the intent-first half; see the industry cross-check record, item 1.
Evidence
Adopted from a published industry practice; practised as a build gate, with no recorded failure it prevented.
25.reasonedneutral corehypothesis
Apply fact-vs-framing tagging to the requirements document itself
Extend rule 23 upstream: mark the requirements document's facts and framing at authoring time, so every downstream view (and the closing diff) regenerates from frozen requirement facts.
If the requirements are not fact-tagged, audience views of them can drift even when the engine is sound.
Receipt: cost, payoff test, evidence
Cost to keep
medium.
Payoff test
Run the engine on one requirements document by a fixed date. Outcome: promote to earned if a freeze-proof holds across three regenerations; retire if authors will not mark spans.
Outcome measure
freeze-proof runs on requirements documents.
Evidence
Proposed extension of a proven mechanism; not yet exercised on requirements.
3
Design & architecture
6 rules
One fact-frozen source, regenerated into audience views; decisions recorded with their evidence.
26.earnedneutral corefield incident
One fact-frozen source, regenerated into views, cannot contradict itself
Keep one fact-frozen core and regenerate every derived document from it. A view generated from frozen facts cannot contradict the specification, because the facts were never sent to the model.
low once the engine exists; each view is near-free.
Payoff test
Adopt rule 23's test: the freeze-proof over fact spans, verified every regeneration, with the run count cited. Outcome: contradictions between a view and the core found by readers (target zero).
Outcome measure
reader-found contradictions.
Cross-check
Living documentation, supports; docs-as-code and the Diataxis framework partially support (they organize hand-written documents; the regeneration guarantee is this doctrine's addition). See the industry cross-check record, item 2–3.
Evidence
The same document engine; this doctrine's own editions are generated from one ledger by the same method.
27.earnedneutral corefield incident
Record settled decisions with their evidence, and surface them before edits
Keep a settled-decision log per system: the load-bearing rules, each citing the incident or measurement that settled it. Surface the relevant entries automatically before anyone edits a foundational file.
Settled decisions get re-litigated by people and agents who never saw the reason.
Receipt: cost, payoff test, evidence
Cost to keep
low, a log and a file map.
Payoff test
Count re-litigations of settled decisions before and after the surfacing guard. Outcome: hours spent re-deriving settled rules per quarter.
Outcome measure
re-derivation hours.
Cross-check
Architecture Decision Records, supports the log; the grading scheme is original to this doctrine; see the industry cross-check record, item 10.
Evidence
A per-system log of settled rules with citations, and a pre-edit guard that displays the relevant entries before a registry, launcher or configuration file is touched.
28.reasonedneutral corehypothesis
Regenerate role-specific audience views from the frozen core
From the one frozen core, regenerate role-specific views: hardware, product, leadership, test, customer. Same facts, different depth and vocabulary. Grade each view honestly: some are load-bearing, some are cheap lottery tickets kept because regeneration is near-free.
Each audience needs a different framing; regeneration makes that affordable, and honest grading stops "six views" being pitched as six pillars.
Receipt: cost, payoff test, evidence
Cost to keep
low.
Payoff test
Track opens per view for a year. Outcome: promote a speculative view if it triggers a logged idea or reference check; drop it if untouched for eighteen months.
Outcome measure
view opens; logged ideas triggered.
Evidence
Proposed application; the mechanism is proven, the audience set is not yet exercised.
29.reasonedneutral corehypothesis
Grade each decision's justification, with cost and a payoff test
Every design decision carries a justification grade (earned, reasoned or speculative) plus its cost-to-keep and a falsifiable payoff so it can later be promoted or retired. Cheap speculative items are legitimate keeps; hand-maintained ones are clutter.
Stops earned rules and hopeful rules masquerading as equals: the single failure that kills AI-in-software documents.
Receipt: cost, payoff test, evidence
Cost to keep
low, three fields.
Payoff test
After a year, at least one speculative item has been promoted or retired on its own test. Outcome: rules retired as never-paid-off, and rules promoted on evidence.
Outcome measure
promotions and retirements per year.
Evidence
The doctrine's own ledger is the first application; every card carries the three fields.
30.speculativeneutral corehypothesis
Audience views need a visibility layer, not just a framing layer
Freezing facts is not enough. Each audience view also needs a rule for what that audience may NOT see, enforced outside the model, or a customer view leaks the roadmap, internal trade-offs or the risk register.
Regeneration faithfully reproduces everything in the core, including what should not travel.
Receipt: cost, payoff test, evidence
Cost to keep
medium, a field per fact and a scan at build, plus an independent reader per edition.
Payoff test
Build a customer view with the visibility layer disabled and count what leaks; then have a reader who never saw the internal edition answer "who wrote this and where do they work?". Outcome: identifying details found per edition (target zero).
Outcome measure
identifying details found by an independent reader.
Evidence
A word denylist alone was shown by independent review to pass details that together could identify an author; an independent-reader check is the required second layer. That check has been run on this document's own public edition; the latest read returned a non-zero count of narrowing details, so the stamp stays where it is until a read returns zero.
31.speculativeneutral corehypothesis
Run the auditor as an AI pass that a human ratifies, checked by a script
The rationale auditor drafts as an AI pass; a human ratifies each stamp; a script verifies that every citation resolves and that every stamp equals the evidence grade or carries an explicit overrule. None of the three alone is sufficient.
An AI pass scales; a human catches motivated tagging; a script catches broken receipts and silent upgrades.
Receipt: cost, payoff test, evidence
Cost to keep
low.
Payoff test
Compare stamps from an unratified AI pass against the ratified set over two revisions. Outcome: if the human changed fewer than one in twenty, drop ratification to spot-checks; if more than one in five, the AI pass is not fit to draft.
Outcome measure
stamps changed at ratification.
Evidence
Proposed answer to an open question; the script half is built, the human half has not yet run.
4
Build
8 rules
Gated. Code does not start until its prerequisites are locked; strong models plan, cheaper models execute.
32.earnedneutral corefield incident
Gate code on locked prerequisites, mechanically
Code does not start until requirements, architecture and (where relevant) threat model are locked. The gate is enforced by a mechanism that blocks edits, not by a checklist the agent is asked to respect.
Agents and people both jump to code; a request to wait is ignored under pressure.
Receipt: cost, payoff test, evidence
Cost to keep
medium, a state file and a guard.
Payoff test
Leave the gate on. Compare rework and escaped defects on gated builds against the pre-gate baseline over a year. Outcome: rework hours per build.
Outcome measure
rework hours; escapes per build.
Known limit
A gate keyed on opt-in registration protects only work that already registered. In the evidence base the pre-code gate allowed edits whenever no build-state marker was found, so a tool built in a fresh folder bypassed it entirely, and the companion adversarial-pass rule never fired because no stage was ever locked. Design guards so the unregistered case trips them rather than passes.
Evidence
A build pipeline blocks code edits with a pre-action guard until the design stages are locked; the guard was added after checklist-only gates were skipped.
33.earnedneutral corefield incident
Ship every scheduled job or service with a working peer beside it
Every config-driven artifact (scheduled job, service definition, guard, workflow) ships with a minimal known-working peer of the same family in the same directory, so a failure can be diffed immediately.
Pre-wires the diagnosis path; removes the dependency on memory.
Receipt: cost, payoff test, evidence
Cost to keep
low, one file per family.
Payoff test
Time-to-diagnose for the next config failure with a peer present versus the historical baseline without one. Outcome: hours to diagnose.
Outcome measure
time-to-diagnose config failures.
Evidence
After a multi-day outage was diagnosed by diffing against a working peer, every scheduled job now ships with a minimal working reference beside it.
34.earnedneutral corefield incident
Verify a redirect took effect from inside the process
Before any write-capable process runs under a redirection (temp database, sandbox, staging endpoint, dry-run flag), verify from inside the process that the redirect is live; values computed at import time ignore overrides set afterward.
The process runs against the real target and nothing errors.
Receipt: cost, payoff test, evidence
Cost to keep
low, log the effective target at startup.
Payoff test
A canary run under redirection must leave the real target untouched; check the real target, not the log. Outcome: writes to a real target from a "redirected" process per year (target zero).
Outcome measure
real-target writes under redirection.
Evidence
A test process was pointed at a temporary data store through a late override; the target had already been fixed at start-up, and the test wrote to the real store.
35.earnedneutral corefield incident
Express enforcement rules in absolute, context-free form
Write deny and allow rules, path fences and any other guard in absolute, context-free form, and test enforcement from a drifted working context, not only from the default one. A rule whose meaning depends on ambient state (the current directory, an environment variable, the order of earlier calls) is state, not a boundary.
One directory change in one shell call silently disarmed an entire privacy fence written in relative form; nothing errored.
Receipt: cost, payoff test, evidence
Cost to keep
low, write the absolute form and add one drifted-context test.
Payoff test
For every guard, one test runs from a drifted context (a changed directory, a stripped environment). Outcome: guard bypasses traced to ambient state per year (target zero).
Outcome measure
bypasses traced to ambient state.
Evidence
A privacy fence written as relative paths was silently disarmed by a single directory change in one shell call, with no error; the same class recurred once more before the absolute-form rule and a drifted-context test were made standing practice.
36.earnedneutral corefield incident
One ownership contract, disjoint files, and every seam as a signature
In multi-agent work, publish one contract document naming file ownership, interfaces and constants; parallelize only across disjoint files; run an explicit integration pass over the seams; and express every seam as a signature, never as prose. Treat every interface the contract described in prose as a predicted defect site.
The seams that broke were exactly the ones the contract described in words rather than as signatures, in more than one build session.
Receipt: cost, payoff test, evidence
Cost to keep
medium, one contract document per build and an integration pass.
Payoff test
Classify every integration defect on a multi-agent build by whether its seam was a signature or prose in the contract. Outcome: integration defects per build, and the share at prose-described seams (a share that does not fall after the rule falsifies it).
Outcome measure
integration defects per multi-agent build; share at prose-described seams.
Evidence
Across several recorded multi-agent builds, the interfaces that failed at integration were the ones the shared contract had described in prose rather than as signatures; the pattern that held was one contract, disjoint file ownership per executor, and an explicit integration pass.
37.reasonedneutral corefield incident
A strong model plans, cheaper models execute: by purpose, never to save tokens
Orchestrate with a strong model writing specifications and cheaper models executing bounded pieces. Route by what each piece needs, not by cost. Work that needs top-tier reasoning stays there; security-critical work stays on the model trusted for it. Categories the organization has ruled off-limits for third-party processing are named in policy and excluded at the routing layer, not by prompt.
Cheap execution of a good spec beats expensive execution of a vague one; but downgrading to save money is how quality quietly leaks.
Receipt: cost, payoff test, evidence
Cost to keep
medium, orchestration overhead.
Payoff test
For a build where one strong model writes the specifications and cheaper models execute them, compare rework against a single-model run of similar size. Outcome: rework hours and escaped defects per build.
Outcome measure
rework and escapes per build.
Evidence
Practised delegation policy routes by purpose and forbids cost-driven downgrades; the claim that downgrades cost more than they saved has not been measured.
38.reasonedneutral corefield incident
Edit surgically; never rewrite what you can replace
Prefer exact-string replacement of the changed lines over rewriting whole files. Whole-file rewrites burn tokens, clobber concurrent edits, and hide the actual change from review.
A rewrite that re-emits hundreds of unchanged lines to change a handful is the commonest way an agent silently loses someone else's edit.
Receipt: cost, payoff test, evidence
Cost to keep
low, a habit.
Payoff test
Track tokens per applied change and review time per change before and after adopting the rule; it pays if both fall without a rise in escaped defects. Outcome: tokens per applied change; review minutes per change; escapes.
Outcome measure
tokens per change; review time per change; escapes.
Evidence
A shared log was being rewritten whole by one session while a parallel session appended to it; nothing was lost, but only by luck, and the rule followed.
39.reasonedneutral corehypothesis
Generated code carries a provenance obligation
Record which model produced which artifact; run the same licence and attribution scanning on generated code as on vendored code; hold a stated policy for near-verbatim reproduction of training material.
A doctrine written for organizations that says nothing about the licensing of emitted code will not survive its first legal review. The obligation is legal rather than empirical, and the doctrine says so.
Receipt: cost, payoff test, evidence
Cost to keep
medium, a scanner and a record per artifact.
Payoff test
Sample generated artifacts quarterly for unattributed near-verbatim reproductions. Outcome: findings per sample, and legal-review findings on AI-authored code. Retire if two years of sampling find nothing and no legal review has raised AI-authored code (review by end of 2028).
Outcome measure
licence findings on generated code.
Evidence
Added because the gap would fail a legal review; no incident behind it.
5
Verify & QA
8 rules
Claim never exceeds evidence. Audit to zero. A second, adversarial pass before any lock.
40.earnedneutral corefield incident
Claim never exceeds evidence: name the surfaces exercised
Before declaring anything done, list the surfaces the claim covers and the surfaces actually exercised, and name the gap. A screenshot proves rendering, not behaviour; a passing suite proves only the paths it drives; a direct API call proves the API, not the button. Drive the path the user will use, or downgrade the claim.
Rigor accumulates where tools can reach and the claim silently extends to where they cannot.
Receipt: cost, payoff test, evidence
Cost to keep
medium, a real-path exercise per claim.
Payoff test
Pre-register the surface list before each done-claim; count escaped defects that land on a surface that was listed but not exercised. Outcome: a rising count falsifies the rule's claim that naming the gap prevents the escape.
Outcome measure
escapes on listed-but-unexercised surfaces.
Evidence
A feature passed several pre-code audits and a large server-side test suite, and its first real button press failed silently: every audit predated the code and every test ran server-side.
41.earnedneutral corefield incident
Empty output is not success: check the artifact
A filtered command that prints nothing looks identical on a clean pass and on a crash. Verify the artifact changed (exit status, the new file, the row count, the specific expected value), never the absence of matched lines.
A search for the success marker finds nothing on a stack trace too.
Receipt: cost, payoff test, evidence
Cost to keep
low.
Payoff test
Every "it worked" claim cites the artifact observed. Outcome: silent failures discovered later than the run that caused them, per quarter.
Outcome measure
late-discovered silent failures.
Evidence
A generator crashed on bad input; its output was searched for a success marker, nothing matched, and "no matches" was read as success for an entire run.
42.earnedneutral corefield incident
Audit to zero, then run an adversarial second agent before any lock
Run the full audit suite and repeat it until no finding the team rates as blocking remains; then, before any stage lock or audit close, run a fresh adversarial pass by a second agent that did not do the work. Audit findings are verified before they are applied, never blindly accepted.
The author of work cannot see its blind spots; a second pass on a different model finds what the first rationalized.
Receipt: cost, payoff test, evidence
Cost to keep
medium, a second model run per lock.
Payoff test
Count blocking findings from the adversarial pass over ten locks; if it stays at zero, drop to sampling. Outcome: escaped defects on locked stages with and without the pass.
Outcome measure
blocking findings per pass; escapes after lock.
Evidence
Adversarial second-model reviews before architecture locks have found blocking issues the authoring pass missed, on several recorded occasions: double-digit findings in one design review, and several more inside a fully green test suite.
43.earnedneutral corefield incident
Falsify before you assert
State the belief as a testable claim, construct the test, run it, compare, and only then assert. Applies to diagnoses, inherited explanations, generative output (fix the seed first) and subjective quality (test against a fixed rubric, not one rendering).
One observation cannot falsify a stochastic or subjective claim; a fixed reference can.
Receipt: cost, payoff test, evidence
Cost to keep
low.
Payoff test
Record the falsification test for every fix; count fixes that regressed and lacked one. Outcome: regressions on untested fixes.
Outcome measure
regressions on fixes without a recorded test.
Evidence
An untested explanation was acted on for days during a multi-day outage; the rule now requires a one-variable falsification test before any fix, with special handling for generative and subjective outputs.
44.earnedneutral corefield incident
Verify security through the real channel, and read the library's own code
A silence or redaction test must emit through the real channel and assert the absence there; asserting that the silencing code exists proves nothing. For any "the library prevents X" claim, read the library's dispatch path, not its documentation.
Two real bypasses were found only when the actual path was exercised.
Receipt: cost, payoff test, evidence
Cost to keep
low.
Payoff test
Every security test names the channel it emitted through. Outcome: bypasses found after a "protected" claim, per audit.
Outcome measure
post-claim bypasses.
Evidence
In one security build, a redaction test that only checked the code existed passed while the real channel leaked, and a library's documented protection was bypassed through a facade its own dispatch path exposed.
45.reasonedneutral corefield incident
Restrict the judge's tools so the evidence cannot steer it
An AI that judges or audits reads evidence that may contain instructions. Scope its tools at the harness level to read and write only, so text inside the evidence cannot make it act.
Prompt injection through evidence is a guarantee-outside-the-model problem, not a prompt-wording problem.
Receipt: cost, payoff test, evidence
Cost to keep
low, an agent definition.
Payoff test
Plant an instruction in a test evidence file; the judge must not act on it; record the run. Outcome: injection attempts that changed a verdict (target zero).
Outcome measure
verdicts steered by planted instructions.
Evidence
A scoring agent in the evidence base is restricted by the harness to reading and writing, so that instructions hidden in the transcript it grades cannot make it run anything; the planted-instruction test has not yet been run.
46.reasonedneutral corefield incident
Treat every artifact an agent reads as untrusted input
Repository content, dependency metadata, tickets, fetched pages, pasted logs and tool output can all carry instructions. Fence or filter them before they enter an agent's context, and give any agent that reads untrusted content the minimum tool set that lets it do its job.
This is the dominant published attack class against coding agents, and the evidence base records one bite from it, filed at the time under privacy.
Receipt: cost, payoff test, evidence
Cost to keep
medium, filters at the boundary and per-agent tool scoping.
Payoff test
Plant instructions in a test repository file, a ticket and a fetched page; count agents that act on them. Outcome: actions taken on planted instructions (target zero).
Outcome measure
actions on planted instructions.
Evidence
A recursive search pulled protected content into an agent's context until a pre-execution filter was added; the general rule was only stated once an independent review pointed out it had been filed under privacy.
47.reasonedneutral corehypothesis
The agent that makes the test pass must not be free to change the test
Treat test files as a separate change class. An agent's diff to a test is reviewed on its own, and assertion and coverage counts are tracked as a tripwire against silent weakening: an edited assertion, a mocked failing path, a new skip, a widened tolerance.
The whole verify stage assumes the suite is an honest oracle; an agent that can edit the oracle defeats every other rule here at once.
Receipt: cost, payoff test, evidence
Cost to keep
low, a review rule and two counters.
Payoff test
Track assertion and coverage counts per merge, and compare the escape rate on merges that changed a test against merges that did not. Outcome: escape rate by merge class. Retire if two years show no difference (review by end of 2028).
Outcome measure
escape rate on merges that changed a test versus merges that did not.
Evidence
Added for a well-documented failure mode; no incident in the evidence base.
6
Release
3 rules
What ships is what was verified, and every accepted risk is said out loud.
48.earnedneutral corefield incident
State every accepted risk explicitly, when the choice is made
An audit finding chosen not to fix is stated explicitly at the moment of the choice, and recorded as accepted risk in the same place the fixes are listed. Filing it silently converts the decision-maker's call into the engineer's.
The decision-maker learned of an exposure afterwards, by accident.
Receipt: cost, payoff test, evidence
Cost to keep
low, one sentence.
Payoff test
Every audit close lists accepted items beside fixed items. Outcome: unfixed findings the decision-maker learned of after the close, per year (target zero).
Outcome measure
findings that surprised the decision-maker after close.
Evidence
An audit found an identifier in a log outside the team's control, recorded it as accepted risk in the written record only, and the decision-maker learned of it afterwards only by asking.
49.earnedneutral corefield incident
Never write private data down: describe the shape, not the contents
Counts and contents of personal or proprietary data never appear in journals, handoffs, trackers, commit messages or plan documents. Describe the shape ("the list renders"), never the contents (a count, a name, a figure). This applies to tool output as well as to prose.
Those files are read into context every session, so anything written there is re-sent forever.
Receipt: cost, payoff test, evidence
Cost to keep
low.
Payoff test
Grep the durable docs for counts and names of private data monthly. Outcome: private items found in re-read documents per audit (target zero), and re-sends prevented.
Outcome measure
private items in durable docs per audit.
Evidence
Private counts were found inside a session handoff note; the rule now forbids recording the contents of personal data anywhere that is re-read into an AI context.
50.reasonedneutral corepractitioner-sanitized
Provenance on every claim in advice and release notes
Factual claims in advice, release notes and audits carry a source tag: observed, inferred, or cited. An unattributed claim is treated as inferred.
Readers cannot weigh a claim they cannot source.
Receipt: cost, payoff test, evidence
Cost to keep
low.
Payoff test
Sample advice given in a week; every factual claim carries its tag. Outcome: decisions later reversed because an untagged inferred claim was taken as observed.
Outcome measure
reversals traced to untagged claims.
Evidence
Standing rule that advice distinguishes observed from inferred claims; adopted by ruling.
7
Operate & incident
6 rules
Survey the family, diff against a working peer, flip one variable, then fix and propagate.
51.earnedneutral corefield incident
Check the tracker before diagnosing
Before diagnosing any failure, search the issue tracker for the component and the symptom. The cause is often already logged, sometimes predicted.
A known failure re-diagnosed from scratch wastes the hours the record was written to save.
Receipt: cost, payoff test, evidence
Cost to keep
low, one query.
Payoff test
Log every incident where the tracker already held the cause. Outcome: hours spent re-diagnosing logged causes per quarter.
Outcome measure
re-diagnosis hours.
Evidence
A scheduled run reported a "new" outage that the team's own tracker had documented the previous day, including a prediction that this very workflow would fail.
52.earnedneutral corefield incident
If a tool changed and you did not, suspect a silent update
When a tool's behaviour changes and nothing was changed on your side, check the tool's version and changelog before blaming the model, usage limits or your configuration.
Auto-updating clients shift behaviour overnight with zero config change.
Receipt: cost, payoff test, evidence
Cost to keep
low.
Payoff test
Time from symptom to changelog read. Outcome: hours lost per tool-update incident.
Outcome measure
hours lost to unread changelogs.
Evidence
Hours were spent blaming a model for a behaviour change that the AI tool's own changelog explained.
53.earnedneutral corefield incident
Survey the family, diff a working peer, flip one variable, then fix
Before proposing any fix, three steps. One: list what else in the same family works, and say whether the failure is one instance, the family, or the whole system. Two: diff the failing artifact against the nearest working peer, listing every difference without pre-filtering. Three: build a minimal repro and flip exactly one variable. Destructive or system-wide interventions require step one to have shown system-wide failure.
A three-line local misconfiguration ran for days while a machine-wide reset was queued as the fix.
Receipt: cost, payoff test, evidence
Cost to keep
low, three commands.
Payoff test
Every destructive intervention is preceded by an on-the-record survey. Outcome: time-to-diagnose per incident, and destructive interventions later shown unnecessary (target zero).
Outcome measure
time-to-diagnose; unnecessary destructive fixes.
Evidence
The incident protocol was written after a small configuration error ran for days while a system-wide reset was the queued fix; a diff against a working peer found it quickly.
54.earnedneutral corefield incident
Treat identifiers in tool output as ambiguous until disambiguated
Bare basenames, short hashes, process ids and log substrings hide multiplicity. Before concluding "there are N of X" or "these are duplicates", re-run with a disambiguating signal: working directory, full arguments, full path, surrounding context.
Three same-named scripts in different directories were read as three copies of one service.
Receipt: cost, payoff test, evidence
Cost to keep
low, one more command.
Payoff test
Any identity claim in a diagnosis cites the disambiguating signal used. Outcome: actions taken on a wrong identity claim (a wrong process killed, a wrong file edited) per year.
Outcome measure
wrong-identity actions.
Evidence
A process listing in the reference environment showed three hits for one script name and was read as three instances of one service; they were three different services in three directories.
55.earnedneutral corefield incident
A fix is done when every artifact that referenced the bug is updated
Propagate every fix to the whole family before calling it done. That family is: the running processes (restart the consumer that cached the old value); the generators and templates that produce the artifact; the tests and the test plan (a regression test that fails on the old behaviour); the authoring docs and cheat-sheets people build from; and the contract, tracker and changelog. State the family swept.
A fix that leaves the cheat-sheet teaching the broken pattern is re-authored next session: the worst miss, because it looks done.
Receipt: cost, payoff test, evidence
Cost to keep
medium, the sweep is real work.
Payoff test
Any recurrence of a fixed bug traces to a family member that was not swept. Outcome: recurrences of fixed bugs per quarter.
Outcome measure
recurrences of fixed bugs.
Evidence
Two recorded incidents: a corrected configuration was ignored by a long-running launcher that had cached the old one; and a fix that touched code and spec but not the authoring cheat-sheet would have been re-authored next session.
56.reasonedneutral corefield incident
Treat the tracker as root-cause memory: failure becomes a rule
The issue tracker is not a task list; it is the organization's root-cause memory. Every incident is logged, root-caused, and propagated into a rule that prevents the next occurrence, and each rule records whether it is earned or hopeful, so the hopeful ones that never pay off can be retired.
A self-auditing knowledge base is the most valuable single export of an AI-assisted lifecycle.
Receipt: cost, payoff test, evidence
Cost to keep
medium, discipline to log and root-cause every incident.
Payoff test
Fraction of incidents whose tracker entry links to a rule change. Outcome: repeat incidents of an already-root-caused class per quarter.
Outcome measure
repeat incidents of root-caused classes.
Evidence
The evidence base's tracker is queried first in every incident and receives a post-mortem entry after every non-trivial one; several rules in this doctrine trace to entries there.
8
Close & retro
6 rules
Regenerate intent from what was built and diff it; every incident becomes a rule.
57.earnedneutral corefield incident
Post-mortem automatically, and propagate the lesson at the widest scope
Any incident that took more than trivial diagnosis gets a short written post-mortem without being asked: what broke, root cause with evidence, fix, wasted iterations, generalizable lesson. Decide the lesson's scope by asking whether it is really about this tool or a higher pattern; default to the widest scope, and check for existing coverage before adding a rule anywhere.
Lessons that stay implicit are re-learned at the next incident; narrow lessons do not compound.
Receipt: cost, payoff test, evidence
Cost to keep
low, five lines.
Payoff test
Every non-trivial incident has a post-mortem block in the same session. Outcome: repeat incidents of a class that already had a post-mortem, per quarter.
Outcome measure
repeats after a post-mortem.
Evidence
The rule to write a post-mortem unprompted came from a multi-day incident whose lessons would otherwise have stayed implicit.
58.reasonedneutral coreindustry-cited
Close the loop on intent: regenerate and diff
At close, regenerate the one-page statement of intent from what was actually built and diff it against the opening statement plus every addition made along the way. Silent de-scoping and undocumented additions surface as diff lines.
Nobody notices what quietly fell out of scope unless something forces the comparison.
Receipt: cost, payoff test, evidence
Cost to keep
low when the one-pager regenerates from the frozen core; medium if hand-written.
Payoff test
Build the mechanism on one project by a fixed date. Outcome: promote to earned if the closing diff finds a scope drift users had not reported; retire the continuous variant (rule 59) if two closes find nothing.
Outcome measure
scope drift found at close before users report it.
Cross-check
Infrastructure-as-code drift detection (declared vs actual), supports strongly, three vendors confirmed; see the industry cross-check record, item 7.
Evidence
Not yet built; the nearest practised analogue is a mandatory structural diff of a built artifact against its locked design before any "done" claim.
59.reasonedneutral corehypothesis
Run the intent diff at every gate where regeneration is free
The closing diff is the minimum. Where the one-pager regenerates from the frozen core at near-zero cost, run the same diff at every stage gate as a drift check; where a human must write it, keep it to the bookends.
Resolves whether intent-closure is continuous or a bookend: it is continuous exactly where it is free.
Receipt: cost, payoff test, evidence
Cost to keep
low where automated.
Payoff test
Promote to earned when a gate-time diff catches a scope drift before close; retire to bookend-only if two full projects run with gate diffs that never catch anything (by end of 2027). Outcome: drifts caught at a gate rather than at close.
Outcome measure
gate-caught drifts.
Cross-check
Infrastructure drift detection runs on every apply. See the industry cross-check record, item 7.
Evidence
Proposed answer to an open question, argued from cost; not yet exercised.
60.reasonedneutral corefield incident
Record the AI's advice at every decision, so deviation is traceable
At every decision point where an AI advised, record what it advised alongside what was decided. At close, it is then possible to say who deviated from whom, and why.
Without the record, every bad outcome becomes "the AI said" or "the human overrode" with no way to check.
Receipt: cost, payoff test, evidence
Cost to keep
low, a log line per decision.
Payoff test
At one retrospective, the record settles at least one "who chose this" question by end of 2026. Outcome: disputes settled by the record; if none by then, drop it.
Outcome measure
disputes settled by the advice record.
Evidence
One tool in the evidence base logs the engine's recommendation at every decision (hidden until the person has made their own call) so a later review can tell who deviated; no review has yet used it.
61.reasonedneutral coreindustry-cited
Measure delivery, not the feeling of speed; protect the judgment you rely on
Perceived productivity is a measured-unreliable instrument; track throughput and escape rate instead. Cap the volume of AI-authored change one reviewer accepts per period. Deliberately keep humans doing some work AI could do wherever their judgment is the named safety net. Otherwise the expert oracle the legacy stage depends on stops being trained.
A published randomized trial found experienced developers slower with AI tools while believing they were faster; and the legacy on-ramp assumes an expert oracle that has to come from somewhere.
Receipt: cost, payoff test, evidence
Cost to keep
medium, a review cap and a protected-work policy.
Payoff test
Track reviewer acceptance volume, escape rate on AI-authored changes, and the share of defects caught by expert judgment over a year. Outcome: escapes per accepted AI change; the expert-caught share counts as collapsing if it falls by more than a third against its first-year baseline. Review by end of 2027; retire the acceptance cap if escapes do not rise as acceptance volume grows.
Outcome measure
escapes per AI-authored change accepted; expert-caught share.
Cross-check
DORA 2025 / METR 2025, supports; see the industry cross-check record, item 9.
Evidence
A 2025 randomized trial and a 2025 industry survey, both cited in the volatile layer; no incident in the evidence base.
62.speculativeneutral coreindustry-cited
Capability is a number with a date and a receipt
Answer "how much can AI do here" per activity, in three bands: unaided, with human review, cannot touch. Each rating carries a receipt. Name explicitly what humans own. Re-measure when models change and record the delta with justification, scoring a new model against a known-good peer on the same tasks. A receipt is: the date; the models measured; the task exercised; the outcome; the review requirement.
Disarms both the hype and the dismissal; and it obeys claim-never-exceeds-evidence. Self-reported speed has been measured with the wrong sign.
Receipt: cost, payoff test, evidence
Cost to keep
high, a benchmark to maintain.
Payoff test
The first populated row with a dated receipt promotes this to reasoned; three rows promote it to earned; retire if none by end of 2027. Outcome: decisions changed by a rating.
Outcome measure
staffing or delegation decisions changed by a rated cell.
Cross-check
DORA 2025 / METR 2025 measurements, supports the receipt requirement; see the industry cross-check record, item 9.
Evidence
Models are re-scored against a known-good peer on fixed tasks at each release; the per-activity matrix is a scaffold with no entries.
·
Volatile layers: dated, verify on read
The per-tool scorecard, the capability ratings and the local-vs-cloud line. Regenerated when the world moves; the principles above do not.
Verified on: 2026-09-11. Everything on this page is perishable. Tool features are renamed, models are replaced and the local-vs-cloud line moves. Before relying on any row, re-verify it against the official source named in evidence/Tool_Scorecard_Reverify_2026-09-11.md (the current dated record; the tool scorecard record is the earlier 2026-09-04 record it supersedes) and the industry cross-check record, item . The principles above this section do not move; this section is regenerated when the world does.
A. Tool capability scorecard
The measuring stick (rule 11): how much of each principle can a tool guarantee (enforce outside the model, able to block) versus merely request through advisory instructions. Tool-neutral is not tool-equal; the grades below are not meant to look like parity. Facts verified against official documentation on 2026-09-11; see the evidence file for URLs and quotes.
Content exclusion: explicitly does NOT cover agent mode in editors
Structured per-phase artifacts read explicitly
Ownership note (verified 2026-09-11): Windsurf became "Devin Desktop" under Cognition on 2026-06-02 (vendor FAQ: "the same IDE… unified under the Devin brand"). The stated July 2026 window for retiring the old "Cascade" agent name in favour of "Devin Local" has passed, but as of 2026-09-11 the official docs still use "Cascade" throughout and its documentation paths have not migrated: the rename is announced-complete but not yet documentation-complete. Any doctrine text that names Windsurf and Devin as separate products is stale.
Reading the table honestly. A rating grades the CLASS of mechanism (blocks outside the model, or merely requests), not the mechanism itself: two tools rated "Guarantee" on the blocking row both block outside the model, through different machinery. Two tools rated the same over a different mechanism CLASS would be a finding against the table, not a footnote (rule 11). "Unverified" means the official documentation did not confirm it on the date shown, not that the capability is absent.
The three justification stamps: traced to a dated incident and generalizes; a sound case with no scar yet; cheap and might pay off, and says so.
Neutral core / overlay
Where a rule lives: publishable and industry-general, or a context-specific calibration kept in a private branch.
Fact-frozen core
The single source document whose fact spans are never sent to a model; every other document is regenerated from it.
Freeze-proof
A cryptographic fingerprint of the untouched fact spans, checked after every regeneration to prove they did not change.
Characterization test
A test that pins a system's CURRENT behaviour, bugs included, so later changes cannot alter it unnoticed.
Spec mining
Reconstructing the slice of specification a change needs from code, tests, history and runtime behaviour, treated as a hypothesis until verified.
Blast radius
Everything a change can ripple to: every caller, shared-state reader and writer, and implicit contract.
Validation theater
Activity that looks like evidence but is not: agreement, enthusiasm, a show of interest.
Guarantee vs request
A property enforced outside the model and able to block, versus an advisory instruction the model may ignore.
Pre- / post-action guard
A script the harness runs before or after a tool action, able to inspect it, block it, or filter its output.
Receipt
For a capability rating: the date, the models measured, the task exercised, the outcome, the review requirement.
Reference environment
The instrumented software delivery environment whose recorded incidents form the evidence base.
Escape, escaped defect, escape rate
A defect that got past every check and reached users; the count of those per period. The doctrine's main outcome measure.
Harness
The software around the model: the tool that runs it, its permissions, guards, sub-agents and configuration.
Incident key
A short label naming one recorded event; several rules can share one key, so the masthead counts keys, not stamps.
Greenfield / brownfield
New work with no existing system to respect, versus work inside an existing, long-lived system.
Context fill
How much of a model's working memory (its context window) a session has used; quality drifts as it fills.
Practitioner-sanitized
A rule that came from a practitioner's own account with identifying detail removed; the weakest source, and marked as such.
Field incident
Provenance: the rule traces to a recorded event in the reference environment. A rule can carry this provenance and still be stamped reasoned if the event does not prove the rule as stated.
BYOK
"Bring your own key": using a tool with your own model-provider account instead of the tool's.
C. Capability ratings: the matrix (scaffold; receipts required before any number is entered)
Rule 62: a rating is a claim, so it obeys claim-never-exceeds-evidence. No cell below may hold a number without a receipt (date, models measured, task exercised, outcome, review requirement). The matrix ships empty on purpose; a populated matrix without receipts would violate the doctrine it sits in. Rows are given per domain so that no single domain reads as the default.
Activity
Domain
Unaided
With human review
Cannot touch
Receipt
Draft an architecture from a locked requirements set
all
-
-
-
none yet
Find edge cases in a spec
all
-
-
-
none yet
Build and maintain an automated test harness
application
-
-
-
none yet
Drive a test bench that includes physical devices
embedded
-
-
-
none yet
Parse service / device logs and propose a root cause
cloud · embedded
-
-
-
none yet
Reconcile declared infrastructure with what is actually running
cloud
-
-
-
none yet
Map the blast radius of a legacy change
all
-
-
-
none yet
Surface candidate hidden assumptions in legacy code
all
-
-
-
none yet
Write characterization tests pinning current behaviour
all
-
-
-
none yet
Regenerate an audience view from a frozen core
all
-
-
-
none yet
Adversarial review before a stage lock
all
-
-
-
none yet
Two published measurements set the bar for a receipt (verified 2026-09-04): the 2025 DORA report (DORA is the DevOps Research and Assessment program's annual industry survey; published 2025-09-23; ~5,000 respondents; AI adoption positively related to throughput, still negatively related to stability) and the July 2025 randomized trial by METR (Model Evaluation and Threat Research, a non-profit research group; 16 experienced developers, 246 real tasks; developers were 19% slower with AI tools while believing they were about 20% faster). The second is the failure this rule exists to prevent: self-reported capability had the opposite sign from measured capability.
Local only, where local capacity exists; where it does not, the control is contractual and the rule becomes a procurement requirement (no training on inputs, retention limits, audited processing)
Never leaves the organization's control; not a cost choice
Never, for whatever the organization has classified as sensitive; the class boundary is the organization's to set
Strongest available model, cloud if necessary; it sees the abstract specification, never the confidential material itself
Capability gap still real on 2026-09-11
As local models close the gap; record each move with dated evidence
E. Changelog of this layer
2026-09-04: first issue. Scorecard, glossary and ownership note verified live the same day; the capability matrix is a scaffold with no receipts yet.
2026-09-11: second adversarial pass applied. The scorecard's reading note now grades the CLASS of mechanism; the local-vs-cloud "moves when" cell names the organization's own sensitivity class instead of one shop's policy; the two industry measurements are expanded at first use.
2026-09-11: scorecard re-verified against official documentation on this date (record refreshed in evidence/Tool_Scorecard_Reverify_2026-09-11.md). The ownership note's rename status was re-dated (the July 2026 Cascade-to-Devin-Local window has passed, but the docs have not migrated). Six cells were evened for depth so no column reads as first-hand use: the sub-agent, plan-gate, local-model and brownfield cells were brought to parity, and the blocking and context-exclusion cells now name their own gaps. The Claude Code glossary cells dropped their command syntax, and a Claude Code-specific operational note was removed from this section (it was not a four-tool capability fact).