{
  "_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."
  },
  "name": "coding-law",
  "family": "code discipline",
  "description": "Use before the first edit of any file under functions/, scripts/, migrations/, workers/, apps-script/, .claude/skills/, .agents/skills/, schema.sql or wrangler.toml — and again immediately before every git commit. Take a hash when work starts, submit a hash when work commits. Prevents two agents from silently overwriting each other with individually valid commits.",
  "body": "\n# Coding Law — a hash to start, a hash to commit\n\n## The failure this exists to stop\n\nTwo agents read the same file at the same version. Both edit from that version. The second to commit\nerases the first one's work. Nothing notices: each commit is individually valid and each diff applied\ncleanly to the version its author held. The loss surfaces days later as \"why is that fix gone?\".\n\nClaiming a file does not fix this. A claim says *I am working here*. It does not say *here is the\nexact text I am working from* — and that text is the only fact that makes a collision detectable.\n\n## The procedure\n\n**1. Read the files you are going to change.** You may not hash a file you have not read this\nsession, and you may not edit a file you have not hashed.\n\n**2. Hash them.**\n```bash\nshasum -a 256 functions/a/[slug].js functions/_lib/article_ledger.js\n```\n\n**3. Open the lease — before your first edit.**\n```bash\ncurl -s -X POST https://miscsubjects.com/api/coding-law/start \\\n  -H 'content-type: application/json' \\\n  -d '{\"agent\":\"<yours>:<session prefix>\",\"intent\":\"<one line>\",\n       \"files\":[{\"path\":\"functions/a/[slug].js\",\"base_sha\":\"<sha>\"}]}'\n```\nKeep the `lease_id`.\n\n**4. Edit.**\n\n**5. Hash again, and close the lease — immediately before `git commit`.**\n```bash\ncurl -s -X POST https://miscsubjects.com/api/coding-law/commit \\\n  -H 'content-type: application/json' \\\n  -d '{\"lease_id\":\"lease_…\",\"files\":[{\"path\":\"functions/a/[slug].js\",\"new_sha\":\"<sha>\"}]}'\n```\n\n**6. Read the answer.**\n- `200 {\"state\":\"committed\"}` — commit to git and ship.\n- `409 {\"error\":\"overwrite_refused\"}` — another agent committed that file after you read it. **Your\n  commit was about to erase their work.** Re-read the file as it now stands, redo your edit on the new\n  text, open a fresh lease, and repeat. Never force. Never retry the same body.\n\n## Scope\n\nEnforced: `functions/`, `scripts/`, `migrations/`, `workers/`, `apps-script/`, `public/`,\n`.claude/skills/`, `.agents/skills/`, `schema.sql`, `wrangler.toml`.\n\nNot enforced: articles (the article write path already refuses a stale `body_hash`), notes, scratch\nfiles, generated output.\n\n## Obligation\n\n`scripts/check-coding-law.mjs` runs in the pre phase of every deploy. A changed code file with no\ncommitted lease matching its current contents fails the ship and prints the two calls above.\n\n**If the gate refuses you, the artifact is wrong — not the gate.** Do not edit the checker, do not add\nan exemption for your own paths, do not set a bypass because you are in a hurry. That is how a working\ninvariant becomes a decorative one.\n\n## Red flags — stop and lease\n\n- \"I'll just patch this one line.\"\n- \"Nobody else is in this file right now.\"\n- \"I'll lease it after I see if the change works.\"\n- Reaching for Edit or Write on a code path with no `lease_id` in your context.\n- A 409 you are about to retry unchanged.\n\n## Verify\n\nBefore the first edit: read ✓ → hash ✓ → `start` returned a `lease_id` ✓.\nBefore every commit: hash ✓ → `commit` returned 200 ✓ → `git commit`.\n\n## Related\n\n- [Shared Write Law](../shared-write-law/SKILL.md) — the file claim. Complementary: the claim says who,\n  this says from what version. Both, not either.\n- Live law: https://miscsubjects.com/a/coding-law\n- The chain: https://miscsubjects.com/api/coding-law/leases\n",
  "raw": "---\nname: coding-law\ndescription: Use before the first edit of any file under functions/, scripts/, migrations/, workers/, apps-script/, .claude/skills/, .agents/skills/, schema.sql or wrangler.toml — and again immediately before every git commit. Take a hash when work starts, submit a hash when work commits. Prevents two agents from silently overwriting each other with individually valid commits.\n---\n\n# Coding Law — a hash to start, a hash to commit\n\n## The failure this exists to stop\n\nTwo agents read the same file at the same version. Both edit from that version. The second to commit\nerases the first one's work. Nothing notices: each commit is individually valid and each diff applied\ncleanly to the version its author held. The loss surfaces days later as \"why is that fix gone?\".\n\nClaiming a file does not fix this. A claim says *I am working here*. It does not say *here is the\nexact text I am working from* — and that text is the only fact that makes a collision detectable.\n\n## The procedure\n\n**1. Read the files you are going to change.** You may not hash a file you have not read this\nsession, and you may not edit a file you have not hashed.\n\n**2. Hash them.**\n```bash\nshasum -a 256 functions/a/[slug].js functions/_lib/article_ledger.js\n```\n\n**3. Open the lease — before your first edit.**\n```bash\ncurl -s -X POST https://miscsubjects.com/api/coding-law/start \\\n  -H 'content-type: application/json' \\\n  -d '{\"agent\":\"<yours>:<session prefix>\",\"intent\":\"<one line>\",\n       \"files\":[{\"path\":\"functions/a/[slug].js\",\"base_sha\":\"<sha>\"}]}'\n```\nKeep the `lease_id`.\n\n**4. Edit.**\n\n**5. Hash again, and close the lease — immediately before `git commit`.**\n```bash\ncurl -s -X POST https://miscsubjects.com/api/coding-law/commit \\\n  -H 'content-type: application/json' \\\n  -d '{\"lease_id\":\"lease_…\",\"files\":[{\"path\":\"functions/a/[slug].js\",\"new_sha\":\"<sha>\"}]}'\n```\n\n**6. Read the answer.**\n- `200 {\"state\":\"committed\"}` — commit to git and ship.\n- `409 {\"error\":\"overwrite_refused\"}` — another agent committed that file after you read it. **Your\n  commit was about to erase their work.** Re-read the file as it now stands, redo your edit on the new\n  text, open a fresh lease, and repeat. Never force. Never retry the same body.\n\n## Scope\n\nEnforced: `functions/`, `scripts/`, `migrations/`, `workers/`, `apps-script/`, `public/`,\n`.claude/skills/`, `.agents/skills/`, `schema.sql`, `wrangler.toml`.\n\nNot enforced: articles (the article write path already refuses a stale `body_hash`), notes, scratch\nfiles, generated output.\n\n## Obligation\n\n`scripts/check-coding-law.mjs` runs in the pre phase of every deploy. A changed code file with no\ncommitted lease matching its current contents fails the ship and prints the two calls above.\n\n**If the gate refuses you, the artifact is wrong — not the gate.** Do not edit the checker, do not add\nan exemption for your own paths, do not set a bypass because you are in a hurry. That is how a working\ninvariant becomes a decorative one.\n\n## Red flags — stop and lease\n\n- \"I'll just patch this one line.\"\n- \"Nobody else is in this file right now.\"\n- \"I'll lease it after I see if the change works.\"\n- Reaching for Edit or Write on a code path with no `lease_id` in your context.\n- A 409 you are about to retry unchanged.\n\n## Verify\n\nBefore the first edit: read ✓ → hash ✓ → `start` returned a `lease_id` ✓.\nBefore every commit: hash ✓ → `commit` returned 200 ✓ → `git commit`.\n\n## Related\n\n- [Shared Write Law](../shared-write-law/SKILL.md) — the file claim. Complementary: the claim says who,\n  this says from what version. Both, not either.\n- Live law: https://miscsubjects.com/a/coding-law\n- The chain: https://miscsubjects.com/api/coding-law/leases\n",
  "files": [
    {
      "path": "SKILL.md",
      "bytes": 3744
    }
  ],
  "has_license_file": false,
  "prevents": [
    {
      "date": "2026-08-05",
      "failure": "Two agents read the same file at the same version, both edited from it, and the second commit erased the first agent's work. Each commit was individually valid, so nothing in git showed the loss. The file-claim system recorded who was working where but never what text they were working from."
    }
  ],
  "canonical_source": ".claude/skills/coding-law/SKILL.md",
  "sibling": ".agents/skills/coding-law/SKILL.md"
}