@adia-ai/adia-ui-forge 0.1.2 → 0.1.3

package/skills/adia-ui-ops/references/doc-types/changelog.md

@@ -0,0 +1,183 @@
+---
+date: 2026-04-27
+coverage: canonical
+peers:
+  - plan-roadmap.md
+  - decisions-log.md
+  - architecture-md.md
+primary_sources:
+  - https://keepachangelog.com/en/1.1.0/ — Keep a Changelog 1.1.0 (the canonical convention)
+  - https://semver.org/spec/v2.0.0.html — Semantic Versioning 2.0.0
+  - https://github.com/changesets/changesets — changesets (monorepo-friendly)
+  - https://github.com/orhun/git-cliff — git-cliff (commit-message-driven generator)
+  - https://github.com/googleapis/release-please — release-please (Conventional-Commits release automation)
+  - https://www.conventionalcommits.org/en/v1.0.0/ — Conventional Commits 1.0.0
+status: research-verified
+---
+
+# CHANGELOG.md — what shipped, organized for humans
+
+> **A changelog is for humans, not machines.** That single line, from [keepachangelog.com](https://keepachangelog.com/en/1.1.0/), is the load-bearing principle. An auto-generated dump of commit messages is *not* a changelog — it's a commit log with a different filename.
+
+This pattern delivers **Promise 1 (less-wasteful)** by giving the agent a single canonical "what shipped, when" surface, and **Promise 5 (continuously-learning)** by giving the team a release ritual that captures intent, not just diffs.
+
+## The Keep-a-Changelog convention (canonical)
+
+[Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) is the de facto industry standard. It defines:
+
+### Six change categories — pick from these, do not invent new ones
+
+| Category | Meaning |
+|---|---|
+| **Added** | New features |
+| **Changed** | Changes in existing functionality |
+| **Deprecated** | Soon-to-be-removed features (still works for now) |
+| **Removed** | Now-removed features |
+| **Fixed** | Bug fixes |
+| **Security** | Vulnerabilities patched (cite CVE if applicable) |
+
+### The "Unreleased" section pattern
+
+The top of every active CHANGELOG.md has an `## [Unreleased]` section. Engineers add entries there as they merge PRs. At release time, the `[Unreleased]` heading is renamed to `[X.Y.Z] - YYYY-MM-DD` and a fresh empty `[Unreleased]` is added at the top.
+
+This means the changelog is *always* drafting the next release; it never lags behind.
+
+### Date format
+
+ISO 8601 (`YYYY-MM-DD`). Always. Anything else triggers ambiguity (US vs EU date order).
+
+### Newest-on-top ordering
+
+Most recent release at the top. The most-recently-shipped change is what the agent (and humans) usually want to know about.
+
+## Sample minimal CHANGELOG.md
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- `--strict` flag to validate frontmatter before commit.
+
+### Fixed
+- Pointer validator no longer crashes on Windows path separators (#412).
+
+## [1.4.0] - 2026-04-19
+
+### Added
+- Pre-commit hook scaffold for AGENTS.md freshness checks.
+- Lychee-based broken-link detector wired into CI.
+
+### Changed
+- Default ADR template upgraded to MADR 4.0.0.
+
+### Deprecated
+- `--legacy-format` flag; will be removed in 2.0.0.
+
+## [1.3.1] - 2026-03-22
+
+### Fixed
+- Crash on empty `.brain/postmortems/` folder (#388).
+
+### Security
+- Bumped `@some/dep` to 4.2.1 to patch CVE-2026-12345.
+
+[Unreleased]: https://github.com/acme/repo/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/acme/repo/compare/v1.3.1...v1.4.0
+[1.3.1]: https://github.com/acme/repo/compare/v1.3.0...v1.3.1
+```
+
+The reference links at the bottom let readers click through to the diff. Tools regenerate them automatically.
+
+## Relationship to git tags and SemVer
+
+[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) gives the version-number meaning:
+
+- **MAJOR** — incompatible API change
+- **MINOR** — backward-compatible new feature
+- **PATCH** — backward-compatible bug fix
+
+The CHANGELOG is the **human narrative** that justifies the version bump. The git tag is the **machine pointer** to the commit that release was cut from.
+
+Convention: tag is `vX.Y.Z` (with the `v` prefix); changelog heading is `[X.Y.Z]` (without the `v`). The reference link at the bottom of the changelog connects them.
+
+The changelog **drives** the version, not the reverse. If `Unreleased` has only `Fixed` entries → next release is PATCH. If it has `Added` → MINOR. If it has `Removed` of a public API → MAJOR.
+
+## Tooling — automation that helps vs. automation that hurts
+
+### Tools that help
+
+| Tool | Approach | Best for |
+|---|---|---|
+| **[changesets](https://github.com/changesets/changesets)** | Each PR adds a `.changeset/*.md` describing the change + intended bump; CI aggregates at release time | Monorepos (especially `pnpm` workspaces); strong fit for libraries |
+| **[release-please](https://github.com/googleapis/release-please)** | Reads Conventional Commits, opens release PRs that update CHANGELOG and bump version | Repos already on Conventional Commits; lightweight to adopt |
+| **[git-cliff](https://github.com/orhun/git-cliff)** | Highly configurable Conventional-Commits → CHANGELOG generator | Teams that want full templating control |
+
+All three preserve the **categorical narrative** — they classify changes into Added/Changed/Fixed/etc. via commit-prefix conventions, not just paste commit messages.
+
+### The auto-generated-commits anti-pattern
+
+```markdown
+## v1.4.0
+
+- Merge pull request #412 from feat/hooks
+- Update README.md
+- chore(deps): bump foo from 1.0 to 1.1
+- fix lint
+- wip
+- address review
+- Merge pull request #418 from fix/edge
+```
+
+This is **not a changelog**. It is a low-signal commit dump with no narrative. The agent (and humans) get nothing actionable from it.
+
+If you can't justify the cost of writing categorized entries, **do not auto-generate this**. Instead: link to GitHub Releases or `git log --oneline` from a brief CHANGELOG note. At least that's honest about what it is.
+
+## How AGENTS.md links the changelog
+
+In the `Where to find things` section:
+
+```markdown
+- **Released changes:** `CHANGELOG.md` — what shipped, by version, newest-first
+```
+
+In the `Memory primitives` section:
+
+```markdown
+- **Before claiming "feature X exists/doesn't exist"**, check `CHANGELOG.md` — features are added, removed, deprecated over time. The current state is the diff of all releases.
+```
+
+## Audit checks
+
+1. **`CHANGELOG.md` exists at repo root.** Not in `.brain/`. Convention is root.
+2. **Header credits Keep a Changelog and SemVer.** A common 2-line preamble; signals the format.
+3. **An `[Unreleased]` section exists at the top.** Without it, the changelog is always lagging.
+4. **Every release entry has an ISO date** (`YYYY-MM-DD`).
+5. **Categories used are from the Keep-a-Changelog set** (Added, Changed, Deprecated, Removed, Fixed, Security). Custom categories like "Misc" or "Other" → flag.
+6. **Latest release date in CHANGELOG matches latest git tag.** Drift = either an untagged release or an unreleased changelog entry.
+7. **Reference-link footnotes resolve** — `[1.4.0]: https://…` URLs are reachable. Lychee catches this; see `../audit-patterns/staleness-tooling.md`.
+
+## Common anti-patterns
+
+- **No CHANGELOG** — releases are silent; GitHub Releases is the only narrative.
+- **Auto-generated commit dump** — discussed above. Low-signal noise.
+- **CHANGELOG inside `.brain/`** — convention is repo root; tools look there.
+- **Mixed date formats** (`19-04-2026`, `Apr 19 2026`). ISO only.
+- **Invented categories** ("New stuff", "Tweaks") — stick to the canonical six.
+- **No `[Unreleased]` section** — entries get lost between releases.
+- **Skipped versions** (1.3.0 → 1.5.0) — usually a hot-fix branch wasn't backported.
+- **Overlap with ROADMAP** — CHANGELOG is shipped past; ROADMAP is unshipped future. See `plan-roadmap.md`.
+
+## Cross-references
+
+- Plan / roadmap (forward-looking, not shipped): `plan-roadmap.md`
+- Decision log (decisions, not features): `decisions-log.md`
+- Architecture overview (current state, not history): `architecture-md.md`
+- Self-healing release automation: `../recipes/self-healing-hooks.md`
+- Staleness detection: `../audit-patterns/staleness-tooling.md`
+- AGENTS.md memory primitives section: `../standards/agents-md-spec.md`

package/skills/adia-ui-ops/references/doc-types/decisions-log.md

@@ -0,0 +1,146 @@
+---
+date: 2026-04-27
+coverage: canonical
+peers:
+  - adr-pattern.md
+  - architecture-md.md
+  - plan-roadmap.md
+primary_sources:
+  - https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record — Microsoft Azure Well-Architected Framework on ADR / decision log
+  - https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html — AWS Prescriptive Guidance, "ADRs"
+  - https://adr.github.io — ADR organization (canonical hub)
+  - https://github.com/joelparkerhenderson/architecture-decision-record — Joel Parker Henderson catalog (most-cited examples library)
+  - https://github.com/npryce/adr-tools — adr-tools, including `adr generate toc`
+  - https://github.com/adr/adr-log — adr-log Markdown index generator
+status: research-verified
+---
+
+# Decision log — what it actually is
+
+> **The canonical "decision log" is the index of all ADRs in `.brain/adrs/`. It is *not* a separate folder.** This is the load-bearing nuance most teams get wrong.
+
+## The canonical meaning (cite-able)
+
+Microsoft Azure Well-Architected Framework, AWS Prescriptive Guidance, and adr.github.io all converge on the same definition:
+
+> "An Architectural Decision Record (ADR) captures a single AD and its rationale; **the collection of ADRs constitutes the decision log.**"
+> — Microsoft Azure WAF, *Architecture decision record*
+
+> "A collection of ADRs creates a decision log that captures the architectural decisions for a project."
+> — AWS Prescriptive Guidance, *Architectural decision records*
+
+So when a repo has `.brain/adrs/0001-…md` … `0042-…md` and a `.brain/adrs/README.md` listing them, **that is the decision log**. There is no second folder needed.
+
+This skill delivers **Promise 5 (continuously-learning)** by ensuring the decision log is *navigable* — an ADR folder without an index is a scrapyard.
+
+## The two shapes the audit detects
+
+The repo-fixer audit must accept both shapes and not flag either as wrong. Just note which one is in play.
+
+| Shape | What's on disk | When appropriate |
+|---|---|---|
+| **Canonical (single-folder)** | `.brain/adrs/` containing all decisions; `.brain/adrs/README.md` is the log index | Default. Fits 90% of teams. |
+| **Split (two-folder)** | `.brain/adrs/` for big architecture decisions; `.brain/decisions/` for lighter day-to-day picks (tooling swaps, library choices, formatting conventions) | Larger orgs where ADR review is heavyweight and would gate routine choices |
+
+The split is **a team convention, not industry standard**. Some teams find it useful: ADRs gate architecture, `.brain/decisions/` lets engineers move on a tooling swap without scheduling an architecture review. Other teams find it confusing — two homes invites drift over which decision goes where.
+
+The audit's recommendation order:
+
+1. If only `.brain/adrs/` exists → recommend keeping it canonical; ensure `README.md` index is present and current.
+2. If only `.brain/decisions/` exists → recommend renaming to `.brain/adrs/` for tool/community alignment (ADR tooling expects `.brain/adrs/`).
+3. If both exist → recommend documenting the split rule in `AGENTS.md`'s "Where to find things" section so the agent knows which folder to write to.
+
+## Generating the index
+
+Three options, ordered by maintenance burden (lowest first):
+
+### Option 1 — `adr-log` (auto-generate)
+
+[`adr-log`](https://github.com/adr/adr-log) reads a folder of ADRs and writes a Markdown table of contents into a delimited region of `README.md`:
+
+```bash
+npm i -g adr-log
+adr-log -d .brain/adrs -i .brain/adrs/README.md
+```
+
+Wrap the index in begin/end markers so subsequent runs only update that region:
+
+```markdown
+# Architecture Decision Records
+
+<!-- adrlog -->
+- [ADR-0001](0001-record-architecture-decisions.md) — Record architecture decisions
+- [ADR-0002](0002-use-postgres-not-mysql.md) — Use Postgres, not MySQL
+<!-- adrlogstop -->
+```
+
+Add to a pre-commit hook or CI workflow so the index never drifts from filenames. See `../recipes/self-healing-hooks.md`.
+
+### Option 2 — `adr-tools generate toc`
+
+[`adr-tools`](https://github.com/npryce/adr-tools) ships a similar generator. Lightly maintained as of April 2026 — works, but no recent releases.
+
+```bash
+adr generate toc > .brain/adrs/README.md
+```
+
+### Option 3 — Hand-written index
+
+For small repos (<20 ADRs) the index is one line per ADR. Maintain by hand:
+
+```markdown
+# Architecture Decision Records
+
+| # | Title | Status | Date |
+|---|---|---|---|
+| [0001](0001-record-architecture-decisions.md) | Record architecture decisions | Accepted | 2024-01-12 |
+| [0002](0002-use-postgres-not-mysql.md) | Use Postgres, not MySQL | Accepted | 2024-03-04 |
+| [0003](0003-rest-not-graphql.md) | REST, not GraphQL | Superseded by 0017 | 2024-03-19 |
+| [0017](0017-graphql-for-public-api.md) | GraphQL for public API | Accepted | 2025-11-08 |
+```
+
+The hand-written form **adds the Status column**, which the auto-generated forms typically omit. Worth it for a navigable log.
+
+## How AGENTS.md links the decision log
+
+In the `Where to find things` section:
+
+```markdown
+- **Architecture Decision Records:** `.brain/adrs/` — see `.brain/adrs/README.md` for the indexed log; newest-first
+- **Lightweight decisions** (if your team uses the split): `.brain/decisions/`
+```
+
+In the `Memory primitives` section:
+
+```markdown
+- **Before making architectural decisions**, consult the decision log at `.brain/adrs/README.md`. If your proposed change conflicts with an `Accepted` ADR, write a new ADR superseding it; don't silently override.
+```
+
+## Audit checks for the decision log
+
+1. **`.brain/adrs/` exists** (or `.brain/architecture/decisions/` — accepted alias).
+2. **An index file exists** at `.brain/adrs/README.md` listing all ADRs.
+3. **The index is current** — every `NNNN-*.md` filename in the folder appears in the index. No orphans, no broken links.
+4. **The index sort order is meaningful** (chronological or by status group, not random).
+5. **AGENTS.md points at the index file**, not just the folder. Folder-only pointers force the agent to `ls` and guess.
+6. **If `.brain/decisions/` also exists**, AGENTS.md documents the split rule.
+
+The "index is current" check is the high-value one — it catches drift after a teammate adds an ADR but forgets to update the index.
+
+## Common anti-patterns
+
+- **No index** — folder of 40 ADRs, no `README.md`. The decision log exists but isn't navigable.
+- **Stale index** — index lists 18 ADRs; folder has 26. Catch with the audit + auto-generation.
+- **Two parallel logs that drift** — `.brain/adrs/` and `.brain/decisions/` both have ADRs about Postgres. Pick a rule and document it.
+- **Decision log as a single Markdown file** — `.brain/decisions.md` with all decisions in one document. Editing one decision rewrites file history; no per-decision audit trail. Strongly recommended against.
+- **Folder named `.brain/architecture-decisions/`** — works, but `.brain/adrs/` is what tooling expects. Prefer `.brain/adrs/`.
+- **Numbering reset on folder split** — if you split into `.brain/adrs/` and `.brain/decisions/`, do NOT restart numbering at 0001 in the second folder. Keep the global sequence so cross-references work.
+
+## Cross-references
+
+- ADR pattern (canonical): `adr-pattern.md`
+- Architecture overview (current state, not decisions): `architecture-md.md`
+- Plan / roadmap (forward-looking, not decisions): `plan-roadmap.md`
+- Self-healing index generation: `../recipes/self-healing-hooks.md`
+- Memory organization: `../recipes/memory-organization.md`
+- AGENTS.md memory primitives section: `../standards/agents-md-spec.md`

package/skills/adia-ui-ops/references/doc-types/plan-roadmap.md

@@ -0,0 +1,182 @@
+---
+date: 2026-04-27
+coverage: canonical
+peers:
+  - decisions-log.md
+  - changelog.md
+  - architecture-md.md
+primary_sources:
+  - https://keepachangelog.com/en/1.1.0/ — Keep a Changelog 1.1.0 (date-stamp convention)
+  - https://linear.app/docs/markdown-export — Linear Markdown export (issues / projects)
+  - https://help.shortcut.com/hc/en-us/articles/360057451511 — Shortcut Markdown / API export
+  - https://docs.basecamp.com/article/29-export-your-account — Basecamp project export
+  - https://docs.github.com/en/issues/planning-and-tracking-with-projects — GitHub Projects (issue-tracker plan source)
+  - https://www.atlassian.com/agile/project-management/program-roadmaps — Atlassian on roadmaps vs plans
+status: research-verified
+---
+
+# PLAN.md and ROADMAP.md — active work vs forward-looking
+
+> **PLAN.md is *now* — what's in flight this week or sprint. ROADMAP.md is *next* — what's coming this quarter or year.** They are two different documents with different update cadences and different audiences. Conflating them is the most common failure mode.
+
+This pattern delivers **Promise 1 (less-wasteful)** and **Promise 3 (less-prone-to-staleness)**: when the boundary between active and forward-looking is clear, neither doc rots into a TODO graveyard.
+
+## The split
+
+| | `.brain/PLAN.md` | `.brain/ROADMAP.md` |
+|---|---|---|
+| **Horizon** | This week / sprint / current iteration | This quarter / half / year |
+| **Granularity** | Specific tasks, owners, due dates | Themes, milestones, target months |
+| **Cadence** | Updated weekly or per-sprint | Updated quarterly |
+| **Audience** | The team doing the work; LLM agents picking up tasks | Stakeholders, leadership, contributors deciding whether to invest |
+| **Status verbs** | "in progress", "blocked", "in review", "done" | "planned", "in progress", "shipped", "deferred" |
+| **Source of truth** | Often a mirror/export of the issue tracker | Hand-maintained by leads/PMs |
+
+If a team has only one of the two, **`PLAN.md` is the higher-value one for LLM agents** — the agent needs to know what to pick up, not what's coming in Q3. Skip `ROADMAP.md` until there is one to publish.
+
+## PLAN.md — shape and conventions
+
+### Minimal template
+
+```markdown
+---
+updated: 2026-04-27
+horizon: 2026-W17 (Apr 21 – Apr 27)
+---
+
+# Plan — Week of 2026-04-21
+
+## In progress
+
+- **[#412] Migrate auth to Auth.js v5** — @alice — due 2026-04-28
+- **[#418] Replace Redis with Postgres LISTEN/NOTIFY** — @bob — due 2026-05-02
+  - Blocked on ADR-0042 review
+
+## Up next (this week)
+
+- [#421] Cron worker → BullMQ — unassigned
+- [#423] Strip dead `lib/legacy/` — @carol
+
+## Done this week
+
+- [x] [#405] Bump TypeScript 5.7 → 5.8 (@alice, merged 2026-04-23)
+- [x] [#408] Drop Node 20 from CI matrix (@bob, merged 2026-04-25)
+
+## Archive
+
+See `.brain/archive/plan-2026-W16.md`.
+```
+
+### Conventions
+
+- **Date the doc**: Keep-a-Changelog-style `updated: YYYY-MM-DD` in YAML frontmatter, plus an English `Week of …` line in the H1. Without a date stamp the agent can't tell whether the plan is current. ([keepachangelog.com](https://keepachangelog.com/en/1.1.0/) date-stamp convention.)
+- **Issue numbers**: link to the tracker so the plan is a *view*, not a parallel source of truth.
+- **Owners**: an unowned item drifts. If no one will own it this week, push it to the roadmap.
+- **Due dates**: explicit ISO dates beat "next week" — relative dates rot.
+- **Archive completed work weekly**: copy the "Done" section to `.brain/archive/plan-YYYY-Www.md` and clear it from `PLAN.md`. The archive is a free changelog.
+
+### The TODO-graveyard anti-pattern
+
+The most common failure: items accumulate, nothing leaves. After a year `PLAN.md` is 800 lines, half of it is "Up next" from 8 months ago, the agent doesn't know which items are real.
+
+Mitigations:
+
+1. **Time-box "Up next"** to the current iteration. Items that don't make it move to `ROADMAP.md` or get closed.
+2. **Archive on a fixed cadence** (every Friday, end-of-sprint).
+3. **Run a staleness audit**: any line item with a due date >30 days in the past, or unedited for >60 days, is flagged. See `../audit-patterns/staleness-tooling.md`.
+
+## ROADMAP.md — shape and conventions
+
+### Minimal template
+
+```markdown
+---
+updated: 2026-04-15
+horizon: 2026-Q2 / Q3
+---
+
+# Roadmap
+
+## Now (Q2 2026)
+
+- **Multi-tenant scoping** — required for enterprise GA. Owner: @alice. Target: 2026-05.
+- **Webhook delivery v2** — exponential backoff, replay tooling. Owner: @bob. Target: 2026-06.
+
+## Next (Q3 2026)
+
+- **Self-serve billing portal** — Stripe Customer Portal integration.
+- **OpenTelemetry instrumentation** — replace ad-hoc logging.
+
+## Later (2026-H2 and beyond)
+
+- Federated SSO
+- Audit-log export to customer S3
+
+## Recently shipped
+
+- 2026-Q1 — SAML SSO (Enterprise tier)
+- 2025-Q4 — Async webhook delivery v1
+```
+
+### Conventions
+
+- **Now / Next / Later** is the standard public-roadmap shape ([ProductPlan](https://www.productplan.com/learn/now-next-later-roadmap/) popularized this; widely adopted). Keeps things vague enough to ship.
+- **No daily-task granularity.** If an item belongs in a sprint, it belongs in `PLAN.md`.
+- **Recently shipped** doubles as a release-notes pointer — link to `CHANGELOG.md`.
+- **Quarterly review** ritual: at end of quarter, move "Now" → "Recently shipped", promote "Next" → "Now", review "Later".
+
+## Issue-tracker exports — when the plan IS the export
+
+Many teams treat the issue tracker as truth and `PLAN.md` as a generated view. This works well — and the agent gets a Markdown view it can read without API access.
+
+| Tool | Export mechanism | Notes |
+|---|---|---|
+| **Linear** | [Markdown export](https://linear.app/docs/markdown-export) per issue or project; API for bulk | Project view exports clean Markdown with status grouping |
+| **Shortcut (formerly Clubhouse)** | [API + Markdown rendering in CLI](https://help.shortcut.com/hc/en-us/articles/360057451511) | Iteration views map to weekly plans |
+| **GitHub Projects** | [GraphQL API](https://docs.github.com/en/graphql/reference/objects#projectv2); community scripts dump views to Markdown | Native to GitHub — no separate auth |
+| **Jira** | REST API; `jira-cli`, `gojira` | Heavier setup; usually only worth it for Jira-mandated orgs |
+| **Basecamp** | [Account export](https://docs.basecamp.com/article/29-export-your-account) | Coarser; better for archive than weekly plan |
+
+The pattern: a CI job (or pre-commit hook) regenerates `.brain/PLAN.md` from the tracker on a cron schedule, commits the diff. Now the agent reads a current plan without an API token.
+
+## How AGENTS.md links them
+
+In the `Where to find things` section:
+
+```markdown
+- **Active plan:** `.brain/PLAN.md` — what's in flight this week
+- **Roadmap:** `.brain/ROADMAP.md` — quarterly horizon
+```
+
+In the `Memory primitives` section:
+
+```markdown
+- **When picking up work**, start at `.brain/PLAN.md`. Items there are scoped for the current iteration.
+- **For longer-horizon questions** ("are we going to support X?"), check `.brain/ROADMAP.md` before proposing new work.
+```
+
+## Audit checks
+
+1. **Date stamps present** — `updated:` frontmatter or visible date in H1. A `PLAN.md` without a date is unverifiable.
+2. **PLAN.md updated within the last 14 days** (sprint cadence). Older = staleness flag.
+3. **ROADMAP.md updated within the last 90 days** (quarterly cadence). Older = staleness flag.
+4. **No items in PLAN.md with due dates >30 days past** (TODO graveyard).
+5. **`.brain/PLAN.md` and `.brain/ROADMAP.md` are referenced from AGENTS.md.**
+6. **Archive folder exists** if the team is using weekly archival (`.brain/archive/plan-YYYY-Www.md`).
+
+## Common anti-patterns
+
+- **One file called `TODO.md`** at repo root, mixing this-week and someday. Split it into PLAN.md + ROADMAP.md or kill it.
+- **No date on either doc** — agent can't tell if the plan is from last sprint or last year.
+- **PLAN.md as immortal backlog** — items added, never removed. Time-box and archive.
+- **ROADMAP.md with weekly-task granularity** — wrong horizon. Push detail to PLAN.md.
+- **PLAN.md and the issue tracker disagree** — pick one as truth (usually the tracker) and generate the other.
+- **Roadmap contains commitments without owners or target months** — it's a wishlist, not a roadmap.
+
+## Cross-references
+
+- Decision log (decisions, not plans): `decisions-log.md`
+- Changelog (shipped, not planned): `changelog.md`
+- Self-healing PLAN.md regeneration: `../recipes/self-healing-hooks.md`
+- Staleness detection: `../audit-patterns/staleness-tooling.md`
+- AGENTS.md "Where to find things" section: `../standards/agents-md-spec.md`