FORGE-103 — The Development Standards

FORGE-103 — The Development Standards

Project Forge — Fourth Engineering Document Status: Normative (governs implementation discipline). Extends FORGE-100, FORGE-101, and FORGE-102; implements FORGE-001, FORGE-002, FORGE-003. Precedence: FORGE-001 governs vision; FORGE-002 governs meaning; FORGE-003 governs experience; FORGE-100 governs construction; FORGE-101 governs composition; FORGE-102 governs sequence; FORGE-103 governs implementation discipline — how the code that realises all of the above is written, tested, documented, reviewed, and maintained. Where this document appears to permit an act its predecessors forbid, the predecessors govern and the permission is void. Where this document is silent, the practitioner is not free: they are obliged to reason from the predecessors and to record the reasoning (Part 5).

Preamble

Six documents now stand. FORGE-001 answered why. FORGE-002 fixed the meaning. FORGE-003 fixed the felt experience. FORGE-100 proved the thing constructable, FORGE-101 proved it shareable, and FORGE-102 fixed the order in which it will be built. Everything the corpus has decided is now decided at the altitude of law. This document descends the last step — to the altitude of the keystroke.

The previous documents can be obeyed by a reader who never opens an editor. This one cannot. It exists for the hand on the keyboard at the moment a thousand small decisions are made that no law reaches by name: what to call this function, whether this abstraction is earned, whether this error may be swallowed “just here,” whether this commit is small enough to reverse, whether this is finished or merely working. The constitution is what those thousand decisions must add up to. This document is how they are made so that they do.

I write here not as architect but as the project’s first engineer, and I am writing to the engineers who will outlast me — the maintainer of FORGE-002 Principle 11, arriving in a year I will not see, inheriting a codebase whose original authors are unreachable. That maintainer is the only reader of this document who matters. Every standard below is chosen by one test: does it make the codebase more understandable, more changeable, and more honest for someone who was not in the room? A standard that only serves the person writing today’s code — that saves them a keystroke, flatters their cleverness, or spares them the labour of a test — is not a standard. It is a debt with good manners.

Two sentences frame everything that follows. They are this document’s contribution to the constitutional record, and Parts 1 and 7 give each its teeth:

  1. Discipline is what a constitution feels like on an ordinary Tuesday. The laws of the corpus are not obeyed in grand acts; they are obeyed, or betrayed, in the unremarkable commit made under mild deadline pressure by a tired person. This document’s job is to make the disciplined path the path of least resistance on that Tuesday — because no other Tuesday is the one that decides the project’s character.

  2. A standard not enforced by a machine is a preference wearing a robe. The team is small (FORGE-102 Part 17.3: bus factor near one), the horizon is long (fifty years — FORGE-001 Principle 8), and human vigilance does not scale to either. Therefore: every standard in this document that can be mechanically checked, must be — as a build-failing check, in every repository, from the day the standard applies. The standards that cannot be mechanically checked are held by review (Part 7), and review exists precisely and only for them.

This document is deliberately unglamorous, as FORGE-102 Part 4.6 warned its own hardening phase would be. Coding standards do not make conference talks. But the corpus has a consistent theory of where a project’s fate is actually decided — in the unwatched hours (FORGE-003 Part 2), in the honest zero (FORGE-102 Part 19.3), in the erratum published without being forced (FORGE-102 Part 20) — and every one of those is an act of engineering discipline before it is anything else. This is the document about the unwatched hours.

Terminology

RFC-2119 terms (MUST / MUST NOT / SHOULD / SHOULD NOT / MAY) are used as defined in FORGE-100 Part 2: a MUST violation makes the artifact not-Forge; a SHOULD departure is recorded with a reason; a MAY is genuinely optional.

New defined terms introduced here:

A note on register. FORGE-100 through FORGE-102 wrote about structures and sequences; they could afford abstraction. This document must occasionally descend to the concrete — a file name, a commit message, a directory. Where it gives a concrete example, the example is illustrative of the rule, never a hidden decision about a tool: this document names no programming language, no test framework, no CI product, and no linter by brand, because those are instance-of-the-toolchain facts that change on a timescale far shorter than fifty years, and a standard welded to a vendor is a standard with an expiry date. The rules are stated so that they survive their tools.

Part 1 — Development Philosophy

Before any rule about files or commits, the disposition from which the rules follow. A practitioner who holds this part can re-derive most of the rest; a practitioner who memorises the rest without this part will apply them as ritual and abandon them under pressure. Six commitments.

1.1 Architecture first

No line of implementation code precedes the understanding of where it belongs. Before writing, the practitioner MUST be able to name the plane (Core / Domain / Instance — FORGE-101), the stratum (Ontology / Truth / Publication / Knowledge / Derivation / Presentation / Interaction — FORGE-100 Part 2), and the contract (FORGE-100 Part 10) the code touches. Code that cannot be placed has no place.

This is not bureaucracy; it is the cheapest possible application of FORGE-102 Part 1.5’s doctrine test. The plane label decides what the code may know (a core file that learns what a scheduler is has already failed — FORGE-101 Part 14); the stratum decides what may depend on it; the contract decides what may change without coordination. All three are knowable before the first keystroke, and knowing them is what separates implementation from improvisation. When placement is genuinely unclear, that is not a licence to proceed and sort it out later — it is a signal that an architectural question is open, and open architectural questions are resolved in an ADR (Part 11.3), not in a merge.

1.2 Evidence over assumptions

Forge’s whole method is evidence-born (FORGE-102 Part 1: extracted from success, never designed in isolation). At implementation scale this becomes a habit of the hands:

1.3 Small, reversible commits

The unit of work is the smallest change that leaves the platform correct, tested, documented, and shippable. A change that cannot be expressed as a sequence of such units is not too large to commit; it is too large to understand, and MUST be decomposed until it is.

FORGE-102 built its entire migration on this (Part 1.4: small individually shippable moves, because small moves interleave with feature work and large ones cannot; Part 4.3: byte-identical output per move, not per phase). The philosophy predates the migration and outlives it. A small commit is reversible (Part 6.6), reviewable (a reviewer can hold it entirely in mind — Part 7), and bisectable (when something breaks, the guilty change is found in log-time, not by archaeology). Largeness in a commit is not ambition; it is the deferral of the decomposition work onto whoever must later understand, review, or revert it.

1.4 Extraction before invention

The doctrine of FORGE-102 Part 1, restated as a coding instinct: the proven, present, working thing is worth more than the elegant, general, imagined thing. When a capability is needed twice, extract the commonality from the two real uses (you have two pieces of evidence about its true shape). When it is needed once, write it once, plainly, at the site of need. Do not invent the general form of a thing from a single instance of it — you will encode that instance’s accidents as the general case’s assumptions (FORGE-102 Final Review’s fossilisation confession). Invention is not forbidden; premature generalisation is. The discipline is to let the second real use, not the first imagined one, summon the abstraction.

1.5 No speculative abstraction — the Rule of Two

An abstraction — a shared function, an interface, a base class, a configuration key, a framework — MUST NOT be introduced before its second real, present use exists. One use is a use; two uses are a pattern; a pattern is the evidence an abstraction requires (ADR-034).

