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

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

@@ -1,210 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - decisions-log.md
-  - architecture-md.md
-  - postmortem-pattern.md
-primary_sources:
-  - Michael Nygard, "Documenting Architecture Decisions" (cognitect.com/blog/2011/11/15) — the original ADR essay
-  - https://adr.github.io — ADR organization (canonical hub)
-  - https://github.com/joelparkerhenderson/architecture-decision-record — Joel Parker Henderson's ADR catalog (most-cited examples library, actively maintained)
-  - https://adr.github.io/madr/ — MADR 4.0.0 (released 2024-09-17, "Markdown Any Decision Records")
-  - https://medium.com/olzzio/y-statements-10eb07b5a177 — Olaf Zimmermann, Y-statements (SATURN 2012)
-  - https://github.com/npryce/adr-tools — adr-tools CLI (lightly maintained)
-  - https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record — ADR / Decision Log canonical meaning
-status: research-verified
----
-
-# Architecture Decision Records (ADRs)
-
-> **One ADR captures one architectural decision and its context — *immutably*.** Decisions don't get edited; they get superseded. The newest ADR wins; older ADRs remain as history.
-
-## What an ADR is (and isn't)
-
-An ADR is a **dated, numbered, status-bearing Markdown file** that captures:
-
-- **Why** a decision was made (the problem and constraints)
-- **What** was decided (the chosen path)
-- **What was considered** (the alternatives and why they lost)
-- **Consequences** (the trade-offs the team is signing up for)
-
-An ADR is **not** a design doc, RFC, spec, or proposal. Those describe future work; an ADR records a *commitment that has been made*. Once accepted, it is rarely edited — instead, a new ADR supersedes it.
-
-## File layout
-
-Standard:
-
-```
-.brain/adrs/
-├── 0001-record-architecture-decisions.md
-├── 0002-use-postgres-not-mysql.md
-├── 0003-rest-not-graphql.md
-├── 0004-deprecate-redis-cache.md
-└── README.md
-```
-
-Numbering is strictly sequential. Filename pattern: `NNNN-kebab-case-title.md`.
-
-## The Nygard format (canonical, ~2011)
-
-Michael Nygard's [original 2011 essay](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions) gave the field its first standard:
-
-```markdown
-# 1. Record architecture decisions
-
-Date: 2026-04-27
-
-## Status
-
-Accepted
-
-## Context
-
-What is the issue we're seeing that motivates this decision?
-
-## Decision
-
-What is the change we're making?
-
-## Consequences
-
-What becomes easier or harder because of this change?
-```
-
-Five sections: Title, Date, Status, Context, Decision, Consequences. Short and disciplined.
-
-## Status values
-
-The set is small and load-bearing:
-
-| Status | Meaning |
-|---|---|
-| `Proposed` | Drafted, under discussion, not yet accepted |
-| `Accepted` | Decided. The team is committed. |
-| `Rejected` | Considered and not adopted. Recorded so it doesn't get re-proposed without context. |
-| `Deprecated` | No longer active but not yet replaced |
-| `Superseded by ADR-NNNN` | Replaced by a newer decision |
-
-## ADR vs Architecture Decision Log (ADL) — canonical meaning
-
-The widely-cited industry view (Microsoft Azure Well-Architected Framework, AWS Prescriptive Guidance, adr.github.io):
-
-> "An Architectural Decision Record (ADR) captures a single AD and its rationale; **the collection of ADRs constitutes the decision log.**"
-
-So the canonical "decision log" is **the index of all ADRs** in `.brain/adrs/`, not a separate folder. Generate it from filenames + status fields, or maintain `.brain/adrs/README.md` as a hand-written index.
-
-Some teams *additionally* maintain a lighter `.brain/decisions/` folder for non-architectural decisions (tooling picks, library swaps, day-to-day commitments). That's a **team convention, not industry standard** — but it's a useful split when ADRs feel too heavyweight for routine choices. The audit should detect both shapes and not flag either as wrong; just note which convention is in play.
-
-## MADR 4.0.0 (Markdown Any Decision Records)
-
-MADR ([adr.github.io/madr](https://adr.github.io/madr/)) is the current canonical structured variant. Released **4.0.0 on 2024-09-17** with a notable rename: the *A* now stands for *Any* (was *Architectural*) — explicitly broadening scope to non-architectural decisions. Templates: `adr-template.md`, `adr-template-minimal.md`, `adr-template-bare.md`. **YADR** (YAML ADRs) added March 2026.
-
-MADR adds:
-
-- `Deciders:` (who decided)
-- `Consulted:` / `Informed:` (who else was looped in)
-- More explicit "Considered Options" with pros/cons per option
-
-```markdown
----
-status: accepted
-date: 2026-04-27
-deciders: alice, bob
-consulted: data-team
-informed: engineering-all
----
-
-# Use Postgres, not MySQL
-
-## Context and Problem Statement
-
-We need a relational database for the user-account service.
-
-## Decision Drivers
-
-- Mature JSONB support
-- Strong concurrency story
-- Existing team skills
-
-## Considered Options
-
-- Postgres
-- MySQL
-- SQLite
-
-## Decision Outcome
-
-Chosen: **Postgres**, because of JSONB + concurrency + team skills.
-
-### Consequences
-
-- Good: rich query power, strong type system
-- Bad: ops overhead vs SQLite
-
-## Pros and Cons of the Options
-
-### Postgres
-- Good: ...
-- Bad: ...
-
-### MySQL
-- Good: ...
-- Bad: ...
-```
-
-MADR's structure scales better to larger teams and audit trails. Nygard's brevity is right for smaller teams. Pick one and stick with it.
-
-## Y-statements (Zimmermann)
-
-A concise alternative format positioned by adr.github.io as current best practice. Single-sentence form:
-
-> *"In the context of `<use case / user story>`, facing `<concern>` we decided for `<option>` and neglected `<other options>`, to achieve `<system qualities>` / `<desired consequences>`, accepting `<downside / undesired consequences>`."*
-
-Origin: Olaf Zimmermann, SATURN 2012. Useful as a one-line summary line at the top of a longer ADR, or as the entire ADR for small reversible choices. Pairs well with MADR.
-
-## Tooling (April 2026)
-
-- **`adr-tools`** by Nat Pryce: https://github.com/npryce/adr-tools — Bash CLI; **lightly maintained** as of April 2026 (no recent releases; MADR-support PR #43 was rejected for maintenance burden). Still functional for the ADR-creation workflow it was built for.
-- **`adr-log`**: generates a Markdown index from a folder of ADRs.
-- **`log4brains`**: web-based ADR browser; check current maintenance state before adopting.
-- **`adr-manager`**: web-UI ADR editor.
-- **For new projects, no tool is required.** `mkdir -p .brain/adrs && cp ~/.adr-templates/madr-minimal.md .brain/adrs/0001-record-architecture-decisions.md` is enough. Tooling adds friction; many teams now skip it.
-
-## How AGENTS.md should reference ADRs
-
-In the `Where to find things` section:
-
-```markdown
-- **Architecture Decision Records:** `.brain/adrs/` — newest-first; read before making architectural changes
-```
-
-In the `Memory primitives` section:
-
-```markdown
-- **Before making architectural decisions**, read `.brain/adrs/` newest-first. If your proposed change conflicts with an `Accepted` ADR, write a new ADR superseding it; don't silently override.
-```
-
-## Common anti-patterns
-
-- **No `.brain/adrs/` folder at all** — decisions live in random PR descriptions, Slack, code comments. Memory fragmentation.
-- **ADRs as RFCs** — files marked `Proposed` that never get marked `Accepted` or `Rejected`. Status drift.
-- **Editing accepted ADRs** — defeats the audit trail. Edits should be supersessions instead.
-- **No `Status:` field** — readers can't tell what's current.
-- **Mixed numbering schemes** — `001-foo.md`, `2-bar.md`, `0003-baz.md`. Pick `NNNN-` four-digit and stick with it.
-- **No ADR for the introduction of ADRs themselves** — the first ADR (`0001`) should be "Record architecture decisions" so the practice itself is decided.
-
-## Audit checks for ADRs
-
-1. **Folder exists** at `.brain/adrs/` (or close — `.brain/architecture/decisions/`, `adrs/`, etc.).
-2. **Numbering is consistent** (`NNNN-` four-digit, sequential).
-3. **Each ADR has a `Status:` field**.
-4. **No ADRs are in `Proposed` for >30 days** (probably abandoned — flag).
-5. **`.brain/adrs/` is referenced from AGENTS.md**.
-
-## Cross-references
-
-- Decision log (looser): `decisions-log.md`
-- Architecture overview: `architecture-md.md`
-- Adding ADRs to existing repo: `../recipes/adr-introduction.md`
-- Memory organization: `../recipes/memory-organization.md`

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

@@ -1,190 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - adr-pattern.md
-  - decisions-log.md
-  - changelog.md
-primary_sources:
-  - https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html — Aleksey Kladov (matklad), "ARCHITECTURE.md" (the canonical pattern essay, Feb 2021)
-  - https://github.com/rust-lang/rust-analyzer/blob/master/docs/dev/architecture.md — rust-analyzer's ARCHITECTURE.md (the canonical example)
-  - https://github.com/sourcegraph/sourcegraph/blob/main/doc/dev/background-information/architecture/index.md — Sourcegraph's adoption of the pattern
-  - https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record — Microsoft Azure WAF on architecture documentation
-status: research-verified
----
-
-# ARCHITECTURE.md — current state, in 30 minutes
-
-> **ARCHITECTURE.md answers: "I'm new here. Where do I look first?"** Not "what did we decide?" (that's ADRs) and not "what shipped?" (that's CHANGELOG). It is a *map of the codebase as it currently is*, optimized for someone landing in the repo cold.
-
-This pattern delivers **Promise 2 (token-and-context-optimized)** by giving an LLM agent a single high-signal entry into the codebase's structure, and **Promise 1 (less-wasteful)** by replacing the scattered "tribal knowledge" that otherwise accumulates in PR comments, Slack threads, and 3-year-old wiki pages.
-
-## Origin and canonical source
-
-The pattern was named and codified by **Aleksey Kladov** (handle: *matklad*, lead author of rust-analyzer) in the February 2021 blog post [**"ARCHITECTURE.md"**](https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html). The canonical exemplar is rust-analyzer's own [`docs/dev/architecture.md`](https://github.com/rust-lang/rust-analyzer/blob/master/docs/dev/architecture.md).
-
-Kladov's framing:
-
-> "Looking at someone else's code is hard, but very useful sometimes. The best help for an outsider is a single document, a map, which describes the *bird's-eye view* of the project, and explains how to navigate the code."
-
-The pattern has spread widely — Sourcegraph, Tantivy, hyperqueue, ripgrep, and many others use a doc by the same name (or `architecture/` folder with the same shape).
-
-## What ARCHITECTURE.md *is* (and what it's not)
-
-| ARCHITECTURE.md | Not ARCHITECTURE.md |
-|---|---|
-| Current state of the system | History of how it got here (→ git log, ADRs) |
-| Map of the codebase ("Module X lives at `src/x/`") | Decision rationale ("Why did we pick X?" → ADRs) |
-| 30-minute onboarding | Comprehensive technical reference (→ separate docs) |
-| Names directories and the responsibility of each | Lists every file (→ tooling) |
-| Cross-cutting concerns (concurrency model, error handling, lifetime) | API documentation (→ generated docs) |
-| Non-obvious intentional choices ("we deliberately don't use X") | Future plans (→ ROADMAP.md) |
-| Updated when architecture changes | Updated weekly (→ PLAN.md) |
-
-The discipline is: **document things that won't change much, that an experienced engineer would still want explained.** Module purpose, layering, where-data-flows-from-input-to-output, how-tests-are-organized, what-not-to-do.
-
-## The 30-minute onboarding shape
-
-Kladov's recommended sections (with this skill's annotations):
-
-### 1. Bird's-eye view
-
-One paragraph or one diagram. What does this project *do*? Who calls it, what does it call?
-
-```markdown
-## Bird's-eye view
-
-`acme-cli` is a Rust binary that reads YAML config from `acme.yaml`,
-queries an HTTPS API, and writes Markdown reports to stdout. It has
-no persistent state. It is invoked from CI in the user's repo.
-```
-
-If a diagram clarifies — use one. ASCII boxes are fine; Mermaid is fine; an image is fine. Don't gold-plate.
-
-### 2. Code map
-
-The load-bearing section. **For each top-level directory, one paragraph: what's in it, what's the responsibility, where the boundaries are.**
-
-```markdown
-## Code map
-
-### `src/cli/`
-Argument parsing (clap), command dispatch. No business logic — delegates to `src/core/`.
-
-### `src/core/`
-The orchestrator. Reads config, fans out to API client, aggregates results. **The only module allowed to depend on both the config layer and the API layer.**
-
-### `src/api/`
-HTTP client (reqwest). One module per endpoint group. Adding a new endpoint? Look here.
-
-### `tests/`
-Integration tests. Use the `wiremock` fixture, not real HTTP.
-```
-
-A reader (human or agent) can immediately answer: *"I want to add a new API endpoint. Where?"*
-
-### 3. Cross-cutting concerns
-
-Things that span modules and aren't inferable from the code map.
-
-```markdown
-## Cross-cutting concerns
-
-- **Error handling**: `anyhow::Error` everywhere except `src/api/` (typed errors). See ADR-0007.
-- **Concurrency**: single-threaded by default; `--parallel N` spawns tokio. Only `src/core/parallel.rs` knows async.
-- **Logging**: `tracing`, structured JSON. `RUST_LOG` configures.
-```
-
-### 4. Non-obvious intentional choices
-
-The "we deliberately don't do X" section. Saves future contributors hours.
-
-```markdown
-## Things we deliberately don't do
-
-- **No async by default.** Tokio startup dominated benchmarks. See ADR-0011.
-- **No plugin system.** Rejected (ADR-0014).
-- **No config format other than YAML.** TOML support was removed in v1.2.0.
-```
-
-ARCHITECTURE.md *summarizes* the decision and points at the ADR for *why*.
-
-### 5. Where to look first
-
-The newcomer's quick-start. Optional but high-value for LLM agents — it's a routing table for common tasks.
-
-```markdown
-## Where to look first
-
-- **Adding a CLI flag?** `src/cli/args.rs`, then dispatch in `src/cli/mod.rs`.
-- **Adding an API endpoint?** `src/api/`. Mirror an existing endpoint.
-- **Investigating a CI failure?** `tests/integration/` first, then logs.
-- **Performance regression?** `benches/` and `cargo bench`.
-```
-
-## Length and ergonomics
-
-Kladov's own rust-analyzer ARCHITECTURE.md is ~600 lines. That's at the upper end. **For most repos, 200–400 lines is right.**
-
-Under 100 lines → probably missing the code map.
-Over 800 lines → split. Move detail into per-module READMEs (`src/api/README.md`) and keep ARCHITECTURE.md as the bird's-eye + index.
-
-This skill's general guidance: **entry-level docs under ~200 lines, pushed-down detail in subdirectory READMEs.** See `../guidance/context-budget.md`.
-
-## Distinction from ADRs
-
-The most-confused boundary: ARCHITECTURE.md is **present-tense, mutable, system-wide**; ADRs are **past-tense, immutable, per-decision**. ARCHITECTURE.md answers "Where does X live?"; ADRs answer "Why did we choose X?". ARCHITECTURE.md *links* to ADRs ("see ADR-0007"), never duplicates them.
-
-## Update discipline
-
-ARCHITECTURE.md goes stale faster than ADRs and slower than PLAN.md. Recommended cadence:
-
-1. **PR-level**: any PR that adds, renames, or removes a top-level directory must update ARCHITECTURE.md in the same PR. Enforce with a CI check or a CODEOWNERS rule. See `../recipes/self-healing-hooks.md`.
-2. **Quarterly review**: a maintainer re-reads ARCHITECTURE.md against the current tree and patches drift.
-3. **LLM-on-diff**: when a large refactor lands, run an LLM-on-diff pass against ARCHITECTURE.md to flag suspect sections. See `../audit-patterns/staleness-tooling.md`.
-
-## How AGENTS.md links ARCHITECTURE.md
-
-In the `Where to find things` section:
-
-```markdown
-- **Architecture:** `ARCHITECTURE.md` — start here if you're new to the codebase
-```
-
-In the `Memory primitives` section:
-
-```markdown
-- **Before making changes that span multiple modules**, read `ARCHITECTURE.md` for the code map and cross-cutting concerns. Architecture-altering changes also require a new ADR.
-```
-
-`ARCHITECTURE.md` at repo root is the recommended location (matklad's pattern). Avoid `.brain/architecture/index.md` unless you have a folder full of related docs.
-
-## Audit checks
-
-1. **File exists** at `/ARCHITECTURE.md` (repo root, per matklad).
-2. **Code map covers all top-level src directories.** Diff `ls src/` against the headings in the code map; missing entries = staleness.
-3. **No directory mentioned in the code map is missing from disk.** Renames or removals that didn't update the doc.
-4. **Length is in 100–800 range.** Both extremes are flagged.
-5. **AGENTS.md references ARCHITECTURE.md**, not just `.brain/`.
-6. **`Last reviewed:` line or YAML `date:` is within the last 180 days.** Older = quarterly review missed.
-
-## Common anti-patterns
-
-- **No ARCHITECTURE.md** — newcomers and agents navigate by `ls` and pattern-match. Slow.
-- **Feature list, not a code map** — describes what the product does, not how it's built.
-- **History, not present-tense** — narrates evolution. That's a blog post.
-- **Duplicates ADR content** — copy-pasted "why" rationale. Link to the ADR instead.
-- **Alphabetical code map** — group by responsibility (core → adapters → entry-points).
-- **Stale code map** — directories renamed in code, not in the doc. Catch with the audit.
-- **Outsourced to a wiki** — agents can't read Confluence; drift is guaranteed. Keep it in the repo.
-
-## Cross-references
-
-- ADR pattern (decisions, not state): `adr-pattern.md`
-- Decision log (collection of ADRs): `decisions-log.md`
-- Changelog (shipped, not state): `changelog.md`
-- Plan / roadmap (planned, not state): `plan-roadmap.md`
-- Self-healing PR-gate hooks: `../recipes/self-healing-hooks.md`
-- LLM-on-diff staleness detection: `../audit-patterns/staleness-tooling.md`
-- Context budget guidance (200-line target): `../guidance/context-budget.md`
-- AGENTS.md "Where to find things" section: `../standards/agents-md-spec.md`

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

@@ -1,183 +0,0 @@
----
-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`