# Release guide

Publish deliberate, versioned npm releases. GitHub releases use the matching entry from
`CHANGELOG.md`; Pi owns installation and updates. Publishing executes no live model calls.
The repository workflows do not publish on ordinary main-branch pushes.

## Version and compatibility policy

- During 0.x, use a patch for compatible fixes and polish, and a minor for new functionality
  or breaking changes. Label breaking changes and explain migration in the changelog.
- Move to 1.0 when the public tool and configuration contracts are stable. After 1.0,
  use semantic versioning: major for breaking changes, minor for compatible features,
  patch for compatible fixes.
- Tool arguments, permissions/grants, configuration, commands and artifact formats are
  user-facing contracts. A small implementation change can still require a breaking release.
- This pipeline publishes stable versions to npm's `latest` channel. Prerelease versions
  are rejected until a separate channel policy is added.
- Delegated execution requires **stable Pi 1.5.2 or newer**, including newer stable patch,
  minor and major versions. Standard build metadata has equal precedence. **Tested host:
  Pi 1.5.2**; allowing future stable versions is not a tested compatibility guarantee.
  Below-minimum, prerelease, malformed and unknown hosts fail closed at execution boundaries, not extension registration. Root status,
  stop/cleanup and diagnostics remain available if the host can load the module; arbitrary
  ancient SDK module-load compatibility is not promised. Wildcard host peer dependencies
  remain required by Pi's packaging format, not an execution compatibility promise.
- Version 0.2.0 introduces this breaking host restriction during 0.x. Migration from 0.1.x:
  drain active tasks, install stable Pi 1.5.2 or newer, update the extension to 0.2.0 and restart Pi.
  Keep host development dependencies pinned and
  verify SDK/CLI lifecycle, permission, cancellation/drain and native rendering behavior
  before changing the minimum or claiming another tested Pi version.
- Never move a release tag, reuse a published version or overwrite retained user artifacts.

## One-time setup

A repository owner and an npm package owner must complete these steps. They are not performed
by the local setup scripts.

1. Confirm your npm account can publish `@howarewoo/pi-subagents` in the `@howarewoo` scope.
   The old unscoped `pi-extended-subagents@0.1.0` is already published; this is a new npm package.
2. Enable GitHub Actions for this repository. Create a GitHub environment named `npm`.
   Require human approval by `howarewoo`, allow self-approval, and restrict deployment refs
   to release tags (`v*`). Do not run a release until this protection is configured.
   Protect `main` with the two CI matrix checks and restrict creation/deletion of `v*` tags
   to release maintainers using repository rulesets.
3. Bootstrap the package with the first manual npm publish below. A trusted publisher is
   normally configured from an existing package's settings, so do not assume the first
   tag-triggered run can create a new npm package without account setup.
4. In **`@howarewoo/pi-subagents` → Settings → Trusted publishing**, add GitHub Actions with:
   The old package's trusted publisher does not carry over to the new scoped package.

   | Field                | Value          |
   | -------------------- | -------------- |
   | Organization or user | `howarewoo`    |
   | Repository           | `pi-subagents` |
   | Workflow filename    | `release.yml`  |
   | Environment name     | `npm`          |

   Permit direct `npm publish` if npm presents an allowed-actions selector. The workflow uses
   GitHub-hosted runners and `id-token: write`; no `NPM_TOKEN` secret is needed. Use npm
   11.5.1 or newer for OIDC publishing (the release runner uses Node 24).

5. Follow npm's current validation/expiry rules when creating the trusted publisher; create it
   near the next release. After successful OIDC publication, restrict traditional token-based
   publishing and revoke unused automation tokens. Public GitHub/OIDC publication supplies npm
   provenance automatically.

