Skip to content

Commit 8edec16

Browse files
thonatosthonatos
committed
docs: strengthen OpenSpec change governance
1 parent 686cc6b commit 8edec16

10 files changed

Lines changed: 530 additions & 10 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,24 +6,25 @@ This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.
66

77
## Workflow
88

9-
Use OpenSpec for scoped behavior, product, API, migration, release, or architecture changes. Small documentation corrections and mechanical fixes can be submitted directly when they do not change shipped behavior.
9+
Use OpenSpec for scoped behavior, product, API, migration, release, architecture, database, security, permissions, deployment, or data repair changes. Small documentation corrections and mechanical fixes can be submitted directly when they do not change shipped behavior.
1010

1111
```mermaid
1212
flowchart LR
13-
Idea[idea or bug] --> Scope{behavior or product change?}
13+
Idea[idea or bug] --> Scope{scoped behavior or high-risk change?}
1414
Scope -- yes --> OpenSpec[OpenSpec change]
1515
Scope -- no --> Patch[small patch]
16-
OpenSpec --> Patch
16+
OpenSpec --> Audit[scope + docs/wiki + audit]
17+
Audit --> Patch
1718
Patch --> Verify[pnpm verify]
1819
Verify --> PR[PR notes]
1920
```
2021

2122
| Step | Contributor task |
2223
| ---- | ---------------- |
23-
| Scope | Decide whether OpenSpec is required. |
24+
| Scope | Decide whether OpenSpec is required and identify affected systems, docs, wiki, and high-risk categories. |
2425
| Patch | Keep changes focused and update docs/tests with behavior. |
2526
| Verify | Run the full gate when feasible. |
26-
| PR | Include validation notes and risk areas. |
27+
| PR | Include validation notes, documentation impact, and risk areas. |
2728

2829
## Local Validation
2930

@@ -48,7 +49,8 @@ Include:
4849

4950
- OpenSpec change ID, or a note that no OpenSpec change is needed.
5051
- Commands run, especially `pnpm verify` or the subset that was possible.
51-
- Database or migration impact.
52+
- Documentation impact for `docs/` and `wiki/`, or why long-lived documentation was not affected.
53+
- Database or migration impact, including a link or summary of the OpenSpec `Database Change Audit` for database-related changes.
5254
- Deployment impact for release changes.
5355
- Secret handling confirmation for config, CI, deployment, auth, mail, storage, and database changes.
5456

‎docs/conventions.md‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ This repository keeps public project documentation concise, task-oriented, and s
1010
| `docs/` | Stable task documentation | Architecture, development, database, migration, API reference, moderation, and security tasks. Keep current behavior first. |
1111
| `wiki/` | Knowledge base | Historical context, legacy behavior, migration background, community rules, and business logic notes. Must follow [wiki/writing-guidelines.md](../wiki/writing-guidelines.md). |
1212
| `deployment/` | Production deployment domain | Production runbook, compose file, grouped dotenv template, audit template, and real operator assets. |
13-
| `openspec/` | Proposed and accepted behavior changes | Use for scoped product, API, migration, release, or architecture changes. |
13+
| `openspec/` | Proposed and accepted behavior changes | Use for scoped product, API, migration, release, architecture, database, security, permissions, deployment, or data repair changes. |
1414

1515
`docs/`, `wiki/`, and `deployment/` are sibling domains. `docs/` answers "how do I develop, understand, or use this now?". `wiki/` records "why is this true, where did it come from, and what still needs review?". `deployment/` contains the production runbook and files operators can copy, validate, or execute.
1616

@@ -53,6 +53,7 @@ This repository keeps public project documentation concise, task-oriented, and s
5353
| Description | State what changed and why. Note migration, deployment, and secret-handling impact. |
5454
| Tests | Add or update tests for behavior changes. Pure refactors still pass `pnpm test`. |
5555
| Docs | Update `docs/` and `apps/api/src/routes/*.ts` zod-openapi declarations when API behavior changes. Run `pnpm gen:openapi` to regenerate `api/openapi.json`. |
56+
| Database audit | For PostgreSQL schema, migration, seed/bootstrap, index, constraint, backfill, cleanup, repair, retention, or field semantic changes, link to the OpenSpec `Database Change Audit`. |
5657
| Verification | Run `pnpm verify` when feasible. If not, list the subset that was run and why. |
5758
| Reviews | At least one maintainer approval for `main`. Request review from domain owners for affected packages. |
5859
| Squash merge | Default. The squashed commit message should follow Conventional Commits. |
@@ -78,11 +79,22 @@ This repository keeps public project documentation concise, task-oriented, and s
7879

