{
  "id": "page:library-production-contract",
  "_kind": "Page",
  "_file": "wiki/library/production-contract.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "title": "Production contract (Library)",
    "displayName": "Production contract (Library)",
    "slug": "library/production-contract",
    "articlePath": "wiki/library/production-contract.md",
    "article": "\n# Production contract\n\nA one-line JSDoc convention for babysitter process files: every\n`*.process.js` carries a `@productionContract` tag in its header naming the\n**user-visible assertion** the run must satisfy.\n\n## TL;DR\n\n```js\n/**\n * @process specializations/web-development/fix-checkout-button\n * @description Cart's \"Buy now\" button is grey after the recent CSS rework\n * @agent general-purpose\n * @productionContract A signed-in user with items in the cart sees a primary\n *   \"Buy now\" button on /cart that responds to click and routes to /checkout.\n */\n```\n\nThe tag answers a single question: *\"If I deployed this and the user\nchecked, what would they see that proves the run worked?\"*\n\nThe answer is intentionally not \"the test suite is green.\" A run can pass\nevery test gate and still leave the user-visible bug intact (the test\nmocked away the thing that was broken, the code path under test isn't the\ncode path the user exercises, the assertion was on an API success count\ninstead of rendered state). The contract makes that gap explicit and\ncode-reviewable.\n\n## Why the convention exists\n\nIt was extracted from a real-world incident on a Next.js + Supabase\nproject. A persistent \"Annotate all (N)\" badge stuck at 4 on the recipe\nbank. Three successive fix attempts each:\n\n1. Identified a plausible cause (sentinel rows / client cache / set-based\n   completeness check).\n2. Shipped the fix.\n3. Passed every unit, data, and Playwright test gate.\n4. **Never moved the user-visible 4.**\n\nEach scoped test was asserting on the wrong thing — the server-action\nreturn value, the in-memory mock's state, the count returned by the\nmocked Supabase client. None asserted on the rendered DOM after a\nreal reload against real data.\n\nThe fourth attempt led with a live-prod diagnostic (a sibling\ncontribution under [`specializations/qa-testing-automation/\ndiagnostic-first-phase`](../../specializations/qa-testing-automation/diagnostic-first-phase.js))\nand found the real cause on the first artifact: PostgREST's silent\n1000-row response cap was truncating an `.in()` query. The mock DB\ncouldn't reproduce the cap because it's a server-side framework default,\nnot a schema constraint.\n\nHad every previous process declared its production contract\n(`Reloading /recipes after Annotate all clears the (N) badge`), each\nattempt would have had to argue *how* its fix moved that specific\nassertion — not just that the test suite stayed green. The wrong\nattempts would have been visibly insufficient at review time, before\nship.\n\n## Where the tag goes\n\nIn the file's top-level JSDoc, alongside `@agent` / `@inputs` / `@outputs`:\n\n```js\n/**\n * @process specializations/<area>/<name>\n * @description <one paragraph>\n * @inputs { ... }\n * @outputs { ... }\n * @agent general-purpose\n * @productionContract <one sentence in user-visible terms>\n */\n```\n\n## Worked examples\n\nA grab bag of contracts from real-world domains, to show the shape:\n\n### UX bug\n\n```\n@productionContract Header logo is visibly clickable, /recipes/new is\n  reachable from any nav, and Favorites/Most-cooked filter pills sort\n  across the full recipe set (not just the first page).\n```\n\nWrong shape for the same run: *\"src/components/Header.tsx renders a\n`<Link>` with the expected aria-label.\"* The tag isn't about which\ncomponent file changed; it's about what the user sees.\n\n### Brand rebrand\n\n```\n@productionContract The header renders the new mark + wordmark in the\n  approved font; favicon and the 4 PWA icon variants match the new brand\n  on both light and dark themes.\n```\n\n### Backend bug fix\n\n```\n@productionContract After clicking \"Annotate all\", reloading /recipes\n  shows the (N) badge cleared — verified by an e2e Playwright test that\n  seeds a real-DB recipe with the failure pattern, performs the click,\n  reloads, and asserts the badge count is 0.\n```\n\nNote the contract names a concrete, reproducible verification path. The\nprocess can still ship if the unit tests pass — but only if the e2e\nassertion holds.\n\n### Schema migration\n\n```\n@productionContract Existing recipes survive the migration with no data\n  loss; new INSERTs use the renamed column; the rollback runbook executes\n  cleanly against a freshly migrated copy.\n```\n\n### UI-only feature toggle\n\n```\n@productionContract A signed-in user in the \"experiment-A\" cohort sees\n  the new pricing card; users in \"experiment-B\" see the old card; both\n  cohorts can still complete checkout.\n```\n\n## Rules\n\n1. **User-visible language only.** \"The bulk-backfill server action\n   returns `success: true`\" is wrong. \"The (N) badge clears after\n   reload\" is right.\n2. **One sentence.** If you need a paragraph, the run is doing too much.\n   Split into multiple processes.\n3. **Verifiable from outside the codebase.** A reviewer who has never\n   read the source should be able to read the contract and know how to\n   tell whether the run succeeded.\n4. **Pair with — don't replace — your test gates.** The test gates keep\n   the codebase healthy; the contract keeps the run honest. Both are\n   required.\n5. **A run that passes every test gate but doesn't move the contract is a\n   failed run.** Treat it as such — don't ship it.\n\n## Adoption\n\n- Add the tag to new process files as they're written.\n- For existing files, a one-liner back-fill is easy:\n\n  ```bash\n  grep -L \"@productionContract\" library/specializations/*/*.js\n  ```\n\n  is all you need to find what's missing.\n\n- Consider a CI check that fails the build when a process file's JSDoc\n  is missing the tag. (Out of scope for this methodology contribution;\n  open as a follow-up if you want it as a first-class SDK feature.)\n\n## Adjacent methodology\n\nThis convention works best when paired with the **diagnostic-first\nphase** snippet under\n[`library/specializations/qa-testing-automation/diagnostic-first-phase.js`](../../specializations/qa-testing-automation/diagnostic-first-phase.js).\nTogether they discipline the loop:\n\n- Diagnostic-first phase = \"What does the production data actually say?\"\n- Production contract = \"What does the user see when we're done?\"\n\nIf you can't answer both, the run isn't ready to write code.\n",
    "documents": [
      "specialization:production-contract"
    ]
  },
  "outgoingEdges": [
    {
      "from": "page:library-production-contract",
      "to": "specialization:production-contract",
      "kind": "documents"
    }
  ],
  "incomingEdges": [
    {
      "from": "specialization:production-contract",
      "to": "page:library-production-contract",
      "kind": "documented_by",
      "attributes": {}
    },
    {
      "from": "page:index",
      "to": "page:library-production-contract",
      "kind": "contains_page"
    }
  ]
}