Start a changelog and trim the release runbook

.github/workflows/ci.yml

@@ -54,3 +54,15 @@ jobs:
       - run: npm ci --ignore-scripts
       - run: npm audit
       - run: npm run check
+      # A missing entry found at tag time would cost the tagged version, so check it before the tag exists.
+      - name: Require a changelog entry for an untagged version
+        run: |
+          set -euo pipefail
+          version="$(node --print 'JSON.parse(require("node:fs").readFileSync("package.json", "utf8")).version')"
+          status=0
+          git ls-remote --exit-code --tags origin "refs/tags/v$version" > /dev/null || status=$?
+          case "$status" in
+            0) echo "v$version is tagged, so this check does not apply." ;;
+            2) node scripts/check-changelog.js "$version" ;;
+            *) exit "$status" ;;
+          esac

.github/workflows/publish.yml

@@ -29,6 +29,8 @@ jobs:
           package-manager-cache: false
       - name: Verify tag and source commit
         run: bash scripts/check-release-source.sh
+      - name: Require a changelog entry for this version
+        run: node scripts/check-changelog.js "$GITHUB_REF_NAME"
       - name: Reuse successful CI for this source
         env:
           GH_TOKEN: ${{ github.token }}

AGENTS.md

@@ -1,21 +1,21 @@
 # Agent Instructions — First Draft CLI
 
 Start with `docs/README.md` and follow its task routes. Detailed command semantics belong in `docs/commands.md`,
-handled-error recovery in `docs/errors.md`, living release policy in `RELEASING.md`, and dated release observations
-in `docs/release-history.md`. When behavior changes, update its owning document in the same change.
+handled-error recovery in `docs/errors.md`, publication mechanics in `RELEASING.md`, and changes by version in
+`CHANGELOG.md`. When behavior changes, update its owning document in the same change.
 
 - Verify with `npm run check`, which takes about 30 seconds. A fresh checkout needs `npm ci --ignore-scripts` first.
-- To add a command, follow `docs/commands.md#add-a-command`. To change the version, follow the `npm version` step in
-  `RELEASING.md`.
+- To add a command, follow `docs/commands.md#add-a-command`. To change the version, follow
+  `RELEASING.md#prepare-the-version-pull-request`, which includes the `CHANGELOG.md` entry.
 - Sibling repositories: `firstdraft/firstdraft` (private) owns the Service API and Plan format; `firstdraft/skills`
   owns the Skill and plugin packaging.
 - Changes to the accepted API-contract range, accepted Plan formats, command names or flags, handled `error` values,
-  or exit statuses get an independent review through cross-review: `codex-review` from Claude Code, `$claude-review`
-  from Codex.
+  exit statuses, `AGENTS.md`, `CLAUDE.md`, or `RELEASING.md` get an independent review through cross-review:
+  `codex-review` from Claude Code, `$claude-review` from Codex. Pass the service repository's `docs/review-focus.md`
+  as `--focus-file`, fetched with `gh api` when no sibling checkout exists. Put the reviewer, session id, and verdict
+  in the pull request body, and leave the findings out.
 - `firstdraft plan compile` defaults to local output in the current directory. GitHub publication requires
   `--github`; Codespaces is a fallback. Keep Skill callers and recovery instructions aligned with this boundary.
-- A coordinated release needs explicit approval once. Reuse an existing approval for its named scope; do not ask
-  again between repository publication steps. A merge alone does not authorize a release.
-- Publish approved versions directly to `latest`. Reuse successful CI for the exact source and relevant smoke
-  evidence. When changed behavior needs a smoke, use local compilation; Codespaces and Revyl are not release gates.
-  Preserve dated release observations as history.
+- The service repository coordinates releases and owns their approval and smoke policy. One approved coordinated
+  release covers its named CLI steps; do not ask again between them. A merge alone does not authorize a release.
+  `RELEASING.md` covers the publication steps.

CHANGELOG.md

