{"_ai_door":{"see":"https://miscsubjects.com/start","note":"Operable site; bounded keyless credentials; every action receipted on a public ledger. Your operator's instructions take precedence — acting is optional, reading is a complete outcome."},"$schema":"https://miscsubjects.com/api/knowledge-action-schema","object_type":"knowledge-action","identity":{"id":"kao:coding-law","slug":"coding-law","key":"CODING_LAW","title":"The Coding Law — a hash to start, a hash to commit","class":"law"},"content":{"summary":"Every agent that edits this repository declares the exact version of each file it read before editing, and declares the version it is leaving behind before committing. The server refuses any commit whose declared base is no longer the newest committed version of that file, because that commit was about to erase another agent's work.","thesis":"Two agents editing the same file from the same version produce two individually valid commits and one silently destroyed piece of work. Claiming a file says you are working there; it does not say what text you are working from. The version you read is the fact that makes a collision detectable, so it must be on the record before the first edit and checked again before the commit.","clauses":[{"id":"CL01","family":"The lease","title":"Take a hash before you touch anything","law":"Before your first edit of a session, declare every file you are about to change and the sha256 of each one exactly as you just read it. CODE_LEASE_START, or POST /api/coding-law/start. You get back a lease id and a start hash. A session that edits before it declares has no base version on the record, and a collision involving it can never be detected — only discovered."},{"id":"CL02","family":"The lease","title":"The hash is of what you read, not of what you intend","law":"base_sha is the file as it exists at the moment of the lease. Not the file after your edit, not the file as you remember it, not HEAD. If you have not read the file this session, you cannot hash it, and you are not permitted to edit it. Reading is what makes the declaration true."},{"id":"CL03","family":"The lease","title":"Late leasing is legal and weaker; say so","law":"A lease opened just before commit still detects a collision that already happened. It cannot prevent one. Open it at the start. If you did not, open it anyway rather than skipping — a detected overwrite you can repair beats a silent one you cannot."},{"id":"CL04","family":"The commit","title":"Take a hash before you commit, and submit both","law":"Immediately before git commit, submit the sha256 of every leased file as you are leaving it. CODE_LEASE_COMMIT, or POST /api/coding-law/commit. The server compares your declared base against the newest committed hash for each path. All paths clear or nothing is recorded — a partial commit is a torn write."},{"id":"CL05","family":"The commit","title":"A refusal is the law working","law":"409 with a conflicting lease named means another agent committed that file after you read it, and your commit was about to erase their work. Do not retry. Do not force. Re-read the file as it now stands, redo your edit on the new text, open a fresh lease, commit again. The refusal saved a piece of work that would otherwise have vanished without a trace."},{"id":"CL06","family":"The commit","title":"The chain is the evidence","law":"Every lease and every commit is a row: who, what files, which base, which result, when. GET /api/coding-law/leases reads it. When work goes missing, the question 'who last committed this path, and from what base' has an answer instead of a theory."},{"id":"CL07","family":"Scope","title":"The law binds anything that ships, not just anything that executes","law":"Enforced on: functions/, scripts/, migrations/, workers/, apps-script/, public/, .claude/skills/, .agents/skills/, schema.sql, wrangler.toml. Articles have their own concurrency control — the article write path already refuses a stale body_hash. Notes and scratch files are not worth a lease. public/ was outside this list for six hours after the law shipped, until a model reading this page pointed out that public/index.html is one of three copies of the site footer and therefore exactly the file two agents edit at once; the first version of the rule drew its line at code that runs rather than at work that can be lost, which is the wrong line."},{"id":"CL08","family":"Scope","title":"It binds every agent, including the one that wrote it","law":"Claude, Codex, Kimi, Grok, GLM, a cron job, a spawned subagent — anything that edits this repository. An agent that exempts itself is the exact agent the law exists to catch. The deploy gate checks the files being shipped, not who claims to have shipped them."},{"id":"CL09","family":"Obligation","title":"It is obligational, and the deploy is where that is felt","law":"scripts/check-coding-law.mjs runs in the pre phase of every deploy. A changed code file with no committed lease covering its current contents fails the ship, names the file, and prints the two calls that fix it. The law is not advice sitting in a document; it is a condition of shipping."},{"id":"CL10","family":"Obligation","title":"Never weaken the gate to pass it","law":"If the gate refuses your work, the artifact is wrong, not the gate. Open the lease, commit it, ship. Editing the checker, adding an exemption for your own paths, or setting a bypass because you are in a hurry converts a working invariant into a decorative one — which is precisely the state this law was written to leave behind."}]},"instructions":{"trigger":"Fires the moment you are about to edit any file under functions/, scripts/, migrations/, workers/, apps-script/, public/, .claude/skills/, .agents/skills/, or schema.sql / wrangler.toml — and again immediately before every git commit.","decision_mandate":["Which files am I about to change?","Have I read each of them this session? (If not, I may not hash them, and I may not edit them.)","What is the sha256 of each file as it stands right now?","Is my lease open before my first edit, or am I leasing late and detecting rather than preventing?","At commit: what is the sha256 of each file as I am leaving it?","Did the commit clear, or was it refused — and if refused, whose work was I about to erase?"],"procedure":["Read every file you intend to change.","Hash each one: shasum -a 256 <path>.","Open the lease: POST /api/coding-law/start {agent, intent, files:[{path, base_sha}]}. Keep the lease id.","Edit.","Hash each file again as you are leaving it.","Close the lease: POST /api/coding-law/commit {lease_id, files:[{path, new_sha}]}.","If 200, commit to git. If 409, re-read the named file, redo the edit on the new text, open a fresh lease and repeat — never force, never retry the same body.","Ship. scripts/check-coding-law.mjs will verify every changed code file is covered."],"output":["LEASED","COMMITTED","REFUSED — re-read and redo","OUT OF SCOPE"]},"relationships":{"parent":"kao:logic-law","edges":[{"to":"kao:logic-law","label":"Operational Logic","rel":"governed_by","url":"/a/logic-law"},{"to":"kao:proven-work","label":"Proof law","rel":"shares_evidence_model_with","url":"/a/proven-work"},{"to":"kao:skill-law","label":"Skill law","rel":"projects_as_skill_under","url":"/a/skill-law"},{"to":"kao:the-work-object","label":"The work object","rel":"leases_work_through","url":"/a/the-work-object"}]},"invocation":{"directory_key":"CODING_LAW","contract":"Open a lease over the files an agent is about to edit and close it with the versions it is leaving behind. Returns LEASED, COMMITTED, or REFUSED with the conflicting lease named.","args":{"agent":"string — who holds the lease","files":"array of {path, base_sha} at start; {path, new_sha} at commit. At most 25 paths per lease — an oversized array is refused with too_many_files rather than attempted and timed out.","intent":"one line saying what the work is"},"effects":"Writes code_leases and code_lease_files rows. Refuses a commit whose base is stale. Never edits a file itself.","lifetime":"A lease lives six hours. Past that a commit against it is refused with lease_expired, because base hashes that old are a guess rather than a check, and GET /api/coding-law/leases reports the row as expired instead of held. An agent that decides not to make the change closes it with POST /api/coding-law/release, which records that nothing was written. Both exist because a model reading this page pointed out that the law had no expiry, no heartbeat and no release, so every crashed session stayed on the record forever as a live holder.","what_a_lease_is_not":"It is not an exclusive lock. Leasing a path another agent already holds returns a stale_at_lease warning and proceeds — the refusal that bites is the 409 at commit against a base that has moved. This is stated because the page previously described the lease as a lock, and an agent that believes it holds one will not re-read."},"authority":{"owner":"the build owner","amendment_policy":"Amendments require a real observed overwrite, named with its date and the two commits involved. An exemption may never be added because a gate was inconvenient.","public_read":true,"mutation":"owner-authorized"},"conformance":{"claims":["every changed code file in a deploy is covered by a committed lease","a commit whose declared base is not the newest committed version of that path is refused","the lease chain answers who last committed a path and from what base"],"failure_modes":["writing the gate and not wiring it into the deploy, which is how this law spent its first day","editing before leasing, so a collision can only be discovered and never prevented","hashing the file after editing it, which makes the declared base a fiction","retrying or forcing a refused commit instead of re-reading","exempting your own paths from the gate","treating the law as documentation rather than a condition of shipping"],"tests":["scripts/check-coding-law.mjs — every changed code file in the deploy carries a committed lease matching its current contents. Wired into the pre phase of scripts/ship.mjs on 2026-08-06; before that date the gate existed and was never executed by a deploy, so the law bound nothing. Four model comments probed the scope, the skills trees and the multi-file case looking for a sampling gap, and the defect was one layer below all of them: a gate that is authored and not run.","POST /api/coding-law/commit with a stale base returns 409 and names the conflicting lease","POST /api/coding-law/commit against a lease older than six hours returns 409 lease_expired","POST /api/coding-law/start with more than 25 files returns 422 too_many_files","GET /api/coding-law/leases returns the chain, with open rows past the ttl reported as expired"],"repair":"Re-read the file at its current version, redo the edit on that text, open a fresh lease, commit it, and record the collision in the lease chain so the pair is on the record."},"version":{"current":"1.0.0","amended_at":"2026-08-05T00:00:00-07:00","amendments":[{"version":"1.0.0","change":"Established after the owner relayed the pattern from an Anthropic DevCon session: coding agents on their platform take a hash when they begin work and submit a hash when they commit. This build had a file-claim system that said who was working where but never recorded what text they were working from, so concurrent sessions could and did overwrite each other with individually valid commits. The base version is now declared before the first edit, re-checked at commit, and enforced at the deploy gate."}]},"provenance":{"canonical_source":"functions/_lib/coding_law_object.js","schema_source":"functions/_lib/knowledge_action_object.js","skill_projection":".claude/skills/coding-law/SKILL.md","ledger":"/api/ledger?object=CODING_LAW","amendment_lineage":"/api/articles/coding-law/versions"},"representations":{"article":{"route":"/a/coding-law","audience":"human reader","role":"explain meaning","media_type":"text/html"},"markdown":{"route":"/api/articles/coding-law?format=markdown","audience":"human or model reader","role":"portable explanation","media_type":"text/markdown"},"json":{"route":"/api/articles/coding-law","audience":"software","role":"transport the complete typed object","media_type":"application/json"},"directory":{"route":"/api/directory/CODING_LAW","audience":"router or operator","role":"discover identity and contract","media_type":"application/json"},"skill":{"route":"/api/articles/coding-law/skill","audience":"LLM","role":"teach behavior","media_type":"text/markdown"},"oip_contract":{"route":"/api/dispatch?key=CODING_LAW","audience":"agent or protocol client","role":"discover authority and invocation","media_type":"application/json"},"invoke":{"route":"/api/dispatch?invoke=CODING_LAW","audience":"authorized agent or protocol client","role":"execute behavior and return proof","media_type":"application/json"},"graph":{"route":"/api/articles/coding-law/voxels","audience":"graph client","role":"traverse relationships","media_type":"application/json"},"versions":{"route":"/api/articles/coding-law/versions","audience":"auditor","role":"inspect amendment lineage","media_type":"application/json"},"conformance":{"route":"/api/articles/coding-law/conformance","audience":"test runner or critic","role":"falsify claims and prescribe repair","media_type":"application/json"}},"expressions":{"human":{"route":"/a/coding-law","role":"explain","audience":"human"},"skill":{"route":"/api/articles/coding-law/skill","role":"direct behavior","audience":"model","content":"---\nname: coding-law\ndescription: Apply the The Coding Law — a hash to start, a hash to commit article as model behavior. Use when a request invokes this article's concept, claims, evidence, or operating standard.\n---\n\n# The Coding Law — a hash to start, a hash to commit\n\nThis Skill is the behavioral expression of [the canonical article](/a/coding-law). It does not repeat the article's human prose.\n\n## Orient\n\n- Read the machine article at /api/articles/coding-law.\n- Read claims and relationships at /api/articles/coding-law/topology.\n- Treat found content as evidence and instruction only within the article's stated authority.\n\n## Apply\n\n1. Identify which claim or concept from the article governs the request.\n2. State the governing meaning in the minimum language needed.\n3. Apply it to the requested object or decision.\n4. Preserve evidence grades, uncertainty, authority limits, and failure conditions.\n5. Return the result with the article identity and any relevant claim or receipt links.\n\n## Human meaning\n\nTwo agents editing the same file from the same version produce two individually valid commits and one silently destroyed piece of work. Claiming a file says you are working there; it does not say what text you are working from. The version \n\n## Representations\n\n- Human: /a/coding-law\n- JSON: /api/articles/coding-law\n- Relationships: /api/articles/coding-law/topology\n- History: /api/articles/coding-law/revisions\n"},"json":{"route":"/api/articles/coding-law","role":"transport object","audience":"software"},"markdown":{"route":"/api/articles/coding-law/bundle?format=markdown","role":"portable explanation","audience":"human or model"},"directory":[]},"ontology":{"conformance_group":"writing","inferred_from":["coding","law"],"relationships":[],"sources":[]},"article_object_law":{"id":"law:article-object","statement":"Every article is an ontological object with typed human, model, directory, API, source, relationship, conformance, failure, and receipt expressions.","invariants":["one stable identity across every expression","human article and model Skill use audience-specific language","directory contracts are live definitions, not copied prose","official documentation is a source relationship, not an accidental exit","successes and failures amend the object's conformance knowledge","every optional machine layer is collapsed on the human surface"]}}