@navels/neal 0.3.0 → 0.3.1

package/docs/release.md

@@ -1,8 +1,8 @@
 # Release process
 
-Releases are manual, versioned npm operations. Normal CI only verifies pushes
-and pull requests. The GitHub Actions `Publish` workflow handles publishing and
-runs only through `workflow_dispatch`.
+Releases start from the manual GitHub Actions `Publish` workflow. The workflow
+checks and stages the npm package, waits for a maintainer's npm approval, then
+creates the matching GitHub tag and release.
 
 ## Versioning policy
 
@@ -18,9 +18,9 @@ exit codes, or durable run artifacts require a major version.
 
 Examples:
 
-- Patch: `0.1.1` fixes a defect or compatibility issue without intentionally
+- Patch: `0.3.2` fixes a defect or compatibility issue without intentionally
   changing documented behavior.
-- Minor before `1.0.0`: `0.2.0` adds a feature or meaningful behavior change
+- Minor before `1.0.0`: `0.4.0` adds a feature or meaningful behavior change
   while the public contract is still settling.
 - Major: `1.0.0` establishes the stable public contract. Later breaking
   contract changes require `2.0.0`, `3.0.0`, and so on.
@@ -40,105 +40,86 @@ published CLI package:
 
 An SDK update should land as a normal dependency pull request that updates both
 `package.json` and `pnpm-lock.yaml`, runs normal CI, and records any provider
-compatibility findings. The resulting neal release should match the user-facing
-impact: use a patch release for a compatibility fix that preserves documented
-behavior, a minor release for behavior changes before `1.0.0`, and a major
-release after `1.0.0` if a documented public contract breaks.
+compatibility findings. Match the neal release to the user-facing impact: use a
+patch release for a compatibility fix that preserves documented behavior, a
+minor release for behavior changes before `1.0.0`, and a major release after
+`1.0.0` if a documented public contract breaks.
 
-## Local release readiness
+## Prepare a release
 
-Prepare a release with a normal pull request that changes `package.json.version`
-to the intended exact SemVer version:
+Bump `package.json.version` and add a nonempty `## [<version>]` section to
+`CHANGELOG.md` in a normal release-preparation pull request:
 
 ```sh
 pnpm version <version> --no-git-tag-version
 ```
 
-Run the local release-readiness gates from the repository root:
+Run the release gates from the repository root:
 
 ```sh
 RELEASE_VERSION=<version> RELEASE_DRY_RUN=true pnpm run validate:release
 pnpm typecheck
 pnpm test
+pnpm lint
 pnpm build
 node scripts/verify-package.mjs
 ```
 
-`validate:release` checks that the workflow input version matches
-`package.json.version`, validates required package metadata, checks npm version
-availability, and checks remote `v<version>` tag availability when an `origin`
-remote is configured. Package verification confirms the built CLI and packed
-tarball.
+`validate:release` checks the package version, required metadata, direct SDK
+pins, changelog section, npm version availability, and remote tag availability.
 
-## Manual publish workflow
+## Publish
 
-After the release-preparation pull request is merged and normal CI passes, run
-the `Publish` workflow manually from `main` with:
+After the release-preparation pull request is merged and normal CI passes, open
+**Actions > Publish > Run workflow** on `main`.
 
-- `version`: the exact `package.json.version`, without a leading `v`
-- `dry_run`: `true`
+Run it first with the exact version and `dry_run: true`. This runs every gate
+and `npm publish --dry-run` without changing npm or GitHub.
 
-The workflow is guarded to `refs/heads/main`, uses the `npm-publish`
-environment, grants `contents: read` and `id-token: write`, installs with
-`pnpm install --frozen-lockfile`, and runs these gates before any publish step:
+Run it again with `dry_run: false` after reviewing the dry run. The workflow:
 
-```sh
-RELEASE_VERSION=<version> RELEASE_DRY_RUN=<dry_run> pnpm run validate:release
-pnpm typecheck
-pnpm test
-pnpm build
-node scripts/verify-package.mjs
-```
+1. Runs the same release gates.
+2. Runs `npm stage publish` and writes the stage ID and approval commands to the
+   GitHub job summary.
+3. Waits up to 60 minutes for the package to become public.
+4. Verifies npm's signed provenance against the workflow's repository, path,
+   branch, and exact commit SHA.
+5. Creates `v<version>` at that commit and a GitHub release from the matching
+   changelog section.
 
