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..ba3373f 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: @@ -115,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. 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));