Specification governance

English | 日本語

目的

この policy は product と delivery に関する知識の種類ごとに、authoritative な保存先を一つ定めます。実装を変更しても user の意図を保ち、closed Issue、code、test から再構築せずに current system contract を見つけられるようにします。

Documentation Governanceを補完します。同文書は documentation の publication と maintenance を所有し、この page は requirement、change、current specification、decision、evidence の配置と promotion の authoritative policy です。

Request から evidence まで

user が提示した solution は input であり、desired outcome と自動的に同一視しません。material または曖昧な work では、authoritative Work Item に必要十分な解釈を記録します。すなわち stakeholder、observed problem と evidence、desired outcome と success evidence、constraint、assumption、unknown、non-goal です。routine で明確、低リスクな work では、各 field を別 artifact にする必要はありません。

`Goal` は改善したい outcome、`Bet` はその Goal を達成すると考える change です。Bet が失敗しても Goal が無効になるとは限りません。Work Item は選択した Bet を実行可能にし、「現在何を変えるか」の authoritative contract になります。

```text User request → interpretation → Goal → Bet → Work Item ↓ Current Specification ← accepted change ← implementation ← verification evidence ```

Authoritative responsibility

Surface 答える authoritative な問い 保存する内容
User request と interpretation stakeholder はどの outcome / constraint を表明したか Original request と、Work Item に記録する proportional な interpretation。
GitHub Issue / Work Item 現在何を変えるか Goal/outcome、selected Bet / proposed change、scope、acceptance criteria、assumption、risk、constraint、replanning、verification plan。
Specification current system はどのように振る舞うべきか 現在形の observable behavior、durable invariant、external contract、lifecycle/state rule、material constraint、explicit non-goal。
`SKILL.md` と references agent / team はどのように work を進めるか execution policy、authority limit、planning/validation workflow、documentation-handling process。repository 固有の product behavior は置かない。
Decision Issue / ADR なぜ durable な design choice をしたか Context、option、decision、rationale、trade-off、revisit condition。current specification へ link し、再定義しない。
Pull request この change をどのように delivery したか implementation summary、Issue / specification link、migration/rollout note、verification evidence。
Tests / CI behavior / invariant が証明可能に成立するか executable な success/failure evidence。読みやすい rule の唯一の定義にはしない。
Code / configuration / schema どの implementation と機械的に復元可能な fact が存在するか implementation、machine-readable contract、generated fact。

`docs/en|ja/development/architecture/` 配下の Architecture page は、この repository の initial living Specification collection です。既存 page が不明瞭になる場合だけ、owning architecture または policy page の近くに focused specification を追加します。巨大な requirements document は作りません。English は normative で、reader-facing Japanese specification は必ず maintained paired translation です。

Living Specification の書き方

stable で現在有効な contract のみを現在形で書きます。必要な section だけを使います。

```markdown

Purpose

Invariants

Observable behavior

Constraints

Non-goals

```

invariant は、将来の change でも維持する property です。たとえば authorization boundary、destructive operation の safety rule、data-integrity condition、lifecycle transition、fail-closed outcome、release safety rule、externally observable compatibility contract です。private function や incidental implementation ではなく property を記述します。機械的に検証可能なら、Documentation Governanceに従い、representative な success/failure evidence を追加または特定します。

rationale、discussion、migration history、PR progress、debugging note、checklist history、code placement、private structure は Specification に残しません。必要に応じて Decision Issue、Work Item、PR、code、test に置きます。

Promotion と completion rule

Work Item の作成・material な変更時に、次を問います。この change は current かつ durable な system contract を変えるか。 user-observable behavior、external interface、security/safety invariant、state transition、compatibility rule、future work が継承する operational rule を変えるなら、owning Specification を更新します。

behavior-preserving refactoring、typo / wording 修正、private implementation detail、temporary migration work、test-only organization、contract を変えない performance improvement では Specification を更新しません。不確かな場合は Work Item に interpretation を記録し、completion 前に小さな specification clarification を優先します。

specification-affecting Issue は、completion 時に次の traceability を満たします。

```text Issue acceptance criteria → current Specification → implementation → verification evidence ```

delivery 中に outcome、scope、acceptance criteria、material interpretation が変わった場合、先に active Work Item を更新します。resulting durable rule は同じ accepted change で Specification に promote します。closed Issue は history であり、current Specification の代替にはなりません。

Duplication と current inventory

一つの rule の authoritative definition は一つだけです。他の surface は link、明示的に non-authoritative な navigation summary、implementation/test を提供できますが、競合する normative copy を作ってはいけません。duplicate text は Documentation Governance の disposition により move、merge、link、generate、delete します。

この initial inventory は既存の durable knowledge を、実績のある owner に維持します。historical Issue を書き換えません。

Existing source Durable content Disposition
`docs/en ja/development/architecture/*.md` current accepted component、sequence、boundary、system invariant
`docs/en ja/development/policies/documentation.md` documentation ownership、language、publication、maintenance
`docs/en ja/development/policies/governance-layers.md` portable と project-local の ownership
`plugins/ai-teams/skills/*/SKILL.md` と `references/` machine-facing execution contract KEEP/LINK。process rule を維持し、人が読む repository-specific current behavior は必要時だけ Specification へ promote。
GitHub Issue と Decision Issue active work、rationale、agreement、history KEEP/LINK。closed-history narrative を current specification に移さない。
Tests、CI、workflow、configuration、schema、evaluation executable enforcement と machine-readable fact KEEP/LINK または GENERATE。各 artifact に prose を copy せず、owning specification を参照。

Architecture overview の responsibility model は non-authoritative な navigation summary であり、この page へ link します。将来の audit が実際に競合する rule を検出した場合は、audit を complete とする前に evidence と durable correction を GitHub Issue に記録します。