end
46c4416ed4
Record the accepted rule for root-module versions and nested modules for heavy dependencies or independent releases. Update repository instructions and link implementation evidence to the ADR. Closes #2
Baseline copied from corestack/standards at a36288e7cec933a32f4819a1308201027c9f57ec; this project owns and may adapt it.
Documentation policy
The corestack/go docs-format specification owns record format, templates, and validation. In scaffolded projects, generate records and run checks with the pinned documentation command in the root AGENTS.md; do not maintain local format templates.
The copied policy is a project-owned baseline that the project may adapt; scaffold re-runs never refresh it unless the owner explicitly asks. The project owns its locked checker pin and upgrades: update the tag and ensure compliance; scaffold re-runs retain the existing pin unless the owner asks.
Choose the smallest useful tier
| Tier | Use when | Scaffold output |
|---|---|---|
| Neither | A single-purpose CLI, library, or script has no consequential architectural choice or durable execution context yet. | No record directories and no docs-check CI step; root instructions tell agents to ask the owner to run scaffold-project to enable records when a consequential choice arises. |
| ADRs only | Consequential choices need durable rationale, but execution fits a short issue or PR. | Local policy in docs/adr/README.md, ADRs as warranted and docs-check CI. |
| ADRs + plans | Work spans areas, phases, or sessions and needs durable execution context. | Local policy in docs/adr/README.md, a docs/plans/README.md pointer, ADRs as warranted, one file per plan, and docs-check CI. |
Project size is a signal, not an exemption: a small security-sensitive library can warrant an ADR. Add the CI docs-check step exactly when the selected tier enables records. Change tiers when actual work warrants it; do not create empty record directories in anticipation.
Decisions and execution
Write an ADR for a consequential choice among real alternatives: difficult to reverse, crossing areas, changing a boundary, data model or security posture, or establishing a convention. Routine details and choices already governed by an accepted ADR or practice guide do not need another record. Read relevant accepted decisions and verify their claims against code before dependent work. Proposed ADRs are context, not authority; only the owner accepts a decision.
Write a plan when work spanning areas, phases or sessions needs durable execution context. Otherwise keep planning in a PR, issue or chat. Each plan has its own file; the directory is the index. Never create a central living plan or living PRD checklist that parallel worktrees continually edit. Closed plans are history, never standing instructions.
Use write-adr and review-adr when available: they guide reasoning while deferring textual format to repository conventions. Seek independent review and owner acceptance before treating a proposal as binding. Neither a self-check nor an independent recommendation accepts an ADR. ADRs may share a PR with implementation; no separate ADR PR or extra sections are required by this policy.
Reconcile before final review and merge
Compare the latest target branch plus the PR with the affected decisions and plans, not just the working branch's previous metadata. Update ADR implementation state and implemented_by with the real PR URL when delivery evidence supports it. Close finished plans with completion evidence and an Outcome; keep work active when scope remains. Never invent PR links, completed checks, owner acceptance, or delivery evidence. Run docs check using the pinned documentation command in the root AGENTS.md after reconciliation.