See [npm's trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/) for
current account requirements and troubleshooting. Do not use `npm whoami` to test OIDC: it does
not validate trusted publishing permissions.

The environment, required reviewer/tag restrictions, and repository rulesets are owner
prerequisites, not settings created by this change. Read-only inspection found no configured
environments or rulesets; npm trusted-publisher account configuration remains unverified.
Do not treat the workflow's `environment: npm` declaration as an approval rule: GitHub can
create an unprotected environment when a job references a new name. Confirm these settings
before any tag push or manual workflow dispatch.

## Repository rename cutover

These file changes prepare the rename from `howarewoo/pi-extended-subagents` to
`howarewoo/pi-subagents`; they do not rename the GitHub repository or configure npm.
The npm package remains `@howarewoo/pi-subagents`, and the production entrypoint remains
`src/pi-extended-subagents.ts`. Existing npm installations need no migration.

A repository owner must coordinate the following before the next release:

1. Rename the GitHub repository to `pi-subagents` and ensure the rename changes are on
   `main`. Do not push release tags or dispatch Release between those steps: the workflow
   guard accepts only `howarewoo/pi-subagents`, and `package.json` must identify the actual
   repository for npm publishing. Do not dispatch old release tags whose workflow still
   checks the previous repository name.
2. An npm package owner must inspect **`@howarewoo/pi-subagents` → Settings → Trusted
   publishing** and verify the connection for `howarewoo/pi-subagents`, `release.yml` and
   environment `npm`. If the connection needs changing, follow npm's current procedure
   to replace it and its validation/expiry rules. Do not assume GitHub URL redirects prove
   OIDC authorization; the account binding remains unverified until checked and exercised
   by an intentionally authorized release. Retain the protected GitHub `npm` environment
   and release-tag restrictions.
3. Update local clones after the rename:

   ```sh
   git remote set-url origin https://github.com/howarewoo/pi-subagents.git
   ```

   GitHub redirects the previous web and Git URLs, but do not reuse the old repository
   name: doing so removes those redirects. For Pi Git installations, use the source URL
   actually registered when updating or removing it. If switching to the new URL, let tasks
   drain, remove the old registration, install the new source at the desired version, and
   restart Pi; never load both registrations. Pi's old-source update path is not verified
   by local package checks.

4. For the next deliberate release, use a new version and tag containing these changes.
   Run the normal release gates and verify registry integrity, provenance and the GitHub
   release afterward. Do not republish an existing version just to update its repository
   metadata; previously published versions remain unchanged.

See [GitHub's rename documentation](https://docs.github.com/en/repositories/creating-and-managing-repositories/renaming-a-repository)
and [npm's trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/).
Preparing or merging this PR does not establish the external rename, account setup or a
successful publish.

## Prepare each release

1. Start from current `main`, with no unrelated local changes. Review the changes being released.
2. On a release-preparation branch, update the manifest and lockfile without creating a tag:

   ```sh
   npm version 0.2.0 --no-git-tag-version
   ```

   Choose the actual next version; `0.2.0` includes the breaking minimum-host restriction.
   Preserve existing release tags and historical changelog entries.

3. Add a nonempty `## [0.2.0]` entry to the root changelog, using the selected version. Include
   changes, migrations, Pi compatibility, and relevant permission/lifecycle changes. Do not
   promise verification that has not run. Keep the README's installation and migration examples
   current.
4. Run the local gates:

   ```sh
   npm ci --ignore-scripts
   npm run check
   npm run release:check
   npm run test:package
   ```

   Package smoke testing installs only runtime dependencies, without host peers or lifecycle
   scripts, in a disposable directory. It checks the packed manifest, changelog, license,
   production extension load and tool registration, not live-provider reliability.

5. Submit the version/changelog changes as a human-reviewed release PR and merge it after CI.
   These instructions describe maintainer actions; local checks do not commit or publish.

CI runs all checks and the package smoke test on Node 22.19.0 and Node 24. It uses pinned Pi
1.5.2 development packages, not an implied matrix of all Pi versions.

## First scoped npm publish only

Historical bootstrap for 0.1.1, which is already published. Do not repeat it for 0.2.0;
use the tag-triggered workflow after verifying the owner prerequisites above.

After the scoped-package release PR is merged, check out its exact clean commit and run the local gates
above. Use an npm account with publishing rights and two-factor authentication:

```sh
npm login
release_dir="$(mktemp -d)"
npm pack --pack-destination "$release_dir"
npm run test:package -- "$release_dir/howarewoo-pi-subagents-0.1.1.tgz"
npm publish "$release_dir/howarewoo-pi-subagents-0.1.1.tgz" --access public --ignore-scripts
```

Inspect the result with `npm view @howarewoo/pi-subagents@0.1.1 version dist.integrity`.
Keep the tarball until verified, then remove the temporary directory. This interactive bootstrap
is separate from GitHub OIDC and does not claim GitHub provenance. Configure the trusted publisher
before pushing the release tag. The workflow accepts an already-published version only when its
registry SHA-512 integrity matches the newly verified tarball byte for byte.

## Tag and publish

From the exact merged release commit (replace the example version as needed):

```sh
git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0
```

`release.yml` accepts tag pushes and manual dispatch on an existing `v*` tag, not branch
dispatch. Its three GitHub-hosted jobs run in order:

1. **validation** has only `contents: read`, no OIDC permission or publishing environment.
   It checks main ancestry, tag/manifest/lockfile versions and changelog, installs dependencies
   with `npm ci --ignore-scripts`, runs the existing checks, packs once, and smoke-tests that
   exact tarball. It uploads package/metadata and notes as separate immutable artifacts.
2. **publish** depends on validation and requires the protected `npm` environment approval.
   Only this job has `id-token: write`; it has `contents: read`, never `contents: write`.
   It selects the package artifact by validation's exact artifact ID from the current run.
   Before any registry request, the reviewed checked-out, dependency-free publish helper
   requires regular metadata/tarball files, checks the fixed package name, stable version,
   tag, commit and fixed tarball filename, and recomputes SHA-512 against validation's job
   output. A missing or mismatched download is fatal; download-action digest warnings are
   not the publication gate. It neither installs dependencies nor extracts/executes archive
   content, runs tests, or repacks. `npm publish --ignore-scripts` suppresses lifecycle scripts.
3. **github-release** depends on npm success. It has `contents: write` but no OIDC permission,
   downloads only the selected notes artifact, and creates the GitHub release without checking
   out or executing package code. An existing release remains unchanged.

Releases serialize; a later tag does not cancel an active publish. Artifact retention is seven
days. If artifacts expire, rerun validation and all downstream jobs on the same immutable tag
rather than substituting an artifact from another run. No executable helper comes from the
transferred artifact. Separation limits credential exposure during tests/builds; it does not
prove that a compromised validation job produced trustworthy package bytes. Review the release
commit and approval evidence before authorizing publication.

The artifact behavior follows [GitHub's artifact documentation](https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts).
OIDC still requires the actual npm account setup described above; documentation and job
permissions alone do not prove that account binding exists.

Verify both the npm version/integrity and the GitHub release before announcing it. Test a clean
Pi install, then `/subagent-profiles`, and confirm the documented update path. No tag, registry publish,
trusted-publisher setting or fresh installed-package user walkthrough is performed by local CI checks.

## Recover a partial or bad release

- **Failed before npm publication:** fix the configuration or external prerequisite, then rerun
  the workflow for the same tag. Do not move the tag to a changed commit.
- **npm published, GitHub release failed:** rerun the failed workflow, or dispatch **Release**
  on the same existing tag. It skips npm publication only when that version's integrity exactly
  matches the verified tarball. An existing GitHub release is left unchanged. A different integrity
  or a registry error stops the workflow; do not bypass the check.
- **Published contents are wrong:** prepare a new patch (or appropriate breaking version), with
  clear changelog guidance. Deprecate the affected version with an explanatory npm message if
  needed; do not unpublish as the normal rollback strategy.
- **User rollback:** let tasks finish, explicitly install the last known-good version, then
  restart Pi. For example, `pi install npm:@howarewoo/pi-subagents@0.1.1` if that is the last known-good release.
  Pinning code does not undo incompatible configuration or data changes; follow release-specific
  migration instructions. Reload and shutdown abort/drain active children rather than migrate them.