7980
## OpenSpec And Design Process
8081

81-
- Use OpenSpec for scoped behavior, product, API, migration, release, or architecture changes. See [CONTRIBUTING.md](../CONTRIBUTING.md).
82+
- Use OpenSpec for scoped behavior, product, API, migration, release, architecture, database, security, permissions, deployment, or data repair changes. See [CONTRIBUTING.md](../CONTRIBUTING.md) and [docs/openspec-governance.md](openspec-governance.md).
8283
- Small documentation corrections and mechanical fixes can be submitted directly when they do not change shipped behavior.
83-
- Proposals should state Why, What Changes, Non-goals, Capabilities, and Impact.
84+
- Proposals should state Why, What Changes, Scope, Non-goals, Capabilities, Impact, and Documentation Impact.
8485
- Specs are capability-oriented and declarative. Implementation details belong in `design.md` or tasks, not the spec.
85-
- Archive a change only after tasks are complete and `openspec validate --all --strict` passes.
86+
- Designs should include Mermaid diagrams or concise matrices for affected architecture, data, state, permission, and migration flows.
87+
- Database-related designs must include a `Database Change Audit` covering impact, compatibility, migration, rollback, performance, data integrity, and documentation updates.
88+
- Archive a change only after tasks are complete, documentation impact is handled, database audit evidence exists where applicable, and `openspec validate --all --strict` passes.
89+
90+
## Documentation Sync Rules
91+
92+
| Change area | Documentation expectation |
93+
| ----------- | ------------------------- |
94+
| Current development, runtime, architecture, API, database, migration, moderation, or security behavior | Update the relevant `docs/` page or explain why stable docs are not affected. |
95+
| Business rules, legacy behavior, migration background, community rules, or sourced historical context | Update the relevant `wiki/` page and follow [wiki/writing-guidelines.md](../wiki/writing-guidelines.md). |
96+
| API contract behavior | Update route zod-openapi declarations and regenerate `api/openapi.json` with `pnpm gen:openapi`. |
97+
| PostgreSQL schema, migration, index, constraint, backfill, cleanup, repair, retention, or field semantics | Include OpenSpec `Database Change Audit`; update `docs/database.md`, `docs/migration-runbook.md`, or `wiki/migration-background.md` when durable knowledge changes. |
8698

8799
## API Documentation Rules
88100

