Governance

How the product is governed

Kairoku is built against seven rules that a proposed change is checked against. They come from the build rules every agent working on Kairoku receives (CLAUDE.md, mirrored in AGENTS.md so an agent gets the same text whichever rules file its tooling reads). Rule 2 is stated here against the API, where the MCP server now lives and where its pin test runs.

1. The app owns plan structure. Agents never create Jira issues for plan structure — they write the plan with upsert_plan and a human pushes it from the Sync tab. An issue minted outside the app gets no sync_mappings row, so the plan can never see it again. When the project's auto-sync toggle for a system is on, agents may auto-update remote issues or pages that already have a sync_mappings row, bounded to the rows their call touched and logged as the agent. Creating remote structure — any new issue or page — remains a human push from the Sync tab.
2. The MCP surface is pinned at fifteen tools by the "GET discovery returns exactly the fifteen pinned tools and no shell" test in kairoku-api's test/integration/mcp.test.ts — anchored on the test's name, never a line number, because a name survives edits that a line number does not. A capability needing a sixteenth is an explicit amendment item in the plan, never a quiet edit to the pin. Nearly everything fits as an optional argument on a tool that already exists.
3. Every plan item carries a six-section body and test notes, both written at plan time, with the test notes in their own field. An item whose acceptance criteria reads "defined by the spec" is a roadmap row wearing a story's clothes.
4. Requirement ids are append-only. Never renumbered, never reused. An id frozen into a pushed Jira story cannot be re-pointed afterwards.
5. Human-only gates. Manual test and Flow test verification, the PR merge, the Done transition, anything in the Clerk dashboard, any browser sign-in walk, any file deletion. A non-human identity never approves, verifies or releases its own work. That is the invariant and it does not bend. What an agent may do is carry out a closure a human has explicitly directed — and then the comment must say plainly that it is administrative and that no verification was performed. Directed bookkeeping is not approval. An agent that closes a gate on its own judgement, or leaves a comment a reader could mistake for evidence the check was run, has broken this rule rather than bent it.
6. No dates, no estimates, no story points. Relative complexity with a stated reason is allowed; a number that implies a calendar is not. The ban is on numbers the system generates or infers: a target date a human typed for their own release is an input, not an estimate, and it stays exempt only while no agent-facing tool input can write it.
7. Never report a test run green without its count, and treat a total lower than the previous run as a failure. A run that silently skipped a third of its assertions is green and looks identical to one that passed. And a story merges only with tsc --noEmit clean — bun test never type-checks, so a green suite is not evidence the code compiles.