0be354a920
Single-commit clean baseline after security scrub of niche-tells, project codenames, internal jargon, and contributor-email leaks. Contents: - 100 Rust crates (_primitives/_rust/) - 37 agent manifests (_manifests/) + generated specs (_generated/) - 67 user-invocable skills (skills/) - 33 hooks (hooks/) - Composition blocks (_blocks/) - Documentation (docs/, README.md) - TS adapter packages (_ts_packages/) - Assembler (_assembler/) - Roles (_roles/) - Templates (_templates/) - Forgejo CI (.forgejo/) Author: Denis Parfionovich <info@greendragon.info> License: see LICENSE.
59 lines
2.1 KiB
Markdown
59 lines
2.1 KiB
Markdown
# DOCS — `DECISIONS.md` / ADR template (MADR 4.0)
|
|
|
|
Architecture Decision Records capture *why* a non-trivial choice was made, so future maintainers (including agents) don't re-litigate. Format: **MADR 4.0** (Markdown Any Decision Records, 2024). Nygard originated the practice in 2011.
|
|
|
|
**One ADR per non-trivial decision.** File path convention:
|
|
- Single-file log: append to `DECISIONS.md` (top-of-file = newest).
|
|
- Per-decision files: `docs/adr/NNNN-kebab-case-title.md` (NNNN = zero-padded int).
|
|
|
|
**MADR 4.0 template (copy as-is):**
|
|
|
|
```markdown
|
|
# ADR-NNNN: <short imperative title>
|
|
|
|
- **Status:** Proposed | Accepted | Rejected | Superseded-by-ADR-NNNN | Deprecated
|
|
- **Date:** YYYY-MM-DD
|
|
- **Deciders:** @handle, @handle
|
|
- **Evidence grade:** E1-E6 (see `_blocks/evidence-grading.md`)
|
|
|
|
## Context and Problem Statement
|
|
<1-3 sentences: what forces us to decide? What breaks if we don't?>
|
|
|
|
## Decision Drivers
|
|
- Driver 1 (e.g. cost < $X/mo)
|
|
- Driver 2 (e.g. must run offline)
|
|
- Driver 3 (e.g. team knows language Y)
|
|
|
|
## Considered Options
|
|
1. **Option A** — one-line summary
|
|
2. **Option B** — one-line summary
|
|
3. **Option C** — one-line summary
|
|
|
|
## Decision Outcome
|
|
Chosen: **Option <letter>**, because <1-2 sentences tying back to drivers>.
|
|
|
|
### Consequences
|
|
- Positive: <what improves>
|
|
- Negative: <what we give up, tech debt incurred>
|
|
- Neutral: <noteworthy but not directional>
|
|
|
|
## Pros and Cons of the Options
|
|
### Option A
|
|
- Pro: ...
|
|
- Con: ...
|
|
### Option B
|
|
- Pro: ...
|
|
- Con: ...
|
|
|
|
## Links
|
|
- Supersedes: ADR-NNNN
|
|
- Related: `HOTPATHS.md#section`, external URL
|
|
- Evidence source: [VERIFIED: url] or [UNVERIFIED]
|
|
```
|
|
|
|
**Rules:**
|
|
- Status `Accepted` = implemented or actively being implemented. `Proposed` = under review. `Rejected` stays as an ADR (the record of why we said no).
|
|
- Never delete a past ADR. Supersede with a new ADR that references the old number.
|
|
- Evidence grade mandatory (RULE 0.4). No grade → the ADR is unreviewable.
|
|
|
|
**Source:** MADR 4.0 spec — [adr/madr](https://adr.github.io/madr/) [E4]. Nygard 2011 original post `cognitect.com/blog/2011/11/15/documenting-architecture-decisions` [E4].
|