Add decision records (ADRs) with template and 0001 on package versioning

[kentcdodds]

What

Adds a lightweight architecture decision record (ADR) system under docs/contributing/decisions/ so platform-shaping choices — especially decisions not to build something — are recorded instead of re-litigated.

• docs/contributing/decisions/index.md — what ADRs are, how to add one, and the record list
• docs/contributing/decisions/0000-template.md — half-page template (Status / Date / Context / Decision / Consequences)
• docs/contributing/decisions/0001-no-package-versioning.md — first real record: no user-facing package versioning and no cross-package import pins, with the rationale (git history on Artifacts already covers history/rollback; the package author is the consumer; community forks already pin by commit; pinned old versions would escape fleet codemods) and the preferred future shape if import-pin demand ever materializes
• Links the folder from docs/contributing/index.md and AGENTS.md (agents should check it before proposing something already decided against)
• Exempts docs/contributing/decisions/ from npm run docs:check-temporal via a new exemptRelativePrefixes list in tools/check-docs-temporal-language.ts (decision records are point-in-time documents by design), with test coverage, and notes the exception in docs/contributing/documentation.md

Why

Came out of a discussion on whether to add versioning to users' packages (answer: no). Decisions like that had no durable home, so the same question would inevitably resurface.

Verification

• npm run format:check, npm run lint, npm run typecheck — pass
• npm run docs:check-temporal — passes with the new folder exempted
• npx vitest run tools/check-docs-temporal-language.node.test.ts — 16 tests pass, including the new prefix-exemption case and a fixed assertion that the decisions prefix is configured
• npm run primitives:check and npm run migrations:check — pass

System recap — composes existing primitives (low risk)

Mode: recap · Base: main @ 3320dad0 · Head: 05a0fe2b

Classification: composes — no primitives added or changed. The classifier matches zero primitives for this diff: it touches contributor documentation and the docs temporal-language validation tool only. No runtime, storage, or capability code changes.

Primitives touched

Primitive	Group	Impact
(none)	—	Docs under docs/contributing/decisions/ plus an exemption list in tools/check-docs-temporal-language.ts (validation tooling, not a mapped primitive)

Before / after

Before: docs/check-temporal exemptions = 2 exact file paths
After:  + exemptRelativePrefixes = ['docs/contributing/decisions/']
        (decision records are point-in-time documents by design)

  

Summary by CodeRabbit

• Documentation

  • Added an architecture decision records section with an index, contribution guidance, and reusable decision template.
  • Documented the decision against product-level package versioning and cross-package import pins.
  • Updated contributor documentation navigation and reformatted existing guidance without changing its meaning.

• Tests

  • Expanded documentation checks to support exempt paths and directory prefixes.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds architecture decision records and contributor-navigation links. It exempts decision-record directories from temporal-language checks and expands tests for prefix-based exemptions.

Changes

Decision records and documentation checks

Layer / File(s)	Summary
Temporal checker exemptions tools/check-docs-temporal-language.ts, tools/check-docs-temporal-language.node.test.ts	The checker now skips configured directory prefixes. Tests cover explicit paths and generated paths under exempt prefixes.
Decision record documentation docs/contributing/decisions/*, AGENTS.md, docs/contributing/index.md, docs/contributing/documentation.md	Adds the decision-record template, index, and package-versioning decision. Contributor documentation links to the index. One guidance paragraph is rewrapped without content changes.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: adding ADRs with a template and the package-versioning decision record.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/decision-records-ccb6

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔎 Preview deployed: https://kody-pr-1108.kody-a99.workers.dev

Worker: kody-pr-1108
D1: kody-pr-1108-db
KV: kody-pr-1108-oauth-kv

Mocks:

• cloudflare: https://kody-pr-1108-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-1108-mock-cloudflare)

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@AGENTS.md`:
- Around line 45-47: Indent the project-intent and decisions documentation links
beneath their respective labels in AGENTS.md, matching the nested continuation
style already used in the surrounding list entries.

In `@tools/check-docs-temporal-language.node.test.ts`:
- Around line 142-145: Update the test loop around exemptRelativePrefixes to
explicitly assert that the configured prefixes include the documented
docs/contributing/decisions/ prefix, using a fixed expected value rather than
relying only on derived sample paths.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 875a97c6-c881-44d7-a21d-5f7f6cfd143e

📥 Commits

Reviewing files that changed from the base of the PR and between 3320dad and 0b69f39.

📒 Files selected for processing (8)

• AGENTS.md
• docs/contributing/decisions/0000-template.md
• docs/contributing/decisions/0001-no-package-versioning.md
• docs/contributing/decisions/index.md
• docs/contributing/documentation.md
• docs/contributing/index.md
• tools/check-docs-temporal-language.node.test.ts
• tools/check-docs-temporal-language.ts