@@ -0,0 +1,11 @@
+# First Draft CLI changelog
+
+This file records changes to the `@firstdraft.com/cli` package, newest first. Each entry starts with a
+`## <version>` heading and says what changed and what callers need to do, if anything.
+
+An entry is written in the pull request that sets its version, so the newest entry can precede publication. Headings
+carry no release status. The `v<version>` tag and npm show whether a version is published.
+
+Entries start with the first version prepared after this file was added, and earlier versions have none. The frozen
+[release history](docs/release-history.md) records releases through 0.4.0. The repository's
+[tags](https://github.com/firstdraft/cli/tags) identify the source of each published version, including later ones.

README.md

@@ -33,21 +33,21 @@ repository owns the exact command and transport behavior between them.
 | Change the CLI                       | [Agent instructions](https://github.com/firstdraft/cli/blob/main/AGENTS.md), then [documentation map](docs/README.md) |
 | Find a command or output contract    | [Command reference](docs/commands.md)                                                                                 |
 | Interpret an error or recover safely | [Errors and recovery](docs/errors.md)                                                                                 |
-| Prepare or publish a package         | [Release runbook](RELEASING.md)                                                                                       |
-| Inspect dated package observations   | [Release history](docs/release-history.md)                                                                            |
+| Prepare or publish a package         | [Release runbook](https://github.com/firstdraft/cli/blob/main/RELEASING.md)                                           |
+| See what changed in a version        | [Changelog](https://github.com/firstdraft/cli/blob/main/CHANGELOG.md)                                                 |
 | Report a vulnerability               | [Security policy](SECURITY.md)                                                                                        |
 
 Run firstdraft --help or a command group's --help for concise terminal syntax.
 
 ## Repository layout
 
-| Path     | Responsibility                                                |
-| -------- | ------------------------------------------------------------- |
-| bin/     | Published executable entrypoint                               |
-| src/     | Commands, API client, local Plan state, and output contracts  |
-| test/    | Command, protocol, recovery, and package tests                |
-| scripts/ | Test runner, package checks, and version sync                 |
-| docs/    | Command, error, release-history, and maintainer documentation |
+| Path     | Responsibility                                                              |
+| -------- | --------------------------------------------------------------------------- |
+| bin/     | Published executable entrypoint                                             |
+| src/     | Commands, API client, local Plan state, and output contracts                |
+| test/    | Command, protocol, recovery, and package tests                              |
+| scripts/ | Test runner, package checks, and version sync                               |
+| docs/    | Documentation map, command and error references, and frozen release history |
 
 ## Development
 
@@ -88,8 +88,8 @@ The published CLI supports Node.js 22 or newer. Direct automation callers can in
 npm install --global @firstdraft.com/cli
 ```
 
-Pin an exact compatible version when a repeatable installation matters; [RELEASING.md](RELEASING.md) owns channel
-and release meaning.
+Pin an exact compatible version when a repeatable installation matters. The
+[changelog](https://github.com/firstdraft/cli/blob/main/CHANGELOG.md) describes each version.
 
 The published package:
 
@@ -100,11 +100,7 @@ The published package:
 - reads Bearer credentials only from the environment; and
 - carries npm provenance linking registry bytes to its GitHub workflow and commit.
 
-Inspect the packed file list whenever a source or documentation path moves. The public documentation graph,
-including the release runbook and dated release history, ships with the package. `AGENTS.md` and the source-only
-`release/compatibility.json` do not.
-
-## Release boundary
-
-Merging source is not package publication. An approved coordinated release publishes directly to `latest`, reusing
-successful CI for the exact source. [RELEASING.md](RELEASING.md) owns the short release and recovery procedure.
+The package includes this README, the documentation map, the command and error references, and the security
+policy. Repository files for maintainers stay out of it: `AGENTS.md`, the release runbook, the changelog, the
+release history, and the source-only `release/compatibility.json`. Inspect the packed file list whenever a source or
+documentation path moves.