‎docs/openspec-governance.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# OpenSpec Governance
2+
3+
This document defines how maintainers and AI agents create changes that can be implemented, audited, documented, and archived without losing project knowledge.
4+
5+
## Change Scope
6+
7+
Every OpenSpec change for behavior, product, API, migration, release, architecture, database, security, permissions, deployment, or data repair work must describe its scope before implementation starts.
8+
9+
Use this shape in `proposal.md` when a change has meaningful boundaries:
10+
11+
```markdown
12+
## Scope
13+
14+
### In Scope
15+
16+
- Current behavior, system, route, package, migration, or business rule being changed.
17+
18+
### Out Of Scope
19+
20+
- Related work intentionally not included in this change.
21+
22+
### Affected Areas
23+
24+
- Code: `apps/web`, `apps/api`, `packages/db`, `packages/shared`, or other paths.
25+
- Runtime: PostgreSQL, Redis, object storage, email, deployment, or workers.
26+
- Contracts: OpenAPI, shared Zod schemas, API errors, public URLs, or CLI commands.
27+
28+
### High-Risk Categories
29+
30+
- Database:
31+
- Security/permissions:
32+
- API contract:
33+
- Migration/data repair:
34+
- Deployment/release:
35+
```
36+
37+
Small documentation corrections, spelling fixes, and mechanical formatting can skip OpenSpec when they do not change shipped behavior or durable project knowledge.
38+
39+
## Documentation Impact
40+
41+
Every proposal must state how `docs/` and `wiki/` are affected. The answer can be `Updated`, `Not Required`, or `Deferred`, but it must be explicit.
42+
43+
```markdown
44+
## Documentation Impact
45+
46+
### docs/
47+
48+
- Updated: `docs/<page>.md` because <current behavior or task changes>.
49+
- Not Required: <why stable task documentation is unchanged>.
50+
- Deferred: <follow-up change or task that will update docs>.
51+
52+
### wiki/
53+
54+
- Updated: `wiki/<page>.md` because <business rule, legacy behavior, migration background, or sourced context changes>.
55+
- Not Required: <why knowledge base content is unchanged>.
56+
- Deferred: <follow-up change or task that will update wiki>.
57+
```
58+
59+
`docs/` describes current development, runtime, architecture, database, API, moderation, security, migration, and deployment tasks. `wiki/` preserves sourced business knowledge, legacy behavior, migration background, community rules, and facts that need review. Do not write implementation logs into either domain.
60+
61+
| Change kind | Usually update |
62+
| --- | --- |
63+
| Runtime architecture, request flow, worker boundary | `docs/architecture.md` |
64+
| Local development or verification commands | `docs/development.md`, `docs/conventions.md` |
65+
| PostgreSQL schema, migration, index, data repair | `docs/database.md`, `docs/migration-runbook.md` |
66+
| Security, auth, roles, audit, secret handling | `docs/security.md` |
67+
| Content moderation operation | `docs/content-moderation.md`, `wiki/community-rules.md` |
68+
| Business rule or legacy behavior | `wiki/business-rules.md`, `wiki/legacy-behavior.md` |
69+
| Mongo to PostgreSQL mapping or migration background | `wiki/migration-background.md` |
70+
71+
Wiki updates must follow `wiki/writing-guidelines.md`: cite sources, separate facts from inferences, and mark uncertain statements as `To Confirm`.
72+
73+
## Diagrams
74+
75+
Use diagrams when prose alone would hide boundaries, ordering, or risk.
76+
77+
| Impact | Preferred form |
78+
| --- | --- |
79+
| Architecture or module boundary | Mermaid `flowchart` or `graph` |
80+
| Request, auth, or integration flow | Mermaid `sequenceDiagram` |
81+
| Data model or relationship | Mermaid `erDiagram` or a field table |
82+
| Lifecycle or state transition | Mermaid `stateDiagram-v2` |
83+
| Permission boundary | Matrix table or Mermaid `flowchart` |
84+
| Migration, backfill, or release ordering | Mermaid `flowchart LR` |
85+
86+
If no diagram is needed, explain why the change is single-boundary or clear enough in prose.
87+
88+
## Database Change Audit
89+
90+
Database-related changes require a `Database Change Audit` in `design.md`. This applies to PostgreSQL schema changes, Drizzle migrations, seed/bootstrap behavior, indexes, constraints, backfills, cleanups, repair scripts, data retention, and field semantic changes.
91+
92+
```markdown
93+
## Database Change Audit
94+
95+
### Change Type
96+
97+
- Schema:
98+
- Migration:
99+
- Seed/bootstrap:
100+
- Index/constraint:
101+
- Data backfill:
102+
- Data cleanup/repair:
103+
- Data semantics:
104+
105+
### Impacted Data
106+
107+
- Tables:
108+
- Columns:
109+
- Existing rows affected:
110+
- User-visible behavior affected:
111+
- Related docs/wiki:
112+
113+
### Compatibility
114+
115+
- Old code with new schema:
116+
- New code with old data:
117+
- API/shared schema compatibility:
118+
- Required deploy order:
119+
120+
### Migration Plan
121+
122+
- Online-safe:
123+
- Estimated data volume:
124+
- Locking/full-scan risk:
125+
- PostgreSQL-specific notes, such as `CONCURRENTLY` or constraint validation:
126+
127+
### Rollback Plan
128+
129+
- Reversible:
130+
- Data loss risk:
131+
- Rollback procedure or rationale if not reversible:
132+
133+
### Verification
134+
135+
- Migration test:
136+
- Data integrity check:
137+
- Performance check:
138+
- Docs/wiki updated:
139+
```
140+
141+
PostgreSQL is the only runtime database. Do not add SQLite, dialect fallback, local database compatibility paths, or tests that make SQLite a release path.
142+
143+
## Task And Archive Checks
144+
145+
`tasks.md` must include follow-through for the impact declared in the proposal and design.
146+
147+
- Add docs/wiki synchronization tasks when `Documentation Impact` lists updates.
148+
- Add diagram consistency checks when design includes architecture, state, permission, data, or migration diagrams.
149+
- Add migration execution, rollback rationale, data integrity, and documentation checks when `Database Change Audit` is present.
150+
- Run `openspec validate <change> --strict` before asking to archive.
151+
- Archive only after tasks are complete, validation passes, documentation impact has been handled, and database audit evidence exists where applicable.

‎openspec/changes/archive/2026-07-30-strengthen-openspec-change-governance/.openspec.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
schema: spec-driven
2+
created: 2026-07-29

0 commit comments

Comments
 (0)