# 🤖 Platform changelog implementation plan

> **For agentic workers:** executed natively by the session that wrote it
> (Paul, 2026-10-06: "work overnight until this is done"), with an Astra
> whole-branch review at the end. Steps use checkbox syntax.

**Goal:** `docs/site/changelog.json` generated from git, release notes and
Amadan, gated in CI, and rendered at carlosframework.com/platform/changelog.

**Architecture:** `internal/changelog` holds pure parsers and resolvers
plus a `Build` that drives three source interfaces (`Git`, `Releases`,
`Discussions`); `cmd/changelog` wires the real sources (git, gh, amadan)
and writes the file. `internal/docsite` gates the committed file. The
website vendors it through `hack/sync-docs.mjs` and renders it with one
Nunjucks template.

**Tech stack:** Go 1.26 stdlib; Eleventy 3 + markdown-it (website).

**Spec:** `docs/superpowers/specs/2026-10-06-platform-changelog-design.md`

## Global constraints

- No email address in `changelog.json` or on the page. Unknown identity = generator failure.
- No GitHub PR links (the mirror is private). Links only to amadan.net, github.com/carlosframework/releases and /docs.
- Change lines are verbatim records; the page carries one visible 🤖 on its h1.
- Website: no browser JS beyond the existing disclaimer; light and dark both work; no em dashes in new copy.
- Copy review gates the page's framing strings and the README step before anything ships.
- Tests: `export GOCACHE=$TMPDIR/gocache GOFLAGS=-mod=mod GOPROXY=off`, run `nice -n 19`, package by path, never `./...`.

## Review focus

1. A squash whose branch was later re-used by name (two tombstones over time): own-commit range must stop at the squash's parent, never pull in later work. Test: tombstone range is `<squash>^..<tombstone>` filtered to commits not on main.
2. A `#N` in a GitHub-era message that collides with a live Amadan id: rejected by the created-before-commit rule. Test with a fake discussion created after the commit.
3. A release-note bullet containing an email-like string (`bill@`): must not trip the email guard unless it is a full address from people.json or a keymail. Test both.
4. A tag with zero first-parent commits in range (v0.24.1 had one, a re-tag could have none): renders "No changes" rather than failing. Test.
5. A heading in old notes (`## carlos deploy`) inside a markdown body: demoted to `####` so the page outline stays intact. Test.

---

### Task 1: identities and credit (`internal/changelog/credit.go`)

- Create `credit.go`, `credit_test.go`.
- Produces: `type People map[string]string` (email or keymail → display name, keys lower-cased); `type Credit struct{ Person string `json:"person,omitempty"`; Agents []string `json:"agents,omitempty"` }`; `func ParseIdentity(name, email string, people People) (person, agent string, skip bool, err error)`; `func CoAuthors(message string) [][2]string` (name, email from `Co-Authored-By:` trailers, case-insensitive); `func Tally(commits []CommitIdent, people People) ([]Credit, error)` where `type CommitIdent struct{ AuthorName, AuthorEmail, Message string }`.
- Rules from the spec's Credit paragraph. Tests: keymail agent with known person; `claude-code` → `claude`; `noreply@anthropic.com`; codex name; plain person by email; unknown email → error naming it; GitHub/ledger skipped; agent-only trailer attaches to a person author; ordering by count; an agent with no person anywhere stands alone.

### Task 2: messages, ranges and notes (`branch.go`, `notes.go`, `refs.go`)

- `func BranchName(message string) string` (three patterns, first match).
- `func DiscussionRefs(message string) []int` (`#N`, `discussion N`, `amadan #N`; deduped, sorted).
- `type Notes struct{ Form string; Sections []NoteSection; MD string }`, `type NoteSection struct{ Title string; Bullets []Bullet }`, `type Bullet struct{ MD string; Lead string; Branches []string; Docs []string }`; `func ParseNotes(body string) *Notes` (bullets form when a `- **` bullet follows a `carlos vX (platform` line; else markdown form with boilerplate stripped and headings demoted by two, capped at h6). `Lead` = text inside the first `**…**` of a bullet.
- `func CLIDocLinks(md string, cliHeadings map[string]string) []string` (inline code `carlos …` → longest heading match → `/docs/cli#anchor`).
- Tests per Review Focus 3 and 5, plus each operator-heading variant and the v0.1.0 one-paragraph body.

### Task 3: Build on fakes and on a scratch repo (`build.go`)

- Interfaces: `Git{ Tags() ([]Tag, error); FirstParent(from, to string) ([]Commit, error); Range(from, to string) ([]Commit, error); OnMain(sha string) bool; Tombstone(branch string) (string, bool); DocsHunks(sha string) ([]DocsHunk, error); Branches() map[string]bool }`, `Releases{ Body(tag string) (string, bool, error) }`, `Discussions{ Show(id int) (*Discussion, error); ForBranch(b string) ([]Discussion, error) }`.
- `func Build(src Sources, people People, links Links, site *docsite.Site) (*Changelog, error)`.
- Docs links from hunks: nearest heading at or above each added line, kept only if `site` has that page and anchor.
- Email guard over the marshalled output.
- `gitexec.go`: the real `Git` over `git` subprocesses; scratch-repo test builds v0.1.0, a direct commit, a two-parent merge, a squash with a `refs/amadan/closed/x` tombstone, and tag v0.2.0, then checks ranges, branches, credit and docs links.

### Task 4: `cmd/changelog`, people.json, real sources

- `cmd/changelog/main.go`: flags `-out`, `-repo` (default `carlos/platform`); real `Releases` over `gh release view <tag> -R carlosframework/releases --json body`, real `Discussions` over `amadan discuss show|list … -json`; loads `docs/site/people.json`, `docs/site/changelog-links.json` (missing = empty), `docsite.Load("docs/site")`.
- `docs/site/people.json` from the identities found in history (names only from git's own author names).
- Run it; read the output for every release; fix what reads wrong.

### Task 5: bullet links backfill (`docs/site/changelog-links.json`)

- For v0.19.0 on, map each bullet's lead to the branches behind it by reading each change's subject and diff. Regenerate.

### Task 6: the gate (`internal/docsite/changelog_test.go`)

- Checks from the spec's "Gates and upkeep". Mutation check: break one docs anchor and one email in a temp copy and watch each fail.

### Task 7: website

- In a worktree of `carlosframework/website` on branch `platform-changelog`: `hack/sync-docs.mjs` also vendors `changelog.json` → `src/_data/docschangelog.json` (and `--check` compares it); `src/changelog.njk`; a markdown filter for notes; `check-docs.mjs` checks the page; a link from `src/platform/index.html`. `npm run check`, then look at it in a browser at both colour schemes.

### Task 8: README release step, copy review, Astra code review, merge

- README "Releasing the platform" step 10. Copy review of the page framing and the README step. Astra review of both branches; fix; `amadan branch merge`; website PR (GitHub) left for Paul unless copy approved.