Don't merge a change you can't explain

git clone https://github.com/tacoda/fulcorum-comprehension-standard.git

# 1. the claim: every PR now asks for four fields
cp fulcorum-comprehension-standard/.github/pull_request_template.md .github/

# 2. the gate: refuse a PR whose block is missing or unfilled
cp fulcorum-comprehension-standard/hooks/comprehension-gate.py .github/scripts/

# 3. the law: put it where the agent reads it, not just where people do
cat fulcorum-comprehension-standard/LAW.md >> CLAUDE.md

Then decide one thing as a team and write it down: which changes require which level (section 4). That decision is the standard. Everything else is plumbing.

"Explain" is doing real work in that sentence, so pin it down. Explaining is not summarizing the diff back. A diff summary is a restatement of syntax, and the agent will write you a beautiful one on request. Explaining means you can say what the change does to the system, where it enters and where it leaves, and what rule it obeys. Then the hard one: what would have to be true for it to be wrong. Those four things are section 2.

The law binds the person who merges, not the person or process that wrote the code. That distinction is the point. When an agent writes the change, authorship stops being a useful place to put accountability. The author has none: it doesn't get paged, doesn't sit in the postmortem, doesn't answer for the outage. Merging is the last human decision in the chain, so that is where the obligation lands.

comprehension:
  does:      <what this change does to the system, in one sentence>
  seam:      <where it enters> -> <where it leaves>
  policy:    <the rule or doc this obeys>   | CHARTER-GAP
  falsifier: <the case that would make this wrong>
             covered by: <test name>         | NONE

1. does One sentence, about behavior, not about code. "Adds a helper and updates two callers" is a description of the diff. "Cash totals now round down to the nickel instead of to the nearest one" is a description of the change. If the sentence needs an "and" you may be merging two changes.
2. seam Entry and exit. Where does data reach this code, and where does the effect land: a response, a row, a file, a charge. This field catches the author who read the function but not its callers, which is the most common way a change looks understood and is not.
3. policy Cite the rule this obeys. A charter rule, a doc, a ticket, an ADR. If nothing in the repo answers "why is it written this way," write CHARTER-GAP and open an issue. That is a finding, not a failure, and it is one of the more valuable things a junior produces.
4. falsifier Name the case that would make this wrong, then name the test that covers it. That pairing separates reading from understanding. If you cannot describe a world in which this change is incorrect, you don't yet know what it does. The standard allows NONE, and it means you shipped a declared risk instead of a hidden one.

Four fields, well under a minute when you actually understand the change, and genuinely hard when you don't. That asymmetry is the entire mechanism. The block is not paperwork about the work, it is the shortest test that the work was understood.

The jump from L1 to L2 is the one that matters and the one people skip. L1 is a description, and an agent can hand you a correct description of code that is quietly wrong. L2 requires you to have imagined the failure and gone looking for it. That is the habit the whole standard exists to install, and it is exactly the habit that shipping-fast erodes first.

L3 is where architecture lives. Most contested engineering decisions have several answers that all work, and the right one is the one consistent with how this system already does things. An agent optimizes for a working answer and has no stake in that consistency, which is why drift compounds silently in agent-heavy codebases.

1. Default L2 for ordinary changes. All four fields, a real falsifier, a test that covers it. That is the working bar, and it should feel routine, not ceremonial.
2. Raise to L3 Money, security and authorization, data integrity and migrations, anything with a written policy, and anything you cannot cheaply roll back. These are the changes where a plausible answer and a correct answer diverge quietly and expensively.
3. Drop to L1 Changes with no semantics: formatting, generated files, copy edits, dependency bumps with an unchanged lock. Name the categories explicitly in your charter, because an unwritten exemption list expands to fit the deadline.
4. Never L0 L0 describes what green means, not a bar anyone may merge at. It exists in this document so that "the tests passed" has a name, and so a reviewer can call it the non-claim it is.

One rule of thumb keeps the L3 list honest: ask what the cost is of being confidently wrong. If the answer is a refund program, an incident, a regulator, or a migration you cannot reverse, it is L3. If the answer is a follow-up commit, it is L2.

A team conforms to CS v0.1 if all five of these hold:

