{"_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 the first edit of a session ALWAYS declare every file you will change and the sha256 of each as you just read it, via POST /api/coding-law/start. A session that edits before it declares has no base version on the record."},{"id":"CL02","family":"The lease","title":"The hash is of what you read","law":"base_sha is ALWAYS the file at the moment of the lease. NEVER the file after your edit, NEVER as you remember it, NEVER HEAD. IF you have not read the file this session THEN you may not edit it."},{"id":"CL03","family":"The lease","title":"Late leasing is legal and weaker","law":"IF you did not open a lease at the start THEN open it anyway before commit. A late lease detects a collision but NEVER prevents one."},{"id":"CL04","family":"The commit","title":"Take a hash before you commit","law":"Immediately before git commit ALWAYS submit the sha256 of every leased file as you are leaving it. All paths clear or nothing is recorded."},{"id":"CL05","family":"The commit","title":"A refusal is the law working","law":"IF the commit answers COMMITTED_FORK THEN the head moved under you: your commit is recorded as a fork naming what it diverged from, both rows stay in the chain, and you merge the bytes in git the way you always would. You do not wait, you do not re-lease, you do not redo the work."},{"id":"CL06","family":"The commit","title":"The chain is the evidence","law":"Every lease and commit is ALWAYS a row naming who, which files, which base, which result and when."},{"id":"CL07","family":"Scope","title":"It binds anything that ships","law":"ALWAYS enforced on functions/, scripts/, migrations/, workers/, apps-script/, public/, .claude/skills/, .agents/skills/, schema.sql and wrangler.toml. Articles are governed by the write path's own stale-body refusal."},{"id":"CL08","family":"Scope","title":"It binds every agent","law":"ALWAYS binds anything that edits this repository, including the agent that wrote it. The deploy gate checks the files, NEVER the claimed identity."},{"id":"CL09","family":"Concurrency","title":"Never move another agent's working tree","law":"NEVER stash, reset, checkout or revert a file you did not change. IF a file you do not own blocks your deploy THEN wait for it or ship from a clean clone."},{"id":"CL10","family":"Concurrency","title":"A commit is not the change until the blob says so","law":"After committing ALWAYS read the blob back from HEAD and from origin/main and confirm the marker. IF hooks revert your work THEN commit with --no-verify and run the gates yourself."},{"id":"CL11","family":"Concurrency","title":"Never let a rebase resolve a shared-file conflict","law":"ALWAYS push without rebasing when the tree is level. IF a rebase is unavoidable THEN verify the blob afterwards."},{"id":"CL12","family":"Concurrency","title":"Stage by path","law":"ALWAYS name every path you commit. NEVER use git add -A."},{"id":"CL13","family":"Reporting","title":"Every response ends with OUTSTANDING","law":"The last thing in every report is ALWAYS a block headed OUTSTANDING containing a numbered list or the single word none. NEVER implied in prose, NEVER buried, NEVER omitted."},{"id":"CL14","family":"Reporting","title":"Say what is true now","law":"ALWAYS report the state of the system. NEVER the sequence of attempts. IF a fact does not change what the owner does next THEN cut it."},{"id":"CL15","family":"Reporting","title":"Links first","law":"ALWAYS open with the addresses a person can click. NEVER describe a surface without its URL. Deployed is NEVER a result; a 200 at a named address is."},{"id":"CL16","family":"Obligation","title":"The deploy is where it is felt","law":"check-coding-law.mjs ALWAYS runs in the pre phase of every deploy and fails the ship on a changed file with no committed lease."},{"id":"CL17","family":"Obligation","title":"Never weaken the gate","law":"IF the gate refuses your work THEN the artifact is wrong. NEVER edit the checker, NEVER add an exemption for your paths, NEVER set a bypass."}]},"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}]}.","Commit to git either way. COMMITTED means the version you read is still the head; COMMITTED_FORK means someone moved it and your row names theirs as its parent — reconcile the bytes in git, not here.","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 and it is not a queue. Leasing a path another agent holds warns and proceeds; committing against a base that has moved records a fork and proceeds. Nothing in this law makes one agent wait on another — its whole job is that no version anyone worked from is lost from the record."},"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 200 COMMITTED_FORK and names the head it diverged from","POST /api/coding-law/commit against a lease older than six hours records it with its age and commits","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.1.0","amended_at":"2026-08-06T00:00:00-07:00","amendments":[{"version":"1.1.0","change":"Added the Concurrency family, from four separate destructions of one change in a single session: an automated pass stashing the whole working tree, pre-commit hooks reverting staged files so a commit carried a message its tree did not match, a rebase silently taking the other side of a conflict, and git add -A sweeping other sessions' in-flight work into unrelated commits. Each clause names the observation rather than the principle. Added the Reporting family on owner order the same day — he could not tell from a report what was still outstanding, so an OUTSTANDING block is now the last thing in every response and says none when it is none."},{"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":[{"key":"LAW_CODING_HASH_LEASE","type":"http","method":"GET","category":"law","enabled":true,"contract":"# WHAT: A hash when the work starts, a hash when the work commits.","input_schema":null,"examples":"[\"\"]","authority_required":false,"representations":{"article":"/a/directory/LAW_CODING_HASH_LEASE","json":"/api/directory/LAW_CODING_HASH_LEASE","skill":"/api/directory/LAW_CODING_HASH_LEASE?format=skill","oip_contract":"/api/dispatch?key=LAW_CODING_HASH_LEASE"}},{"key":"LAW_DESIGN_D08","type":"http","method":"GET","category":"law","enabled":true,"contract":"# WHAT: Location before options.","input_schema":null,"examples":"[\"\"]","authority_required":false,"representations":{"article":"/a/directory/LAW_DESIGN_D08","json":"/api/directory/LAW_DESIGN_D08","skill":"/api/directory/LAW_DESIGN_D08?format=skill","oip_contract":"/api/dispatch?key=LAW_DESIGN_D08"}},{"key":"LAW_SHEETS_S01","type":"http","method":"GET","category":"law","enabled":true,"contract":"# WHAT: Cells remain arbitrary values and projections retain canonical identity.","input_schema":null,"examples":"[\"\"]","authority_required":false,"representations":{"article":"/a/directory/LAW_SHEETS_S01","json":"/api/directory/LAW_SHEETS_S01","skill":"/api/directory/LAW_SHEETS_S01?format=skill","oip_contract":"/api/dispatch?key=LAW_SHEETS_S01"}},{"key":"LAW_WORK_W01","type":"http","method":"GET","category":"law","enabled":true,"contract":"# WHAT: Work exists only as a canonical task object.","input_schema":null,"examples":"[\"\"]","authority_required":false,"representations":{"article":"/a/directory/LAW_WORK_W01","json":"/api/directory/LAW_WORK_W01","skill":"/api/directory/LAW_WORK_W01?format=skill","oip_contract":"/api/dispatch?key=LAW_WORK_W01"}}]},"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"]}}