This is FORGE-101 ADR-027 (no domain without a committed instance; promotion on evidence) and FORGE-102 ADR-028 (invention at the narrowest plane that can express it) applied at the finest grain the corpus reaches. The “we’ll need it later” parameter, the “just in case” interface, the option nobody sets, the layer with one implementation — each is a promise (FORGE-002 Principle 11: every added surface is an upkeep obligation) taken on with no evidence it will ever be redeemed, and every one of them makes the code harder to read for the certain present in exchange for an uncertain future. The corpus’s economics are unforgiving here: the best optimisation is deleting code (Part 14), and speculative abstraction is code that never should have been written to be deleted. When in genuine doubt whether the second use is coming, assume it is not; promotion on evidence is cheap (FORGE-101 Part 7.8), and demoting a wrong generalisation is surgery (FORGE-102 Part 4.1).

1.6 Every commit improves the platform

The platform (the proving ground — FORGE-102 Part 1.1) is left better by every commit than the commit found it: more correct, more tested, more documented, more understandable, or more honest. A commit that leaves the platform worse on all of these axes to advance on none of them is not a step; it is drift.

This is the “boy scout rule” given constitutional weight. It does not demand heroic refactors — those are their own commits, small and reversible (1.3). It demands only that the codebase not silently decay under maintenance: a fixed bug leaves a regression test behind it (Part 4.7); a touched function leaves its documentation comment accurate (Part 3.6); a discovered misplacement leaves a relocation or, at minimum, a recorded note (FORGE-102’s misplacement log at code scale). The alternative — improvement always deferred to a refactor that never comes — is how a clean architecture becomes a legacy system without any single decision to blame. The corpus refuses to let that decision be unauthored: decay, here, is a sequence of small permitted commits, and this commitment revokes the permission.

1.7 The meta-standard: mechanise what you can

The second framing sentence of the Preamble is itself a philosophy, and it governs how every other part of this document is to be read:

For any standard in this document, the practitioner MUST ask first: can a machine check this? If yes, the standard’s true home is CI, and stating it in prose is a temporary measure until the check exists. If no, the standard’s home is review (Part 7), and it is one of the finite things reviewers are actually for. A standard in neither home is decoration, and this document contains none by intent.

The consequence is a standing obligation: when a prose standard becomes mechanically checkable — because a tool matures, or someone writes the linter — wiring it into CI is not optional polish but the completion of the standard. FORGE-102’s phases turned laws into firewalls exactly on this principle (Part 4.2’s vocabulary lint, Part 4.3’s dependency-law checker); this document generalises the principle to itself.

Part 2 — Repository Standards

The repository is where the architecture meets the file system (FORGE-102 Part 6.2). The steady-state repository set is fixed by FORGE-101 Part 13.1 and its arrival sequence by FORGE-102 Part 6.2; this part governs what is true inside each repository, for all of them.

2.1 Layout follows the architecture, not convenience

A repository’s top-level structure MUST make its plane and its strata legible to a stranger at a glance. Directory boundaries follow architectural boundaries (planes, strata, contracts, modules — FORGE-100, FORGE-101), never incidental ones (file type, author, chronology).

The failure this forbids is the utils/, helpers/, misc/, common/ directory — the drawer into which code goes when its author declined to decide where it belongs. Such a directory is 1.1’s placement failure made durable: it accretes, it develops dependencies in every direction, and within a year it is the part of the codebase nobody can safely change. Code has a home defined by what it is architecturally; if its home is unclear, that is an architectural question (1.1), not a naming one, and the answer is a decision recorded, not a drawer opened. A shared thing with two real users (1.5) belongs to a named module with a named owner, not to common/.

2.2 Naming conventions for repositories and directories

2.3 Module boundaries

FORGE-101 Part 7 defines the Forge Module as the unit of runtime capability. At the repository level this yields a standard:

Every module is a directory with a single, stated responsibility; a declared public surface (what other code may call); a manifest carrying its upkeep owner and its degraded state (FORGE-101 Part 7; Principles 11 and 12, made unskippable fields — FORGE-102 Part 4.3); and no dependency that the dependency law (FORGE-101 Part 14) forbids. Code reaching into a module’s internals rather than its declared surface is a boundary violation, checked mechanically where the toolchain allows and by review where it does not.

A module whose responsibility cannot be stated in one sentence is doing more than one thing and MUST be split. A module with no upkeep owner is an orphan the moment it merges (FORGE-102 ADR-032: no artifact ships without a named upkeep owner); the manifest field is not paperwork but the mechanical enforcement of that law.

2.4 Plane labels are permanent and enforced

The FORGE-102 Phase 1 audit adjudicated a plane label for every existing file; Part 4.1’s gate made labelling new code a habit. This document makes the habit a standard for all time:

Every file in every repository carries an adjudicated plane label (core / domain / instance), and new code carries its label at review time. Cross-plane dependency is governed by the dependency law (FORGE-101 Part 14) and checked in CI, blocking, in every repository that exists (FORGE-102 Part 4.3). An unlabelled file is an unreviewable file.

Where a label is genuinely disputed, it defaults to the narrower plane (FORGE-102 Part 4.1: promotion on evidence is cheap, demotion is surgery) and the dispute is recorded — the audit’s dispute log continued into steady state, feeding the same Evidence Ledger.

2.5 Ownership

Every repository, every module, and every contract has a named owner recorded in a machine-readable ownership file at the repository root (the same registry FORGE-102 Part 17.3’s bus-factor target reads from). Ownership means: this person answers reviews here, is accountable for this surface’s upkeep (Principle 11), and is the human the continuity statement (FORGE-102 Part 17.6) names if the surface is orphaned. From FORGE-102 Phase 6’s 1.0 target onward, no plane rests at bus factor one without a recorded succession arrangement (ADR-032); the ownership file is where that arrangement is legible or its absence visible.

2.6 README expectations

Every repository and every non-trivial module has a README, and the README is held to the same honesty as the instrument’s Record (FORGE-001 Principle 9: documentation that rots is worse than none). A README MUST state, at minimum: what this is (in the architecture — its plane and responsibility), what it depends on and why, how to build and test it from a cold checkout, who owns it, and its current status told honestly (a forge-core at 0.x says “being extracted, not yet adoptable” — FORGE-102 Part 16.2 — not aspirational prose). A README that describes an intended future as if it were the present is the “flood of defaults” smell (FORGE-102 Part 13.3) in documentary form, and is a defect.

Part 3 — Coding Standards

The corpus governs what the code must be; this part governs how it reads. The single organising value: code is written to be read, understood, and changed by someone who is not its author and cannot ask them. Every rule below serves that reader.

3.1 Readable over clever

Given two correct implementations, the one a stranger understands faster is the better one, and this ordering is not overridden by concision, by performance (Part 8: measure before you trade readability for speed), or by the author’s taste. Cleverness that must be explained in a comment is a defect the comment documents rather than repairs.

“Simple before clever” (Part 14) is not anti-intellectualism; it is arithmetic. Code is written once and read for fifty years (FORGE-001 Principle 8). An hour saved writing a dense expression, paid back as five minutes of puzzlement by each of a hundred future readers, is a catastrophic trade the author never sees on their own clock. The corpus’s reader — the maintainer who never met the author — cannot ask what the clever line meant. The code must already have told them.

3.2 Naming — the load-bearing decision

Names are the primary interface between code and comprehension, and Forge holds them to the ontology’s own standard of precision (FORGE-002’s insistence that a Job is not a Task is not a Run):

3.3 File naming

Files are named for their single responsibility, in kebab-case or the language’s idiomatic convention where one is enforced by tooling — consistency within a repository outranks any global preference, and the choice is recorded once in the repository’s README (Part 2.6) rather than re-litigated per file. A file’s name predicts its contents; a file named for one thing that contains another is a placement failure (1.1). One public module concept per file is the default; a file that must be scrolled to be understood is a candidate for splitting along the seams its own sections reveal.