-Review the dry-run result before any real publish. Run `Publish` again with
-`dry_run: false` only when a release-preparation plan has explicitly authorized
-the real publish.
+Review the stage with `npm stage view <stage-id>` or
+`npm stage download <stage-id>`. Approve it with 2FA using
+`npm stage approve <stage-id>` or the npmjs.com UI. npm won't publish the
+package until that approval happens.
 
-The real-publish path is **staged**: the workflow runs `npm stage publish`,
-which places the version in a staged, not-publicly-available state. A
-maintainer then reviews and approves it with 2FA: `npm stage list`,
-`npm stage view <stage-id>` / `npm stage download <stage-id>`, and
-`npm stage approve <stage-id>` (or the npmjs.com UI). Nothing reaches `latest`
-without that human approval, so a compromised workflow cannot ship directly.
+## Recovery
 
-## First-publish history
+Rerun `Publish` with the same version and `dry_run: false` after a timeout or a
+partial failure. The workflow checks existing state before taking action:
 
-`0.1.0` was published manually on 2026-07-12 with an interactive 2FA publish
-from a maintainer terminal: npm trusted publishing cannot be configured for a
-package that has never been published, so the first publish had to
-authenticate directly. Every release after `0.1.0` goes through the `Publish`
-workflow and the staged flow above.
+- If the npm version isn't public, it stages it and waits for approval.
+- If the npm version is public, it skips staging and verifies its signed
+  provenance against the current workflow commit.
+- If the tag or GitHub release already exists at the expected commit, it keeps
+  it and finishes successfully.
+- If the npm provenance or tag points to another commit, it stops without
+  changing the existing release.
 
-## Trusted publishing setup
-
-The publish workflow relies on trusted publishing/OIDC and intentionally has no
-npm-token fallback. It grants `id-token: write` for OIDC, keeps repository
-contents read-only, uses the `npm-publish` GitHub environment, and runs
-`npm stage publish` only on the real-publish path (staged publishing requires
-npm >= 11.15.0, so the workflow upgrades npm accordingly).
-
-The npm-side configuration for `@navels/neal`:
+If the approval wait times out, approve the existing npm stage before rerunning.
+Do not try to stage the same version a second time.
 
-- Publishing access: **Require two-factor authentication and disallow tokens**.
-  This blocks every traditional token permanently. Trusted publishers are
-  unaffected because they use OIDC, and staged approvals always require a
-  maintainer's 2FA.
-- Trusted publisher: owner/repo `navels/neal`, workflow filename
-  `publish.yml`, environment `npm-publish`, allowed action **`npm stage
-  publish` only** (stage-only, plain `npm publish` is deliberately not
-  granted).
-
-## Release boundaries
+## Trusted publishing setup
 
-The current workflow checks that the remote `v<version>` tag is available, but
-it does not create tags or GitHub releases. Do not promise or perform release
-marker creation as part of the current publish workflow. If tags or GitHub
-releases are needed after a successful publish, add them in a separate plan with
-the required permissions and explicit operator approval.
+The workflow uses npm trusted publishing with no token fallback. The npm trusted
+publisher is configured for owner/repository `navels/neal`, workflow
+`publish.yml`, environment `npm-publish`, and the **`npm stage publish` only**
+permission. Publishing access requires two-factor authentication and disallows
+traditional tokens.
 
-Recovery rule for later real publishes: if `npm publish` succeeds but a later
-release-marker step fails in a separate plan, do not rerun the publish blindly.
-First confirm the npm version exists, then create only the missing marker.
+The workflow grants `id-token: write` for npm's OpenID Connect authentication
+and `contents: write` for the final tag and GitHub release. The `npm-publish`
+environment accepts only `main`. npm's stage-only permission means the workflow
+can't make a package public without a maintainer's 2FA approval.
 
 Official references:
 
@@ -146,5 +127,7 @@ Official references:
   <https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow>
 - npm trusted publishing:
   <https://docs.npmjs.com/trusted-publishers/>
+- npm staged packages:
+  <https://docs.npmjs.com/staged-publishing/>
 - npm trust command:
   <https://docs.npmjs.com/cli/v11/commands/npm-trust/>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navels/neal",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "A source-first multi-agent CLI for planning, executing, reviewing, and resuming scoped code changes.",
   "license": "MIT",
   "publishConfig": {