{
  "schema": "org-writing@v1",
  "slug": "justification-travels-in-the-diff",
  "kg": {
    "id": "org:writing:justification-travels-in-the-diff",
    "type": "brick",
    "graph": "/kg.json"
  },
  "title": "Justification travels in the diff",
  "subtitle": "An approval recorded outside the change it approves has approved nothing",
  "abstract": "How to tell a real approval from a filed one, and why three unrelated parts of our own tooling reached the same placement rule without consulting each other. The canonical treatment of co-located justification.",
  "kind": "brick",
  "topics": [
    "Approval"
  ],
  "courseMemberships": [
    {
      "course": "org:courses:approval",
      "topic": "Approval",
      "wall": "org:walls:ethics",
      "position": 1,
      "total": 5
    }
  ],
  "publishedAt": "2026-08-03T00:00:00.000Z",
  "version": 1,
  "guidelinesVersion": 15,
  "brief": {
    "problem": {
      "text": "Rules, rulings, and approvals are naturally filed where rules live, in a policy file or a decision log, while the reviewer who has to act on them is reading a bounded set of added and removed lines and nothing else.",
      "claims": [
        "treats a marker in a sibling file"
      ]
    },
    "mechanism": {
      "text": "A justification held anywhere except inside the change is absent at the instant the decision is made, which is why the oldest working version of this rule puts the certification in the commit rather than in a register.",
      "claims": [
        "a Signed-off-by line inside the commit"
      ]
    },
    "move": {
      "text": "Put the reason where the change is. If a rule governs an edit, it belongs in the same diff as the edit, and a system that cannot arrange that has separated its reasons from its decisions on purpose.",
      "claims": []
    }
  },
  "sources": [
    {
      "repo": "mnstry-atelier",
      "path": "docs/repo-boundary-guard.md"
    },
    {
      "repo": "mnstry-website",
      "path": "AGENTS.md"
    },
    {
      "repo": "mnstry-website",
      "path": "DESIGN.md"
    }
  ],
  "canonicalPath": "/writing/justification-travels-in-the-diff/",
  "body": "A rule belongs in the rules file. That is where it can be maintained, where the next person will look for it, and where it stops being scattered across a hundred places that each drift on their own schedule. Every instinct a well-organized repository trains points that way, and the instinct is right nearly always. It is wrong at exactly one moment, and that moment is the one where the rule was supposed to do its work.\n\nThe moment is review. Somebody approving a change does not read the repository. They read the change, a bounded set of removed and added lines, and they decide on the evidence inside that boundary. Whatever sits outside it is not evidence they have, however true it is and however carefully it was written. Our own boundary guard states the consequence without softening it. To widen the exposure of a document, an approval marker has to travel in the same file's diff as the change it approves, and a marker committed in a sibling file, or already sitting elsewhere in a file this commit does not touch, approves nothing at all. The guard reads the diff, not the working tree.\n\nThe mechanism is that a justification held anywhere except inside the change is absent at the instant the decision is made, so the reviewer approves an unexplained edit while a perfectly good explanation sits somewhere else being correct and unread.\n\nWe did not set that down as a house rule and then apply it three times. It arrived three times, in different repositories, written by different hands against different problems, and none of the three cites either of the others. The boundary guard's version governs disclosure. Our website repository carries a second version in its standing instructions for agents, which is that operator feedback becomes a dated ruling in the same commit as the fix, and that a change altering rendered appearance without updating that ledger is incomplete rather than merely undocumented. The design authority in the same repository carries a third, which is that a fix promoted into the shared foundation package moves as code, validator, registry entry, and canonical documentation in one change or does not move. Disclosure review, design authority, and package promotion share almost nothing except that each is a place where a decision has to survive being read later, by someone who was not there when it was made.\n\nThe oldest version of the rule is twenty years old and was written under legal pressure. When litigation over the origins of kernel code made contribution provenance a live question in 2004, Linux adopted the Developer Certificate of Origin, and the durable thing about it is where the certification goes. Not into a contributor register, not into a signed agreement filed with a foundation, but into the commit itself, as a Signed-off-by line attached to the change it certifies. This corpus has already argued the attribution half of that decision, that a shared structure needs every piece to carry its maker's name. The placement half is the one at issue here, and it is why the practice still works across tens of thousands of contributors. The certificate cannot be separated from the code without deleting it.\n\nWhat makes this urgent rather than tidy is who writes the changes now. An agent can produce a paragraph of justification on demand, and the cheapest place to put that paragraph is a document nobody diffs, where it will read beautifully and be consulted by no one. A reviewer facing forty machine-proposed changes before lunch will read forty diffs, and forty explanations filed elsewhere will go unread in a way that leaves no trace, because unread is not a state any system reports. Co-location is not a filing convention. It is the only arrangement in which a reason and the thing it justifies reach the same pair of eyes in the same breath, and a reason that arrives with its change is still working on the busiest morning of the year, when every policy nobody has time to open has quietly stopped.",
  "apparatus": {
    "note": "The human-facing essay is deliberately practical; this apparatus carries the full references, evidence-graded claims, article-local concepts, and research context behind it. Canonical concept definitions come from the concept registry.",
    "references": [
      {
        "id": "org:references:justification-travels-in-the-diff:r01",
        "author": "MNSTRY Atelier",
        "work": "Repo Boundary Guard V1, the staged boundary field review",
        "year": 2026,
        "relevance": "The primary artifact and the sharpest statement of the rule. The staged guard inspects diffs for boundary-field changes and accepts an approval marker only inside the same file's diff, on the stated ground that the guard reads the diff and not the working tree."
      },
      {
        "id": "org:references:justification-travels-in-the-diff:r02",
        "author": "MNSTRY (website repository)",
        "work": "Standing agent instructions, the authority chain",
        "year": 2026,
        "relevance": "The second independent instance. Operator feedback becomes a dated ruling in the same commit as the fix, and a change altering rendered appearance without updating that ledger is classed incomplete rather than undocumented."
      },
      {
        "id": "org:references:justification-travels-in-the-diff:r03",
        "author": "MNSTRY (website repository)",
        "work": "The design authority document, foundation promotion",
        "year": 2026,
        "relevance": "The third independent instance, applied to package promotion rather than review. A fix promoted into the shared foundation moves as code, validator, registry entry, and canonical documentation in one change."
      },
      {
        "id": "org:references:justification-travels-in-the-diff:r04",
        "author": "Open Source Development Labs, and the Linux kernel maintainers",
        "work": "The Developer Certificate of Origin, version 1.1, and the Signed-off-by convention",
        "year": 2004,
        "relevance": "The oldest working version of the placement rule, and the external case the brick anchors on. Cited for where the certification lives, not for the attribution argument, which belongs to Signed stones."
      },
      {
        "id": "org:references:justification-travels-in-the-diff:r05",
        "author": "MNSTRY (this corpus)",
        "work": "'Structural, not behavioral' (the parent essay)",
        "year": 2026,
        "relevance": "The frame. Asking reviewers to consult a policy file is behavioral; arranging the format so the reason and the change arrive together is structural."
      }
    ],
    "claims": [
      {
        "id": "org:claims:justification-travels-in-the-diff:c01",
        "claim": "The Atelier boundary guard requires an approval marker to travel in the same file's diff as the boundary-field change it approves, and treats a marker in a sibling file, or one already sitting in an untouched part of the working tree, as approving nothing.",
        "basis": "The staged boundary field review section of the guard document, read directly on 2026-08-03; the wording is the document's own.",
        "confidence": "verified",
        "sources": []
      },
      {
        "id": "org:claims:justification-travels-in-the-diff:c02",
        "claim": "The website repository's standing agent instructions require operator feedback to become a dated ruling in the same commit as the fix, and declare a change that alters rendered appearance without updating that ledger incomplete.",
        "basis": "The authority chain section of the repository's agent instructions, read directly on 2026-08-03.",
        "confidence": "verified",
        "sources": []
      },
      {
        "id": "org:claims:justification-travels-in-the-diff:c03",
        "claim": "The website design authority requires a fix promoted into the shared marketing foundation package to move as code, validator, registry entry, and canonical documentation in a single change.",
        "basis": "The design document's foundation-promotion paragraph, read directly on 2026-08-03.",
        "confidence": "verified",
        "sources": []
      },
      {
        "id": "org:claims:justification-travels-in-the-diff:c04",
        "claim": "The Developer Certificate of Origin, adopted by the Linux kernel in 2004 during litigation over the provenance of kernel code, records a contributor's certification as a Signed-off-by line inside the commit that carries the change, rather than in a separate contributor register.",
        "basis": "The certificate text and the kernel's submitting-patches documentation; the 2004 adoption and its litigation context are uncontroversial public record.",
        "confidence": "verified",
        "sources": []
      },
      {
        "id": "org:claims:justification-travels-in-the-diff:c05",
        "claim": "The three placement rules were written independently, across two repositories, against three different problems, and none of them cites either of the others.",
        "basis": "A read of all three documents on 2026-08-03 finding no cross-reference. Independence is inferred from the absence of citation and from the differing problem domains, not established by authorship records.",
        "confidence": "directional",
        "sources": []
      }
    ],
    "concepts": [
      {
        "id": "org:concepts:justification-in-the-diff",
        "name": "Justification in the diff",
        "definition": "A rule, ruling, or approval takes effect only where a reviewer will encounter it, which is inside the diff of the change it governs. A reviewer reads a bounded set of removed and added lines and decides on that evidence, so a justification held in a policy file, a decision log, or an untouched region of the working tree is absent at the moment of decision and approves nothing. The placement is structural rather than editorial: it is what makes the reason and the change reach the same reader in the same breath.",
        "provenance": "canonical"
      }
    ],
    "researchContext": "Sourced from three of our own repositories and one external convention, a\npairing chosen because the argument is the convergence rather than any one\nstatement of the rule. No client, tenant, or product material is involved,\nand no path, branch, or commit identifier appears in the prose; the source\nlabels name repositories and documents only.\n\nThe brick's contribution is treating the placement of a justification as a\nstructural property rather than a documentation preference, and reading the\nthree independent arrivals as evidence rather than as repetition. The\nattribution half of the Developer Certificate of Origin is credited to\n\"Signed stones\" and deliberately not re-argued here. That brick owns the\nclaim that a shared structure needs every piece to carry its maker's name;\nthis one owns the narrower claim about where the mark has to sit.\n\nGrading note: the independence claim is directional on purpose. Three\ndocuments that do not cite one another is evidence of convergence and not\nproof of it, and the honest form of the argument survives if one author\nturns out to have read another, because the three rules still govern three\nunrelated problems. Do not upgrade it without authorship evidence.\n\nBoundary with the parent essay: \"Structural, not behavioral\" argues that a\nguarantee resting on shape beats one resting on a promise. This brick applies\nthat to the review step itself, where asking a reviewer to go and read the\npolicy is the promise and putting the policy in the diff is the shape."
  },
  "contract": "https://mnstry.org/contracts/org/org-writing.v1.schema.json",
  "releaseHash": "68d4217338b6f730462a56ed6ec7ae8ca9f41627f67695a8b424e1d54c82185b",
  "versions": [
    {
      "version": 1,
      "cutAt": "2026-08-03",
      "note": "Initial publication, boundary wave",
      "visibility": "published",
      "path": "/writing/justification-travels-in-the-diff/",
      "contentHash": "sha256:d03e0df0532bd8c8",
      "releaseHash": "68d4217338b6f730462a56ed6ec7ae8ca9f41627f67695a8b424e1d54c82185b"
    }
  ]
}