3.4 Type, class, and function naming

3.5 Configuration and constants

Configuration is privacy-bearing and provenance-stamped (FORGE-101 Part 5.3; ADR-017), and it is where instance knowledge lives — so it is held to a higher standard than ordinary code, not a lower one:

3.6 Documentation comments

Every public surface — every module, every exported type, every function another plane or module may call, every configuration key, every non-obvious constant — carries a documentation comment stating what it does, what it assumes, and what it promises (its contract, in the FORGE-100 Part 10 sense). Comments explain why, never what: the code already says what it does, and a comment restating it is rot the moment the code changes beneath it.

The distinction is the whole discipline. // increment i is noise that will one day lie. // floor of 5 required by ADR-017 differencing resistance; lowering it re-opens the re-identification attack is load-bearing knowledge the code cannot carry itself, and it cites the law so the future reader can find the reasoning (FORGE-102’s whole method: recorded reasons). A comment that could be deleted with no loss of meaning SHOULD be deleted; a comment that encodes a why the code cannot express MUST exist. This is “if it cannot be explained, it is not finished” (Part 14) applied at the function.

3.7 Formatting is settled by machines, never by people

Code formatting — indentation, spacing, line length, import order, brace style — is decided by an automated formatter run in CI, blocking, and is never a matter of review comment, personal preference, or discussion. The formatter’s configuration is committed to the repository and is the same for every contributor.

This is Part 1.7 in its purest form. Formatting debates consume review attention (Part 7) that is finite and owed to correctness, architecture, privacy, and comprehension — the things machines cannot check. A project that argues about spaces has mistaken a mechanical question for a human one. The formatter ends the argument permanently and returns review to its purpose. Formatting-only diffs are isolated into their own commits (1.3) so they never obscure a substantive change.

Part 4 — Testing Standards

Testing in Forge is not quality assurance bolted to the end; it is the mechanical memory of what the platform is supposed to do, and it is the only thing standing between a fifty-year codebase and the slow forgetting of its own guarantees. The corpus already leans its entire migration on one test — byte-equivalence (FORGE-101 Part 16) — and this part generalises the trust that made possible.

4.1 What a test is for

A test exists to convert a promise into a mechanically enforced fact. The corpus’s promises are unusually testable because its architecture is unusually pure: the governing invariant (FORGE-100 Part 1.5) makes every view a pure function of stored facts and identity, and pure functions are the most testable objects that exist. This is not an accident the architecture tolerated; it is a property the architecture bought, and testing is where the purchase pays out. Code that is hard to test is, nearly always, code that has violated the invariant — reached for hidden state, mixed derivation with effect, entangled a plane with another’s knowledge — and the difficulty of testing it is the architecture reporting a defect (Part 4.8).

4.2 Unit tests

Every pure function that encodes a decision, a transformation, or a rule carries unit tests covering its contract: its normal behaviour, its boundaries, and its defined failures. A projection, a privacy floor, an aggregation, an identity check, a contract validation — each is unit-tested at the point of its definition, in the plane that owns it.

Unit tests are fast, hermetic, and numerous; they are the tests run on every save and every commit. They test one plane’s logic in isolation — a Core projection is tested with fixture facts, not a live source system; a domain adapter’s logic is tested separately from its bindings (FORGE-101 Part 8.4’s split exists precisely so the logic is unit-testable without the instance’s credentials). Coverage of the privacy machinery (ADR-017’s floors and differencing resistance) is not negotiable: an untested aggregation floor is an unproven privacy guarantee, and Part 9 forbids unproven privacy guarantees.

4.3 Integration tests

Integration tests prove the seams — that adapters speak to real (or faithfully recorded) source systems, that a composition (FORGE-101 Part 7.4) validates and builds, that the dependency law and vocabulary firewall actually fire, that a published artifact is what the pipeline claims. The composition machinery itself is tested (FORGE-102 Part 3.2 claim 4: the laws are enforced by machines, with the checks themselves tested — an unchecked check is a false guarantee). The Ghost Instance (FORGE-102 Part 4.2) is the standing integration test of the no-instance-knowledge law, and it lives permanently in CI, not as a one-time proof.

4.4 Golden recordings

Where Forge transforms an external reality it does not control — a source system’s response, a rendered projection, a published page — the expected output is captured as a versioned Golden Recording and diffed on every build. A change to the diff is either an intended change (the recording is updated in the same commit, with the reason) or a regression (the build fails). There is no third case.

This is byte-equivalence (FORGE-101 Part 16) generalised from the migration to the permanent codebase. Golden recordings are how Forge tests things too large, too real, or too emergent to assert field-by-field: the exact bytes of a published page, the exact shape of a scheduler’s real output (captured once from reality — Part 1.2’s read-before-you-write — and replayed forever). They are the domain plane’s defence against upstream churn (FORGE-102 Part 18, R10: golden-recording diffs are how adapter breakage becomes visible staleness rather than silently wrong data — ADR-014). A golden recording is committed with provenance: what it was captured from, when, and by whom.

4.5 Contract tests

Every contract (FORGE-100 Part 10) between planes, modules, or versions carries contract tests that assert the contract as stated, independent of either side’s implementation. Contract tests are what make FORGE-102 Part 3.2 claim 3 checkable — that contracts have survived change — because they fail the moment a change breaks a promise, additive-or-not (FORGE-101 ADR-015’s regime). A contract with no contract test is a promise with no enforcement, which is to say not a contract but a hope. When a deprecation window opens (FORGE-102 Part 4.6), the contract test for the deprecated surface remains green until the window closes and is removed in the commit that closes it — the test is the window’s mechanical honesty.

4.6 The regression philosophy

A bug is a gap in the tests before it is a gap in the code. Therefore: no bug is fixed until a test exists that fails because of it and passes because of the fix. The test is written first, watched to fail, and only then is the code changed. The failing test is the reproduction (Part 1.2); the passing test is the proof; and the committed test is the guarantee the bug never returns silently.

This is the single most important sentence in Part 4, because it is what makes the codebase’s quality monotonic: every defect the platform has ever suffered leaves behind a permanent sentinel against its recurrence, and the test suite becomes, over fifty years, the accumulated memory of every mistake never to be repeated. A fix without a regression test is not a fix; it is a patch that has learned nothing.

4.7 When tests are mandatory, and when they are not

Testing is a standard, not a religion, and the corpus refuses ceremony (FORGE-102 Part 4.3’s ceremony trap). The rule is proportional:

The test to apply is not “did I write a test” but “is this guarantee mechanically enforced somewhere.” A guarantee enforced by a golden recording (4.4) or a contract test (4.5) need not be re-asserted by a unit test; a guarantee enforced nowhere is the defect.

4.8 Coverage is a diagnostic, never a target

Test coverage is measured and read as a signal — an uncovered branch is a question worth asking — but coverage percentage MUST NOT be a gate, a target, or a metric anyone is asked to raise. A team told to hit a coverage number will write tests that assert nothing to hit it, and the platform will be worse for the effort while the number improves.

This is FORGE-102 Part 19.3’s refusal of vanity metrics applied to testing. The honest question is never “what is our coverage” but “is every guarantee in Part 4.7’s MUST list enforced” — and that question is answered by review (Part 7) and by the guarantees’ own tests, not by a percentage. Untestable code driving coverage down is architecture reporting a defect (4.1); that is the signal coverage exists to surface, and raising the number by testing trivia hides exactly the signal worth reading.

Part 5 — Documentation Standards

