Specification governance¶
Purpose¶
This policy assigns one authoritative home to each kind of product and delivery knowledge. It lets a contributor preserve a user's intent while changing an implementation, and lets a reader find the current system contract without reconstructing it from closed Issues, code, or tests.
It complements documentation governance: that policy owns documentation publication and maintenance; this page is the authoritative allocation and promotion policy for requirements, changes, current specifications, decisions, and evidence.
From request to evidence¶
Treat a user's stated solution as input, not automatically as the desired outcome. For material or ambiguous work, record the smallest useful interpretation in the authoritative Work Item: stakeholder, observed problem and evidence, desired outcome and success evidence, constraints, assumptions, unknowns, and non-goals. Routine, clear, low-risk work does not need separate artifacts for each field.
`Goal` is the outcome to improve. `Bet` is the change believed to achieve that Goal. A failed Bet can require a new Bet without invalidating the Goal. The Work Item makes the selected Bet actionable: it is the authoritative contract for what is being changed now.
```text User request → interpretation → Goal → Bet → Work Item ↓ Current Specification ← accepted change ← implementation ← verification evidence ```
Authoritative responsibilities¶
| Surface | Authoritative question it answers | Keep there |
|---|---|---|
| User request and interpretation | What outcome or constraint did the stakeholder express? | Original request; the proportional interpretation recorded in the Work Item. |
| GitHub Issue / Work Item | What are we changing now? | Goal/outcome, selected Bet or proposed change, scope, acceptance criteria, assumptions, risks, constraints, replanning, and verification plan. |
| Specification | How must the current system behave? | Present-tense observable behavior, durable invariants, external contracts, lifecycle/state rules, material constraints, and explicit non-goals. |
| `SKILL.md` and its references | How must an agent or team perform work? | Execution policy, authority limits, planning and validation workflow, and documentation-handling process—not repository-specific product behavior. |
| Decision Issue / ADR | Why was a durable design choice made? | Context, options, decision, rationale, trade-offs, and revisit conditions. It links to the current specification rather than redefining it. |
| Pull request | How was this change delivered? | Implementation summary, Issue and specification links, migration/rollout notes, and verification evidence. |
| Tests / CI | Is a behavior or invariant demonstrably satisfied? | Executable success and failure evidence. They do not become the only readable definition of a rule. |
| Code / configuration / schemas | What implementation and mechanically reconstructable facts exist? | The implementation, machine-readable contracts, and generated facts. |
Architecture pages under `docs/en|ja/development/architecture/` are this repository's initial living Specification collection. A new focused specification belongs beside the owning architecture or policy page when an existing page would become unclear; do not create a monolithic requirements document. English is normative and every reader-facing Japanese specification is its maintained paired translation.
Writing a living Specification¶
Write only the stable, currently effective contract in the present tense. Use the smallest useful sections:
```markdown
¶
Purpose¶
Invariants¶
Observable behavior¶
Constraints¶
Non-goals¶
Related interfaces¶
```
An invariant is a property future changes must preserve, such as an authorization boundary, destructive-operation safety rule, data-integrity condition, lifecycle transition, fail-closed outcome, release safety rule, or externally observable compatibility contract. State the property, not its private function or incidental implementation. If it is mechanically enforceable, identify or add representative success and failure evidence as required by documentation governance.
Keep rationale, debate, migration history, PR progress, debugging notes, checklist history, code placement, and private structure out of the Specification. Those belong to the Decision Issue, Work Item, PR, code, or tests as applicable.
Promotion and completion rule¶
When creating or materially changing a Work Item, ask: does this change the current, durable system contract? Update the owning Specification when it changes user-observable behavior, an external interface, security or safety invariant, state transition, compatibility rule, or an operational rule that future work must inherit.
Do not update a Specification for behavior-preserving refactoring, wording or typo correction, private implementation detail, temporary migration work, test-only organization, or a performance improvement that does not change the contract. If the answer is uncertain, record the interpretation in the Work Item and prefer a small specification clarification before completion.
For a specification-affecting Issue, completion requires this traceability:
```text Issue acceptance criteria → current Specification → implementation → verification evidence ```
If outcome, scope, acceptance criteria, or material interpretation changes during delivery, update the active Work Item first. Promote the resulting durable rule to the Specification in the same accepted change. A closed Issue remains history, never a replacement for the current Specification.
Duplication and current inventory¶
One rule has one authoritative definition. Other surfaces may link to it, summarize it as explicitly non-authoritative navigation, or implement/test it; they must not silently create a competing normative copy. Move, merge, link, generate, or delete duplicate text using the maintenance dispositions in documentation governance.
This initial inventory keeps existing durable knowledge in its proven owners; it does not rewrite historical Issues.
| Existing source | Durable content | Disposition |
|---|---|---|
| `docs/en | ja/development/architecture/*.md` | Current accepted components, sequences, boundaries, and system invariants |
| `docs/en | ja/development/policies/documentation.md` | Documentation ownership, language, publication, and maintenance |
| `docs/en | ja/development/policies/governance-layers.md` | Portable versus project-local ownership |
| `plugins/ai-teams/skills/*/SKILL.md` and `references/` | Machine-facing execution contracts | KEEP/LINK; retain process rules, promote repository-specific current behavior only when it needs a human-facing specification. |
| GitHub Issues and Decision Issues | Active work, rationale, agreements, and history | KEEP/LINK; do not migrate closed-history narratives into a current specification. |
| Tests, CI, workflows, configuration, schemas, and evaluations | Executable enforcement and machine-readable facts | KEEP/LINK or GENERATE; refer to the owning specification rather than copying prose into each artifact. |
The architecture overview's responsibility model is a non-authoritative navigation summary and links here. When a future audit identifies a real competing rule, record its evidence and durable correction in a GitHub Issue before declaring that audit complete.