1. 1 · The law The law lives in the charter the agent reads, not only in a wiki page humans have bookmarked. If the agent never sees it, it is not part of the system.
2. 2 · The claim Every merged pull request carries a filled comprehension block, written by the person requesting the merge.
3. 3 · The bar The team writes the merge bar down, including the L3 list and the exemption list. Exceptions go in the PR, never silently.
4. 4 · The gaps CHARTER-GAP reaches a human who owns and answers it. If people only type it into a box and never read it, field three of the block is theater.
5. 5 · The review Reviews examine the claims, not only the diff, and a reviewer who never disputes a falsifier is not reviewing comprehension. Reverse-review is the exercise that trains this.

1 · The template asks

## What and why

<!-- Required by the Comprehension Standard v0.1. Write this yourself,
     before you ask the agent for anything. Level: L2 default, L3 for
     money, security, data integrity, or a written policy. -->

```comprehension
does:
seam:
policy:
falsifier:
           covered by:
```

level: L2
exception: none

2 · The gate refuses

import re, sys

REQUIRED = ("does", "seam", "policy", "falsifier")
PLACEHOLDER = re.compile(r"^(todo|tbd|n/?a|\.+|\?+)$", re.I)

def check(body):
    block = re.search(r"```comprehension\n(.*?)```", body, re.S)
    if not block:
        return ["no comprehension block in the PR body"]

    text = block.group(1)
    # [ \t] not \s: \s spans newlines, so an empty field eats the next one
    fields = dict(re.findall(r"^[ \t]*(\w+):[ \t]*(.*)$", text, re.M))
    problems = []
    for name in REQUIRED:
        value = fields.get(name, "").strip()
        if not value:
            problems.append(f"{name}: empty")
        elif PLACEHOLDER.match(value):
            problems.append(f"{name}: placeholder ({value!r})")

    falsifier = fields.get("falsifier", "").strip()
    if falsifier and falsifier.upper() != "NONE":
        if not re.search(r"covered by:[ \t]*\S+", text):
            problems.append("falsifier: named, but no covering test")
    return problems

if __name__ == "__main__":
    found = check(sys.stdin.read())
    for p in found:
        print(f"comprehension-gate: {p}")
    sys.exit(1 if found else 0)

Roughly twenty-five lines, and that is the whole enforceable surface. Everything else in this document is a decision a team makes. That split is the right division of labor: machines are good at insisting a step happened, and bad at judging whether it happened well.

Non-goals

• Not a certification. No badge, no exam, no auditor, no registry. If someone sells you compliance with this, they made that up.
• Not a performance metric. Block fill rate never belongs in a review packet: score it and you will get four true sentences guarding a change nobody read.
• Not a replacement for tests, types, static analysis, or review. It sits on top of those and assumes they exist.
• Not a maturity model. There are no organizational tiers to ascend. A team either does the five things in section 5 or does not.
• Not anti-agent. Use the agent for everything, including as a tutor on the code it just wrote, because the standard governs what you merge, not what you generate.

Where it is weakest

• falsifier is the field people fake first. The tell is a falsifier restating the happy path inverted ("it would be wrong if it returned the wrong value"). A real falsifier, by contrast, names a specific input and a specific wrong outcome.
• The standard is uncomfortable on very large diffs. One sentence for a 900-line change is either a lie or an argument for splitting the change. Usually the second.
• It does nothing for code already merged. This is a bar on new changes. Comprehension debt already in the tree needs a different instrument.
• v0.1 is small-team evidence. It has been used on small teams. There is no data on how it behaves across a large organization, and claiming otherwise would be exactly the kind of plausible, unfalsifiable statement this document exists to catch.

Forking

• Keep the law. Everything else is implementation. A fork that drops the law is a different document and should have a different name.
• Change the fields to fit your domain. A team shipping infrastructure might swap seam for blast-radius. A team on regulated data might add data-class. Four to five fields is the working range, and past that people stop reading them.
• Set your own L3 list. The one in section 4 is a starting point, not a claim about your business.
• Version your fork and date it. A standard nobody can cite by version cannot be argued with, and being arguable is most of the value.

What would move this to v0.2

• Field names that survived contact with teams that did not write them.
• An exemption list that stopped needing constant patching, which is the signal it finally describes reality.
• Actual evidence about faking: how often blocks are filled fluently and wrongly, and whether reviewers catch it, because that number decides whether this standard does anything at all.