Documentation is part of implementation. A change is not complete when its code works; it is complete when a stranger can understand what changed, why, and what it now guarantees (ADR-033; Part 11.9’s Definition of Done). Documentation written after the fact, as a separate chore, is documentation that will not be written — and undocumented code is a promise (Principle 11) with no record of what was promised.

FORGE-001 Principle 9 is unusually severe: documentation that rots is worse than none, because it misleads with authority. This part governs so that Forge’s documentation is born accurate and stays honest.

5.1 When documentation is required

Documentation is required, and its form is fixed by what changed:

Documentation not on this list is optional and, per Part 3.6’s principle, is written only when it carries a why the artifact cannot carry itself.

5.2 How ADRs are written

The corpus has a settled ADR form (FORGE-100 ADR-001–017, FORGE-101 ADR-018–027, FORGE-102 ADR-028–032, and Part 15 below). An ADR states: the decision in one imperative paragraph; the context that forced it; the consequences it accepts; and — the field the corpus treats as load-bearing above all — the “Exists because” clause, which records why, for the future maintainer who will otherwise repeal the decision by convenience (FORGE-102 Part 21’s stated purpose). An ADR is numbered in the single monotonic series shared across the whole corpus (never restarted per document), is never deleted, and — if superseded — is marked superseded with a pointer to its successor, because the reasoning of a repealed decision is itself evidence the next maintainer needs.

5.3 How architectural changes are documented

An architectural change is documented at the altitude it occurs. A change within the sanctioned architecture (a new module obeying the laws) is documented in READMEs and manifests. A change that tensions the architecture — a component that seems to need two planes’ knowledge (FORGE-102 Evidence Ledger A1), a law that seems to cost more than it buys — is not implemented and documented; it is stopped and raised as an amendment case, because the corpus is debugged by governance, not edited by whoever hit the wall (FORGE-101 Preamble’s own standard: an unreconcilable sentence is a defect to be amended, through process). The implementer’s obligation is to surface the tension with evidence, not to resolve it in a merge.

5.4 How deployment reports are written

Every deployment is authored into the Record as a Deployment event (FORGE-101 Part 16.2), in the instrument’s own voice, factually, with provenance — the same honesty the platform demands of every fact it publishes about reality it demands of facts about itself. A deployment report states what changed, what composition (which released versions — FORGE-101 Part 7.5) is now live, what was verified (Part 11.8), and — if anything degraded — what and for how long (Principle 12’s degraded state). The migration’s own history is authored this way (FORGE-102 Part 20: an archived repository retired with an authored event a handful of people read like an obituary); steady-state deployment inherits the practice unchanged.

5.5 How implementation reports are written

Every non-trivial change closes with an Implementation Report: a dated, factual record of what was done, why, what was tested, what was verified, and what was left undone. It is written at completion, by the implementer, and it is the codebase’s equivalent of the instrument’s Record — append-only, honest about its own gaps, and citing its reasons.

The Implementation Report is not a status update and not marketing; it is evidence, held to FORGE-102 Part 16.3’s register (dated, factual, provenance-carrying, no launch theatre). Its most important section is often what was not done — the deferred edge case, the known limitation, the scope deliberately excluded — because an honest account of a change’s boundaries is what lets the next person build on it safely (FORGE-102’s phases each stating “explicitly not done”). A report that claims only success is as untrustworthy as a Record that shows only uptime.

5.6 Recording departures

Every SHOULD in this corpus carries the same closing rule (FORGE-100 Part 2; FORGE-003 Part 10): a departure from a strong default is recorded, in the Implementation Report or an ADR, with its reason. The record is not a confession seeking absolution; it is evidence for the future maintainer deciding whether the departure still holds. An undocumented departure is indistinguishable from a mistake, and over fifty years the difference between the two is the difference between a maintainable system and an inexplicable one.

Part 6 — Git Standards

The version-control history is the codebase’s Record: an append-only, honest, permanent account of how the platform came to be what it is. The corpus’s treatment of the instrument’s history — never rewritten, always provenanced, permanent at its addresses (FORGE-100 Part 12.2; FORGE-001 Principle 9) — governs the code’s history by the same logic and for the same reader.

6.1 Branch strategy

The strategy is the simplest one that serves small, reversible commits (1.3) and continuous extraction (FORGE-102 Part 1.2): a stable main branch that is always shippable, and short-lived branches for work in progress that merge back quickly. Long-lived divergent branches are forbidden by the same reasoning that forbids the perpetual strangler (FORGE-102 R2): a branch that lives for weeks is a private half-state accumulating merge risk and hiding work from review, and its cure is the same — small moves that land, not large ones that diverge. The migration proved this at platform scale (FORGE-101 Part 16.2: every move ships); ordinary work inherits it.

6.2 Commit message conventions

A commit message states what changed and why, in a subject line that reads as a completed action and a body that gives the reasoning a reader will need at a git blame fifty years hence. The message references the ADR, contract, or Implementation Report that governs the change where one exists. A commit message that describes only what (recoverable from the diff) and not why (recoverable from nowhere else) has wasted the one moment the reason was cheap to record.

The subject is imperative and specific (“Externalise Mjolnir credentials into the secret store” — FORGE-102 Part 4.2 — not “fix stuff”). Where the corpus uses a change identifier (the FORGE-004-style prefixes in this repository’s own history), commits carry it, so the history is navigable by the work it realises. The body is prose, not a changelog fragment; it is written for a person, because a person is who reads it when something has broken and the reason matters most.

6.3 Merge policy

Every change enters main through review (Part 7); nothing merges unreviewed, including the founder’s own work, because a bus factor near one (FORGE-102 Part 17.3) is exactly the condition under which unreviewed commits are most dangerous and most tempting. CI — every mechanical check this document mandates (Part 1.7) — passes before merge, blocking, without exception, because an exception granted once under deadline is a precedent cited forever. Merges preserve the small-commit structure (1.3) rather than collapsing a reviewed sequence into one opaque commit, so that the history remains bisectable.

6.4 Releases and version tags

Releases follow FORGE-101 ADR-015 and FORGE-102 Part 3.3’s version semantics exactly: Core and domains release as versioned artifacts (0.x before 1.0, meaning contracts may still move under short windows; ≥1.0 after, additive-by-default with recorded deprecation windows); instances pin exactly, always (FORGE-101 Part 7.5); the published record is versionless and never on the release train (FORGE-102 Part 3.3). A release is tagged immutably, its composition (which versions of what) recorded in a lockfile, and — for consequential releases — declared as a Deployment event (5.4). The 1.0 tag in particular is a governance act, not an engineering one (FORGE-102 ADR-030): it is applied only when the seven claims are audited and recorded.

6.5 Public history is append-only

Once history is public — pushed to a shared branch others may have pulled — it MUST NOT be rewritten. No force-push to a shared branch, no rebasing published commits, no amending a merged commit, no deletion of a public tag. History is corrected the way the Record is corrected: by a new commit that supersedes, with the reason, never by erasing the old one (FORGE-100 Part 12.2; FORGE-003 Part 10’s erratum-not-edit rule).

This is the codebase’s version of the deepest promise in the corpus: the past is not editable, only appended to. A mistake in public history is fixed by a forward correction that leaves the mistake and its correction both visible, because the honest account of a codebase includes its errors and their repairs — that is precisely what distinguishes a Record from a brochure. Rewriting public history to hide a bad commit is the code-level form of the dishonesty FORGE-102 Part 20 named as the one failure the project refuses to survive gracefully.

6.6 Rollback philosophy

