From 8d6086d120c6f4a29ec12f416dd1d3af50c327a8 Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Thu, 1 Oct 2026 17:08:43 -0500 Subject: [PATCH 1/2] Drop release history and duplicated review text The frozen release history covered releases through 0.4.0 and said it no longer described current state. Its current facts already live in RELEASING.md, SECURITY.md and AGENTS.md, the tags and git log keep the rest, and the npm package never shipped it. The last copy is e98b427:docs/release-history.md. The second "Retrieval quality" paragraph in docs/README.md narrated the documentation tests' caps and checks to npm readers. The tests' failure messages say the same when a rule breaks, so the paragraph only added a copy to keep in step with them. CONTRIBUTING.md restated cross-review's own install instructions. Keep the two facts its README lacks, that the tracked settings enable the plugins in a trusted checkout and that linked worktrees inherit that trust, and send readers to the README for the rest. The shared review procedure is unchanged. AGENTS.md now points at CONTRIBUTING.md for the focus-file fetch instead of restating it. --- AGENTS.md | 5 +-- CHANGELOG.md | 5 +-- CONTRIBUTING.md | 18 +-------- README.md | 19 +++++----- docs/README.md | 7 ---- docs/release-history.md | 78 -------------------------------------- test/documentation.test.js | 7 +--- 7 files changed, 16 insertions(+), 123 deletions(-) delete mode 100644 docs/release-history.md diff --git a/AGENTS.md b/AGENTS.md index 08c592c..8e93495 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,9 +13,8 @@ handled-error recovery in `docs/errors.md`, publication mechanics in `RELEASING. - Changes to the accepted API-contract range, accepted Plan formats, command names or flags, handled `error` values, exit statuses, `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, `RELEASING.md`, `.claude/settings.json`, or `.codex/config.toml` 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. + `$claude-review` from Codex. Pass the service repository's `docs/review-focus.md` as `--focus-file` (see + `CONTRIBUTING.md`). 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. - The service repository coordinates releases and owns their approval and smoke policy. One approved coordinated diff --git a/CHANGELOG.md b/CHANGELOG.md index 81479ca..721d179 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,9 +6,8 @@ This file records changes to the `@firstdraft.com/cli` package, newest first. Ea 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` 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. +Entries start with the first version prepared after this file was added, and earlier versions have none. The +repository's [tags](https://github.com/firstdraft/cli/tags) identify the source of each published version. ## 0.8.1 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 914debb..f9db8c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,22 +53,8 @@ reviews from Claude Code, and Claude Code reviews from Codex. Install both and s and `codex login`). In Claude Code, ask for a Codex review or run `/codex-review:codex-review`; in Codex, use `$claude-review`. Neither is a shell command. -- **Claude Code:** the tracked `.claude/settings.json` registers the cross-review marketplace and enables - `codex-review`. It loads once you accept the workspace-trust prompt for the main checkout; linked worktrees use - that trust. A headless `claude -p` run loads it only where you have already trusted the checkout. -- **Codex:** the tracked `.codex/config.toml` declares the marketplace and enables `$claude-review` in a trusted - project. The first trusted session fetches the plugin and the next one loads it; - `codex plugin marketplace upgrade cross-review` fetches it at once. In the Codex desktop app, quit and reopen it - after the first fetch. - -If the tracked configuration does not load a plugin, install it yourself: - -```sh -claude plugin marketplace add raghubetina/cross-review -claude plugin install codex-review@cross-review -codex plugin marketplace add raghubetina/cross-review -codex plugin add claude-review@cross-review -``` +The tracked `.claude/settings.json` and `.codex/config.toml` enable both plugins once you trust the main checkout, +and linked worktrees inherit that trust. The cross-review README covers installing them by hand. To run a review: diff --git a/README.md b/README.md index badfd65..f585b45 100644 --- a/README.md +++ b/README.md @@ -42,13 +42,13 @@ 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/ | Documentation map, command and error references, and frozen release history | +| 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 and command and error references | ## Development @@ -102,6 +102,5 @@ The published package: - carries npm provenance linking registry bytes to its GitHub workflow and commit. 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. +policy. Repository files for maintainers stay out of it: `AGENTS.md`, the release runbook, the changelog, and the +source-only `release/compatibility.json`. Inspect the packed file list whenever a source or documentation path moves. diff --git a/docs/README.md b/docs/README.md index f5007a2..4827eaf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,13 +30,6 @@ evidence for implemented behavior; if they contradict a document, surface the co Start here, then load the one owning document for the task. Follow a cross-link only when the task crosses an authority boundary. Create another page only for a distinct audience, task, or authority. -The documentation tests cap `AGENTS.md` at 2 KiB, the root README at 6 KiB, and this map at 4 KiB. They also -require every public topic to be reachable from this map or the root README. They check relative links, links to -this repository's `main` on GitHub, and their fragments. Outside the changelog and release history, they reject -retired version identities and release-status labels on the current version. They also reject status labels in -changelog headings. The package check verifies that relative links in packaged Markdown resolve inside the package; -packaged pages link other files on GitHub. - ## Work on the repository Development uses Node.js 24.18.0 and npm 11.16.0, pinned in `.tool-versions`. From a fresh checkout: diff --git a/docs/release-history.md b/docs/release-history.md deleted file mode 100644 index 8aa97b4..0000000 --- a/docs/release-history.md +++ /dev/null @@ -1,78 +0,0 @@ -# First Draft CLI release history - -**Status:** Historical, frozen 2026-09-30. - -This page preserves dated release and registry observations from the alpha publications through CLI 0.4.0. It is no -longer updated and does not describe current npm, GitHub, service, or qualification state. Versions prepared after -it was frozen have entries in [CHANGELOG.md](../CHANGELOG.md). [RELEASING.md](../RELEASING.md) describes publication. - -## 0.4.0 local-output release - -- On September 23, 2026 UTC, protected tag `v0.4.0` published CLI `0.4.0` from - `a555f8d39862109b8c28b392c0439470e88f4ba8` directly to `latest` through - [GitHub trusted publishing](https://github.com/firstdraft/cli/actions/runs/35807891432). -- `plan compile` now defaults to current-folder output, equivalent to `--output .`. GitHub Publication requires - `--github`. API compatibility remains `0.4.x`; this is a breaking CLI-default change from `0.3.x`. -- npm SHA-1 is `65b6b960b9029cb8f2352273db9fb551132f2ac9`. Public exact-version installation reported `0.4.0`, and - registry signature and provenance verification passed. `latest` selected `0.4.0`; `next` remained `0.3.0`. -- The packed candidate compiled a reviewed Reading List Plan against service `2bfdf6bf`, materialized 360 files at - the local root, and passed local Rails boot, browser creation, and source-edit refresh. Existing warnings and gaps - remained disclosed. No Codespace, GitHub Publication, native build, or Revyl session was part of this release smoke. -- Plugin `0.4.0` bundles this exact CLI source. Its publication workflow matched all 27 files with the registry CLI. - The [plugin release record](https://github.com/firstdraft/skills/blob/archive/evidence-2026-10-01/evidence/2026-09-22-plugin-0.4.0-release.md) - records the companion package, catalog, and post-publication Drawing Board follow-up. - -## 0.1.0 alpha publications - -- On July 31, 2026, npm rejected the unscoped `firstdraft` name for `v0.1.0-alpha.1` as too similar to the existing - `first-draft` package before creating a registry package. The tag records the first reviewed release candidate and - is immutable; neither its tag nor version may be moved or reused. -- On August 5, 2026, `v0.1.0-alpha.2` became the first organization-scoped publication, - `@firstdraft.com/cli@0.1.0-alpha.2`. -- As observed earlier on August 7, 2026, `0.1.0-alpha.2` was the only published scoped version and both npm's `next` - and `latest` dist-tags identified it. - -## 0.1.0 ordinary release and promotion - -- Later on August 7, 2026, protected tag `v0.1.0` published ordinary version `0.1.0` under `next`, while `latest` - continued to identify `0.1.0-alpha.2`. The ordinary release intentionally superseded the alpha and required the - service's `0.2.x` API contract; the historical prerelease did not define an ordinary compatibility line. -- The first ordinary release established the npm trusted-publisher relationship used by the release workflow. -- On August 12, 2026, the selected bounded CLI `0.1.0` user-journey smoke passed and separate promotion approval was - granted. `latest` was promoted to `0.1.0`; both `next` and `latest` then identified ordinary version `0.1.0`. Full - v14 service qualification remained separate and incomplete. -- Requiring two-factor authentication while disallowing tokens at the package publishing-access layer was not a - `v0.1.0` release prerequisite and was not established by that release evidence. - -The alpha versions remain immutable registry history but, as of the August 12 observation, neither distribution -channel selected them. Protected tag `v0.1.0` and package version `0.1.0` were consumed and immutable. Preparing -source or documentation does not mutate either dist-tag. - -## 0.2.0 candidate publication - -- On August 27, 2026, protected tag `v0.2.0` published ordinary version `0.2.0` under `next`; `latest` remained - `0.1.0`. The candidate established compatibility with API contract `0.3.x` but did not displace the separately - promoted stable release. -- Package version `0.2.0` and protected tag `v0.2.0` are consumed and immutable. A backward-compatible addition to - the `0.2.x` line therefore requires a higher patch version rather than reusing those identities. - -## 0.2.1 candidate publication - -- On August 28, 2026, protected tag `v0.2.1` published ordinary version `0.2.1` under `next`; `latest` remained - `0.1.0`. The patch hardened direct Compilation recovery while preserving the `0.2.x` compatibility line. -- Package version `0.2.1` and protected tag `v0.2.1` are consumed and immutable. As observed on August 29, 2026, - current-directory root-output had integrated to `main` at `4352f64baf673ad93457e8bc84273e9d1d9a9501` (tree - `b43ba6de98e27328e548cc3410ba9f39dfa9fcee`) but was not part of those registry bytes. - -## 0.2.2 publication and registry observation - -- The [npm registry](https://registry.npmjs.org/@firstdraft.com%2fcli) records version `0.2.2` published at - `2026-08-30T04:40:13.459Z`. - [Tag `v0.2.2`](https://github.com/firstdraft/cli/releases/tag/v0.2.2) resolves to - `799a184cb2453ceadf5575f7b46ba975e084f192`. That source implements current-root adoption with the archive at - top-level `design/`. -- On September 18, 2026, a read-only registry check found both `next` and `latest` selecting `0.2.2`. This is an - observation of their selection, not evidence of the time or approval of the earlier promotion. The check ran no - fresh package parity, service, authenticated user-journey, or Codespaces qualification. -- Package version `0.2.2` and protected tag `v0.2.2` are consumed and immutable. The nested `.firstdraft/design` - archive belongs to the unpublished `0.3.0` source candidate; preparing it does not change installed `0.2.2` bytes. diff --git a/test/documentation.test.js b/test/documentation.test.js index 58b89c4..843f22a 100644 --- a/test/documentation.test.js +++ b/test/documentation.test.js @@ -141,12 +141,7 @@ test("living documentation names only current version identities", () => { for (const [file, source] of sources) { const name = path.relative(repository, file); - if ( - name === "CHANGELOG.md" || - name === path.join("docs", "release-history.md") - ) { - continue; - } + if (name === "CHANGELOG.md") continue; findings.push(...staleVersionFindings(name, source, identities)); From 64b04a89e29e38522c8d5b846af24cdaf38b40ed Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Thu, 1 Oct 2026 18:32:03 -0500 Subject: [PATCH 2/2] Name the remaining exceptions list firstdraft deleted docs/owner-shape-exceptions.json once every page fit its size limits, so the shared Maintenance bullet named a file that no longer exists. It now names the one exceptions list left, currencyBaseline in firstdraft/skills. firstdraft, skills and cli carry the same line, as the shared section requires. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f9db8c1..ba3373f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -101,5 +101,5 @@ in all three repositories: `firstdraft/firstdraft`, `firstdraft/skills`, and `fi - Test each line of every `AGENTS.md`: would an agent get a task wrong if the line were gone? If not, delete it. In Claude Code, `/doctor prompt-audit` also suggests lines to cut. -- Shrink each exceptions list, such as `docs/owner-shape-exceptions.json` in `firstdraft/firstdraft`. +- Shrink each exceptions list, such as `currencyBaseline` in `firstdraft/skills`. - Delete any documentation check that caught nothing that tests or review would not have caught.