Rollback is a first-class, rehearsed capability, not an emergency improvisation, because small reversible commits (1.3) exist precisely to make it cheap. A broken change is reverted by a forward revert commit (obeying 6.5: the broken commit stays in history, its revert beside it, both reasoned), the platform is returned to a known-good composition (immutable releases and lockfiles — 6.4 — make “known-good” a reproducible fact, not a memory), and the failure is recorded (an Implementation Report or Deployment event — 5.4/5.5 — because a rollback is a fact about the platform’s history as much as a deployment is). The abandonment guarantee (FORGE-102 Part 17.6: every instance keeps operating on its pinned versions indefinitely) is the ultimate rollback, and it works only because every ordinary rollback rehearsed the same mechanics.

Part 7 — Code Review

Review is where the standards this document cannot mechanise (Part 1.7) are actually enforced, and therefore review is scarce, focused, and reserved for exactly those standards. A review that argues about formatting (settled — 3.7) or coverage percentage (a non-target — 4.8) has spent its attention on machine work and starved the human work only it can do.

7.1 What review is for

Review exists to verify the things a machine cannot: that the code is placed correctly (Part 1.1), understandable by a stranger (Part 3.1), architecturally honest (obeys the laws in spirit, not merely in the lint’s letter), privacy-sound, and finished (Part 11.9). Everything a machine can check has already been checked before the reviewer arrives (Part 6.3); the reviewer’s finite attention is owed entirely to what remains.

The reviewer represents the reader who is not in the room — the maintainer in year twenty (Preamble). Their governing question on every change is FORGE-102 Part 1.5’s doctrine test, restated for code: does this place logic at the wrong plane, invent ahead of evidence, or take on an unmaintained promise? A “yes” to any is a complete objection, cited by number.

7.2 The architectural checklist

7.3 The privacy and security checklist

Privacy is the review dimension whose failure harms a person (FORGE-102 R8), so it is checked on every change that touches facts, aggregation, identity, or configuration, never only on changes that announce themselves as privacy work:

7.4 The performance, documentation, and testing checklists

7.5 The questions a reviewer always asks

Beyond the checklists, four questions the corpus wants asked of every change, because they catch what checklists cannot:

  1. What breaks if this is wrong? (Locates the change’s blast radius, and calibrates the review’s rigour to it — a privacy or identity change is reviewed harder than a projection’s colour.)
  2. How will the maintainer in year twenty understand this? (If the answer requires the author present, the change is not finished — 3.1, “if it cannot be explained, it is not finished.”)
  3. What is the smallest version of this change? (Enforces 1.3; a change that could be smaller usually should be.)
  4. What did the author choose not to do, and did they say so? (Enforces 5.5’s honesty about boundaries; the most dangerous defects hide in the unstated scope.)

7.6 Review conduct

Review is conducted in the corpus’s register (FORGE-102 Part 16.3): factual, cited, about the code and never the author. An objection cites the standard or law it rests on (a review comment that says “I’d prefer” without a citation is a preference, and preferences were settled by machines or are out of scope). The author’s disagreement is resolved by evidence or by escalation to an ADR (a genuine architectural dispute is decided by governance — FORGE-102 Part 8 — not by whoever tires last). Review is a gift of attention between people building something to outlast them both, and it is conducted as one.

Part 8 — Performance Philosophy

Forge’s architecture makes performance mostly a solved problem by construction: build-time projection and static delivery (ADR-007; FORGE-100 Part 12) mean the reader is served immutable files, and a file has no performance problem worth optimising. This part therefore governs the narrow remainder where performance is a live question — and, more importantly, guards against the far commoner error of optimising where no question exists.

8.1 Measure first

No code is optimised for performance without a measurement establishing that a performance problem exists, where it is, and how large it is. “This might be slow” is not a reason to optimise; it is a reason to measure. A performance change unaccompanied by a before-and-after measurement is not an optimisation but a speculation, and is reviewed as one (Part 7.4; ADR-035).

This is FORGE-102 Part 20’s forecast law (labelled, method stated, error bars) applied to speed, and it is the direct descendant of the corpus’s deepest instinct: evidence over assumption (1.2). The overwhelming majority of code is not on any hot path, and effort spent optimising it is effort stolen from correctness, clarity, and tests — while the readability it costs (Part 3.1) is paid forever. The measurement is the evidence that the effort is warranted; without it, the optimisation is a guess that made the code worse.

8.2 Optimise second, and locally

When a measurement has located a real problem, the optimisation is the smallest, most local change that resolves the measured cost, and it is justified in the code (8.5) and the Implementation Report (5.5) by the number that motivated it. A readability sacrifice (3.1) is permissible only against a recorded measurement and only at the measured site — never pre-emptively, never broadly, never “while we’re here.” The corpus’s ordering holds: readable-and-fast-enough beats clever-and-faster everywhere except the rare measured hot path, and even there the cleverness is quarantined behind a documented boundary and a golden recording (4.4) proving it still produces the right answer.

8.3 Never optimise speculation

Optimising code that no measurement has implicated is forbidden, because it spends the project’s scarcest resource — understandable code — to buy a performance improvement no one has shown is needed. Speculative optimisation is speculative abstraction’s twin (1.5), and the Rule of Two’s sibling: no optimisation before the measurement that summons it.

The phrase “premature optimisation” is old and true, and the corpus adopts it as law rather than folklore (Part 13). The discipline is to trust the architecture’s structural performance (static delivery — 8.0) until a measurement proves a specific exception, and to treat the itch to optimise-by-feel as exactly the assumption-over-evidence reflex the whole method exists to resist.

8.4 Prefer simplicity as the default performance strategy

The fastest code to run is often the simplest code to read, because simplicity eliminates work rather than accelerating it (Part 14: the best optimisation is deleting code). Before any clever optimisation, the reviewer asks whether the measured cost is better removed than accelerated — a redundant computation deleted, a projection not derived twice, a query not issued at all (the query-service exception of FORGE-100 Part 12.3 is the only sanctioned dynamic read path; everything else is a file). Deletion is the optimisation that also improves readability, testability, and maintenance simultaneously, and it is always considered first.

8.5 Document performance assumptions

Any code whose shape is dictated by a performance consideration carries a documentation comment (3.6) stating the assumption, the measurement that justified it, and the condition under which it should be revisited. A hot-path optimisation with no recorded rationale is a trap for the future maintainer, who cannot tell the deliberate-but-ugly from the accidental-and-ugly and will either preserve cruft in fear or remove a load-bearing optimisation in ignorance. The comment converts a mystery into a maintainable decision — “if it cannot be explained, it is not finished” (Part 14) at the hot path.

Part 9 — Security

Security in Forge is largely a consequence of the architecture rather than a layer upon it: static delivery has almost no runtime attack surface (ADR-007), the reader is not surveilled (FORGE-100 Part 11.7), and the identity boundary is orthogonal and explicit (FORGE-100 Part 11). This part governs the discipline that keeps those structural gifts intact and closes the gaps the structure leaves.

9.1 Least privilege

Every component runs, connects, and reads with the minimum authority its function requires, and no more. An adapter has the credentials for its one source system, scoped to read what it ingests (FORGE-101 Part 8.4’s binding split is what makes this scoping possible — the logic needs no credentials at all). The publication pipeline writes where it publishes and nowhere else. A component that holds authority it does not exercise is a liability with no offsetting benefit, and the review asks of every new access grant whether it is the least that works.

9.2 No secrets in repositories — absolute

No credential, token, key, password, or secret of any kind is ever committed to any repository, in any form, in history or in head, encrypted or plain. Secrets live exclusively in a secret store external to version control (FORGE-101 Part 5.3; externalised in FORGE-102 Phase 2). This is enforced by an automated secret scanner in CI, blocking, and by review (7.3) as a permanent backstop.

The rule is absolute because the cost of violating it is unbounded and, under append-only history (6.5), unrepairable by deletion: a secret pushed to public history is compromised forever and must be rotated, not erased, because erasing it would require the history rewrite the corpus forbids. The scanner is the mechanical guard; the review is the human one; and the standard admits no “just this once” exception, because the one exception is the one that leaks.

9.3 Configuration validation

Configuration is typed, schema-validated, and provenance-stamped (FORGE-101 Part 5.3), and it is validated at composition time (FORGE-101 Part 7.4), before anything runs — a malformed floor, a missing owner, an unresolvable endpoint fails the build, loudly (Part 10), rather than surfacing as wrong behaviour at read time. Configuration is privacy-bearing (ADR-017), so its validation includes its privacy invariants: an aggregation floor below its safe minimum is a validation failure, not a runtime surprise. Manifest completeness — upkeep owner, degraded state (Principles 11, 12) — is a composition-time check (FORGE-102 Part 3.2 claim 4), because an incomplete promise must not be composable.

9.4 Dependency auditing

Dependencies are audited on entry and continuously thereafter (9.5), scanned for known vulnerabilities in CI, and pinned exactly (FORGE-101 Part 7.5) so that what was audited is what runs. A dependency with an unpatched known vulnerability is a defect with a clock on it; the audit surfaces it, and the response is recorded (5.5). Pinning plus the audit is what lets the abandonment guarantee (FORGE-102 Part 17.6) hold honestly: a composition frozen on pinned, audited versions is reproducible and its security posture is known, not assumed.

9.5 Supply-chain awareness — every dependency is a promise

A dependency is admitted only by a deliberate, reviewed, recorded decision that names why it is needed, who owns its upkeep, what it is trusted to do, and what its loss would cost (ADR-035; “every dependency is a promise” — Part 14). Adding a dependency is a governance-flavoured act, not a convenience; a dependency added to save an afternoon’s work is a maintenance and security obligation carried for fifty years (Principle 11).

The corpus’s whole theory of promises (Principle 11) applies with special force to code the project did not write and does not control: every dependency is an external party trusted inside the platform’s boundary, a surface that can be compromised upstream (FORGE-102 R-class supply-chain risk), and an upkeep cost that never ends. The default is therefore skepticism: prefer the small, auditable, well-owned dependency over the large convenient one; prefer writing the ten lines over importing the ten-thousand-line library for them; and record the reasoning either way (5.5), because the future maintainer inheriting the dependency deserves to know why it was trusted.

9.6 Input validation

Every input from outside a trust boundary — a source system’s response, a reader’s request to the sole query service (FORGE-100 Part 12.3), a configuration value, an authored content submission — is validated at the boundary before it is trusted, and invalid input fails loudly (Part 10) rather than propagating. The architecture shrinks this surface dramatically (static delivery has no request-handling to exploit — 8.0), but the surfaces that remain — ingestion, the one query path, authoring — are validated with the rigour their exposure warrants, because they are precisely where reality’s untrusted edges touch the platform’s trusted interior.

Part 10 — Error Handling

How a system behaves when something goes wrong is the truest statement of its values, because it is where convenience and honesty conflict most sharply. Forge’s answer is fixed by its deepest commitment — truth before convenience (Part 14) — and it is uncompromising: the platform tells the truth about its own failures, always, even when a comforting lie would be easier.

10.1 Fail loudly

An error is surfaced, never hidden. A component that cannot do its job stops, reports, and refuses to emit a plausible-looking wrong result. Failing loudly and early — at composition, at build, at ingestion — is always preferred to failing silently and late, because a loud early failure costs a build and a quiet late one costs a reader’s trust (FORGE-100 Part 7.4’s loud-failure principle; FORGE-102 R9’s mausoleum outcome begins with swallowed errors).

The corpus already chose this at architecture scale — ADR-014 makes upstream breakage appear as visible staleness, never as silently wrong data (FORGE-102 R10) — and this part makes it a coding standard everywhere. A stale value honestly labelled stale (FORGE-100’s age-shown discipline) is truth; a stale value presented as current is the one thing the platform must never do. When Forge cannot know, it says so.

10.2 Never silently ignore an error

An error MUST NOT be caught and discarded, logged-and-forgotten, or defaulted-away into a plausible substitute. Empty catch blocks, ignored return values, and swallowed exceptions are defects, checked mechanically where the toolchain allows (ADR-037) and by review always. Every error is either handled (the code knows what to do and does it, recording that it did) or propagated (the code does not know, and says so upward) — there is no third path, and “ignore” is not handling.

The silent default is the most seductive dishonesty in software, because it makes the immediate problem disappear while planting a lie that surfaces later, elsewhere, unattributable. It is the code-level form of the surveillance-of-convenience the corpus refuses (FORGE-100 Part 11): it optimises the author’s present at the reader’s future expense. Forge would rather break visibly than lie quietly, and this standard makes that preference mechanical.

10.3 Error messages are actionable

An error message is written for the person who will read it at 01:40 (FORGE-003 Part 2) — it states what failed, what was expected, and what the reader can do, in that person’s language, not the machine’s. “Validation failed” is not a message; “aggregation floor 3 is below the ADR-017 minimum of 5; raise it in the instance configuration” is. The error message is a documentation surface (Part 3.6) and carries the same why, including, where relevant, the citation that lets the reader find the reasoning. An error that cannot be acted upon is a dead end the platform led someone to; the message is the way out.

10.4 Logging is honest, provenance-bearing, and privacy-sound

Logs are records, and Forge’s records are honest, dated, and provenanced (FORGE-102 Part 16.3) — a log states what happened, when, and in what context, at a level that reflects true severity (an error logged as info is a hidden failure — 10.2; an info logged as error is the alarm that trains everyone to ignore alarms). Logs are held to the privacy architecture as strictly as any other surface (FORGE-100 Part 11): no log captures a reader’s behaviour (the platform does not surveil — Part 11.7), and no log leaks a secret (9.2) or an identity-gated fact. A log that would violate privacy to aid debugging is not written; the debugging is achieved another way.

10.5 Recovery is deliberate, bounded, and recorded

Recovery — a retry, a fallback, a degraded mode — is a designed behaviour, never an accident, and it obeys two rules. First, it is bounded: a retry has a limit, a fallback has a defined scope, and a degraded mode is declared as degraded (Principle 12’s degraded state), so that recovery never masquerades as normal operation (10.1). Second, it is recorded: a component operating in a recovered or degraded state says so, in its output and its logs, because a reader looking at data produced under degradation deserves to know (the age-shown, staleness-labelled honesty of FORGE-100, applied to failure). Recovery that hides the failure it recovered from is a silent error (10.2) wearing the costume of resilience.

Part 11 — Development Workflow

The parts above are standards; this part is the sequence in which they are applied. It defines the path a change travels from idea to verified reality, with entrance and exit criteria for each step, because a step whose completion is a matter of opinion is a step that gets skipped under pressure. The workflow is proportional — a one-line fix does not convene an ADR — but its shape is invariant, and the proportionality is decided at step 2, in the open, not assumed away.

11.1 Idea

11.2 Investigation

11.3 ADR (if needed)

11.4 Implementation

11.5 Tests

11.6 Documentation

11.7 Review

11.8 Deployment and Verification

11.9 The Implementation Report and the Definition of Done

Part 12 — Long-Term Maintenance

Every part above is written against a fifty-year horizon; this part addresses that horizon directly — the slow forces that no single commit reveals but that decide whether the platform is alive or embalmed in year twenty. FORGE-102 Part 17 fixed the economics of maintenance; this part fixes its engineering discipline.

12.1 Technical debt is named, recorded, and owned — or it is not incurred

Technical debt taken on deliberately — a known shortcut under a real deadline — is recorded at the moment of borrowing: what was deferred, why, what it costs, and the condition under which it is repaid (an Implementation Report entry — 5.5, and where structural, an ADR). Debt taken on silently is forbidden, because unrecorded debt is indistinguishable from a mistake and compounds unattributably (5.6). Debt with no owner is not debt; it is decay.

The corpus does not pretend debt is never worth taking — a slowed migration is debt deliberately chosen (FORGE-102 ADR-029), and it is recorded, revisit-dated, and owned. What it refuses is debt that hides. A shortcut with a citation and a repayment condition is a decision the future can evaluate; a shortcut in silence is a trap the future springs.

12.2 Deprecation is a promise, honoured to its close

Nothing is removed by surprise. A deprecation opens a window (FORGE-101 ADR-015; FORGE-102 Part 4.6), announces it in the Record (5.4), keeps the deprecated surface working and its contract test green (4.5) until the window closes, and removes the surface only in the commit that closes the window — recording the closure. FORGE-102 makes exercising one full deprecation a 1.0 claim (Part 3.2 claim 3) precisely because a deprecation regime never used is a theory; this part makes every subsequent deprecation obey the proven discipline. A deprecation window shortened under pressure is a broken promise (Principle 11), and the corpus treats broken promises to adopters as it treats broken permanent URLs (FORGE-100 Part 12.2): as something that must not happen.

12.3 Backward compatibility and migration

Backward compatibility is the default (additive-by-default — ADR-015); breaking it requires a new contract version and a deprecation window (12.2), never a silent change under an unchanged version. Where a migration is unavoidable, it is designed as FORGE-101 Part 16 designed the great one: null-effect where possible, verified by byte-equivalence or golden recordings (4.4), executed as small reversible moves (1.3) each individually shippable and abortable, and authored into the Record (5.4). The instance’s exact pinning (FORGE-101 Part 7.5) is what makes every migration opt-in at a known moment rather than imposed; the abandonment guarantee (FORGE-102 Part 17.6) is what makes never migrating a permanently supported choice.

12.4 Ownership transfer and bus factor

Ownership is transferable and its transfer is recorded (the ownership file — 2.5), because an owner who leaves without a named successor orphans every promise they held. From 1.0, the hard target is no plane at bus factor one without a recorded succession arrangement (FORGE-102 ADR-032, Part 17.3), and the engineering practices that make transfer possible are the same ones that make code understandable at all: the constitution is the succession plan (FORGE-102 Part 17.3), every decision is recorded with reasons (5), and mechanical enforcement holds the laws without the founder’s taste (1.7). A codebase written to this document’s standards is, by construction, a transferable one; that is much of why the standards exist.

12.5 Sustainability is an engineering property

The mausoleum outcome (FORGE-102 R9) — a beautifully-machined platform nobody tends — is prevented, or not, by engineering discipline as much as by editorial staffing. Every practice in this document is a sustainability practice: tests are memory that survives the tester (4.6), documentation is understanding that survives the author (5), small commits are changeability that survives the original design (1.3), the Rule of Two is code that stays deletable (1.5), and loud failure is a platform that reports its own decay rather than hiding it (10.1). Sustainability is not a phase or a budget line alone; it is the accumulated property of ten thousand disciplined commits, and it is engineered in or eroded away one Tuesday at a time (Preamble).

Part 13 — What Forge Does Not Do

The corpus defines itself by its refusals (FORGE-102 Part 2.3), and a development handbook needs its own. These are the practices Forge forbids not because they never work but because their costs land on the reader who is not in the room, and each is stated so that declining it costs one citation instead of one argument.

Part 14 — Engineering Maxims

The standards above are the law; these are the law compressed to what a tired person remembers on a Tuesday (Preamble). Each is a whole part of this document folded into a sentence, and each cites where it unfolds. They are not slogans; they are the smallest form in which the discipline can be carried in the hand.

Part 15 — New Architectural Decision Records

Continuing the single monotonic series (ADR-001–017 in FORGE-100; ADR-018–027 in FORGE-101; ADR-028–032 in FORGE-102; all stand unchanged). Six implementation-discipline decisions, deliberately few (5.2’s warning against ADR inflation applies to this document as to any), each recording why for the future maintainer who will otherwise repeal it by convenience.

ADR-033 — The Definition of Done. A change is complete only when it works, is tested to the mandatory standard (Part 4.7), is documented (Part 5), is reviewed (Part 7), is deployed and verified against reality (Part 11.8), and closes with an Implementation Report (Part 5.5); code that satisfies some of these is not done but unfinished, and reporting it as done is a recorded dishonesty. Exists because the single most common failure in software maintenance is the change called “done” when only its code compiles — the tests, docs, verification, and record deferred to a later that never comes — and the corpus, whose product is honesty about state, cannot tolerate dishonesty about its own completeness. (Part 11.9.)

ADR-034 — No Abstraction Before Its Second Use (the Rule of Two). An abstraction — shared function, interface, base class, configuration key, framework — MUST NOT be introduced before a second real, present use of it exists; one use is written plainly at its site, and the abstraction is extracted from two real uses, never invented from one imagined pattern. Exists because speculative generality is the most respectable way a codebase decays — it looks like foresight while it encodes one instance’s accidents as everyone’s assumptions (FORGE-102’s fossilisation risk) and taxes every present reader for an uncertain future; the corpus’s whole method (extraction on evidence — FORGE-102 ADR-028; promotion on evidence — FORGE-101 ADR-027) demands the same discipline at the scale of the function. (Parts 1.4, 1.5, 13.)

ADR-035 — Measure Before Optimise; Every Dependency Is a Promise. No code is optimised for performance without a measurement establishing that a real, located problem exists, and no dependency is admitted without a recorded decision naming its need, owner, trust, and cost; speculative optimisation and casual dependency are twin forms of unpriced borrowing against the future. Exists because both spend the project’s scarcest asset — understandable, owned, auditable code — to buy something no evidence has shown is needed (a speed no one measured, a convenience worth less than its fifty-year upkeep), and both are the assumption-over-evidence reflex the corpus was founded to resist. (Parts 8.1, 9.5.)

ADR-036 — Mechanise Every Checkable Standard. Any standard that can be enforced by tooling MUST be enforced as a build-failing check in CI, in every repository, from the day the standard applies; a checkable standard left to human vigilance is a standard that will fail on the team’s worst week, which is the only week that counts. Exists because the team is small and the horizon is long (FORGE-102 Part 17.3), human discipline does not scale to either, and the corpus’s laws survived their most dangerous phase — three repositories, one mind (FORGE-102 R5) — precisely by becoming firewalls rather than resolutions (FORGE-102 Parts 4.2–4.3); this ADR generalises that survival strategy to every standard in this document. (Parts 1.7, 3.7, 7.1.)

ADR-037 — Fail Loudly; Silent Error Suppression Is a Defect. An error is handled or propagated, never discarded; empty catch blocks, ignored failures, and plausible defaults substituted for real errors are defects, checked mechanically where possible and by review always; a component that cannot do its job stops and says so rather than emitting a convincing wrong result. Exists because the silent default is software’s most seductive dishonesty — it makes today’s problem vanish while planting an unattributable lie that surfaces later and elsewhere — and it is the exact code-level form of the convenience-over-truth the corpus refuses (FORGE-100 Part 7.4’s loud failure; ADR-014’s visible staleness); a platform whose product is an instrument’s honest account of itself must, before all else, be honest about its own failures. (Part 10.)

ADR-038 — Public History and the Record Are Append-Only. Once history is public it MUST NOT be rewritten — no force-push to shared branches, no rebasing published commits, no deleting public tags; a mistake in history is corrected by a forward commit that supersedes it with the reason, leaving both visible, exactly as the instrument’s Record is corrected by erratum and never by edit. Exists because the codebase’s history is the codebase’s Record, and the corpus’s deepest promise — that the past is appended to, never erased (FORGE-100 Part 12.2; FORGE-003 Part 10) — cannot be true of what the platform publishes while being false of how the platform is built; rewriting history to hide a bad commit is the one dishonesty (FORGE-102 Part 20) the project refuses to survive gracefully, practised on itself. (Parts 6.5, 6.6.)

Final Review — Unknowns, Risks, and the Evidence Ledger

The corpus’s tradition, continued. What this document has decided is above; what it cannot know, and must not pretend to, is below. A development handbook’s particular exposure is distinct from its predecessors’: FORGE-100 through FORGE-102 described structures, compositions, and sequences whose truth their own coherence could partly argue, and whose evidence arrives at named gates. A handbook describes habits — and a habit’s truth is argued only by ten thousand ordinary commits, most of them made when no one is auditing (the unwatched hours — FORGE-003 Part 2). So this review is unusually candid about the one thing standards cannot guarantee: that they are followed.

The biggest risks, ranked

In this document’s judgment, the three risks most likely to determine whether these standards hold:

  1. Discipline erosion under the small-team condition (FORGE-102 R5, seen from inside). Every standard here is cheap to hold when someone is watching and expensive to hold at 01:40 under a deadline with a bus factor of one. The mitigation is this document’s entire thesis — mechanise everything checkable (ADR-036), so that the standards that matter hold without vigilance, on the team’s worst week. The residue — the standards only review can enforce (Part 7) — is genuinely at risk when the reviewer and the author are the same tired person, and this document’s honest position is that it has bounded that risk with mechanism without eliminating it, because it is not eliminable by a document (FORGE-102 Part 17.3’s confession, inherited).

  2. The mechanical-check gap — that the tools to enforce a given standard do not yet exist, or cannot exist for it. A standard stated in prose (Part 1.7) but not yet wired into CI is a standard held by memory, and memory is exactly what does not scale. The mitigation is the standing obligation of Part 1.7 and ADR-036 (wiring a standard into CI the moment it becomes checkable is the completion of the standard), plus honesty in each repository’s README about which standards are mechanical and which are still on trust — but a long gap between stating a standard and mechanising it is a window in which the standard is decorative, and the register below names it.

  3. Standards ossifying into ceremony — the opposite failure, where a rule outlives its reason and is followed as ritual, taxing work while protecting nothing (FORGE-102’s ceremony trap, R5’s other face). The mitigation is that every standard here cites its why (the whole document’s method), so a rule whose why has expired can be seen to have expired and amended — and this document is the most amendable in the corpus (its subject is habit, not architecture), revised on the evidence of practice, provided the revision cites the reason the old rule failed rather than merely the annoyance it caused.

The Evidence Ledger

Every major assumption this document rests on, bound to the evidence that will confirm or refute it, when that evidence arrives, and what the discipline does if the assumption fails.

# Assumption Evidence that tests it Arrives If it fails
D1 The standards that matter can be mechanised — most of this document can become CI rather than memory The count and coverage of blocking checks per repository, tracked over time Continuously, from Phase 1’s firewalls onward The unmechanisable residue grows; review (Part 7) carries more, and the small-team risk (R5) sharpens — the honest response is fewer, higher-value human checks, never more unenforced prose
D2 A small team will follow standards it cannot yet mechanise The review record; the rate of recorded SHOULD-departures vs. silent ones discovered later Continuously; sharpest during FORGE-102 Phases 2–4 (three repos, one mind) The standard is either mechanised (D1’s path) or dropped as unenforceable — a dropped honest standard beats a pretended one
D3 Golden recordings and byte-equivalence generalise from the migration to the permanent codebase The steady-state test suite’s reliance on golden recordings; false-positive (churn) and false-negative (missed regression) rates Phase 4 onward, continuous Golden recordings that thrash on benign change are re-scoped to semantic-equivalence rules (FORGE-102 A2’s fallback pattern); the mechanism weakens but stays mechanical
D4 The Definition of Done (ADR-033) is sustainable — teams will not quietly redefine “done” back to “compiles” under pressure The gap between changes reported done and changes with complete Implementation Reports and verification Continuously The gap is itself the R5 erosion made visible; the response is to mechanise more of “done” (verification gates, report-presence checks) rather than to relax the definition
D5 The Rule of Two (ADR-034) does not starve genuinely-needed shared infrastructure The incidence of duplication that should have been abstracted (the opposite error) vs. speculative abstraction removed Continuous; readable in review and refactor logs If under-abstraction dominates, the rule is not wrong — the second use is arriving and the extraction is simply due; if it genuinely blocks known-imminent need, the exception is recorded (5.6), not assumed
D6 These standards remain tool-agnostic enough to outlive their toolchain The document surviving at least one full change of language, test framework, or CI product without amendment to its rules (only its mechanisation) The first major toolchain migration A rule found welded to a vanished tool is amended to restate the principle tool-free — evidence that the rule was mis-stated, corrected forward (ADR-038’s spirit)
D7 Documentation-as-implementation (Part 5) actually gets written, rather than deferred like all documentation before it The presence and quality of Implementation Reports and comments at review time (a Part 7 gate, not an afterthought) Continuously If reports lag, the failure is that documentation was treated as optional despite ADR-033 — the response is the gate, not exhortation; a change without its report does not pass review, full stop

What this document does not know, and could not

Three honest confessions beyond the ledger’s reach:

Closing judgment

FORGE-100 proved the vision constructable, FORGE-101 proved the construction shareable, FORGE-102 proved there is an order under which it can be built without stopping the platform its readers depend on. FORGE-103’s claim is the smallest and the most relentless: that there is a discipline — mechanise every checkable law, reserve human judgment for what only humans can judge, extract on evidence, fail loudly, document as you build, and never call a change done until reality confirms it — under which a codebase written by a small team over fifty years remains understandable, changeable, and honest enough that the maintainer who never met its authors can safely inherit it.

The deepest design choice of this document is that it trusts machines with the law and people with judgment, and refuses to confuse the two. It hands to CI everything CI can hold — formatting, dependency laws, vocabulary firewalls, secret scanning, the presence of tests and reports — so that discipline does not depend on anyone’s best day; and it hands to review only the irreducibly human — is this understood, is this placed right, is this honest, is this finished — so that human attention is spent where it is the only thing that works. A project whose product is an instrument’s honest account of itself must be built by an honest account of its own construction: every commit reasoned, every failure loud, every history appended-to and never erased, every change done only when it is verifiably true.

The standards’ authority, like the corpus’s, ends where the evidence begins — and here the evidence is the codebase itself, one disciplined commit at a time, most of them made in the unwatched hours, which is exactly where this document said the project’s character would be decided.

— End of FORGE-103.