@unbrained/pm-cli 2026.5.4 → 2026.5.6

package/docs/RELEASING.md

@@ -33,8 +33,8 @@ pnpm version:check
 
 ## One-Time Setup
 
-- Add `NPM_TOKEN` as a GitHub Environment or repository secret.
-- Add `SENTRY_AUTH_TOKEN` as an optional GitHub Environment or repository secret when Sentry release creation and sourcemap upload should run. The release workflow skips this step cleanly when the secret is absent.
+- Prefer npm Trusted Publishing for `.github/workflows/release.yml` so GitHub-hosted release jobs can publish with short-lived OIDC credentials. Keep `id-token: write`, `npm publish --access public --provenance`, and the package repository URL aligned with npm's Trusted Publisher configuration. If Trusted Publishing is not configured yet, add `NPM_TOKEN` as a GitHub Environment or repository secret as the fallback publisher credential.
+- Add `SENTRY_AUTH_TOKEN` as an optional GitHub Environment or repository secret when Sentry release creation and sourcemap upload should run. Add `SENTRY_PERSONAL_ADMIN_TOKEN` only when the GitHub-hosted Sentry issue-threshold gate should read unresolved issues; CI-scoped release tokens may not have issue-read scope. The release workflow skips Sentry upload cleanly when `SENTRY_AUTH_TOKEN` is absent and skips the GitHub-hosted issue-threshold gate when `SENTRY_PERSONAL_ADMIN_TOKEN` is absent; local maintainers should still run the token-backed Sentry gate before release.
 - Keep any `release` environment compatible with free GitHub features. This repository is public, so environment secrets and tag/branch deployment rules are compatible with the free GitHub path; do not add paid-only release gates.
 - Ensure `GITHUB_TOKEN` has `contents: write` for GitHub Release creation.
 - Keep `package.json` repository, homepage, and bugs URLs aligned with `https://github.com/unbraind/pm-cli`.
@@ -47,9 +47,12 @@ pnpm version:check
 Policy:
 
 - release only when commits exist after the latest release tag
+- ignore `.agents/pm`-only tracker commits for publish eligibility so post-release evidence and closure updates do not create a package release by themselves
 - release at most once per UTC day by default
 - same-day follow-up release (`YYYY.M.D-N`) is manual-only via `allow_same_day_release=true`
 - release preparation must pass all quality and compatibility gates before commit+tag push
+- external Sentry checks run when a Sentry token is configured; local maintainers can make Sentry and private telemetry mandatory with `--telemetry-mode required`
+- after creating and pushing a new tag, auto-release dispatches `.github/workflows/release.yml` with that tag and waits for the publish workflow to finish, because GitHub does not start normal push/tag workflows from `GITHUB_TOKEN` pushes
 
 Pipeline entrypoint:
 
@@ -82,6 +85,7 @@ Minimum coverage:
 - parent and dependency links
 - comments, notes, learnings, body, reminders, events
 - linked files, docs, and tests
+- json_markdown items with external YAML wrappers before JSON front matter
 - closed issue metadata and history drift checks
 - current-build write mutation and item-count preservation
 
@@ -114,6 +118,7 @@ git push origin v<version>
 `.github/workflows/release.yml` runs on `v*.*.*` tags and handles:
 
 - full-history checkout
+- manual `workflow_dispatch` by tag for automation handoff or recovery when a tag already exists
 - pnpm install with frozen lockfile
 - version policy and tag guard
 - secret scan
@@ -126,7 +131,7 @@ git push origin v<version>
 - npm pack dry run and npx tarball smoke test
 - generated release notes from changelog plus sanitized tracker metadata
 - artifact uploads
-- `npm publish --access public --provenance`
+- `npm publish --access public --provenance`, skipped on retry when the exact version is already present on npm
 - post-publish npm/npx/bunx verification
 - GitHub Release creation
 
@@ -141,16 +146,18 @@ gh run watch <run-id> --exit-status
 
 ```bash
 npm view @unbrained/pm-cli@<version> version dist.integrity dist.unpackedSize --json
-npx --yes @unbrained/pm-cli@<version> --version
-bunx @unbrained/pm-cli@<version> --version
+npx --yes --package @unbrained/pm-cli@<version> -- pm --version
+bunx --bun @unbrained/pm-cli@<version> pm --version
 gh release view v<version> --json tagName,name,isDraft,isPrerelease,url
 ```
 
 The executable remains `pm` even though the npm package is scoped.
 
+Use the npm registry package for maintainer global updates. Do not use `npm install -g https://github.com/unbraind/pm-cli.git` as the normal update path; npm can leave a stale shim while replacing git-sourced global installs. If a workstation is already in that state, run `bash scripts/install.sh --repair` or `npm uninstall -g @unbrained/pm-cli && npm install -g @unbrained/pm-cli@latest`.
+
 ## Failure Handling
 
 - If local gates fail, fix and rerun before tagging.
 - If the tag workflow fails before npm publish, confirm no package was published before moving or replacing a tag.
-- If npm publish succeeds but GitHub Release creation fails, recreate only the GitHub Release after verifying the tag and package.
+- If npm publish succeeds but GitHub Release creation fails, rerun `.github/workflows/release.yml` with `workflow_dispatch` and `tag=v<version>`; the workflow skips duplicate npm publish, reruns public verification, and creates the GitHub Release for the existing tag.
 - Record failure evidence and remediation in the release `pm` item.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.5.4",
+  "version": "2026.5.6",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",

package/scripts/install.ps1

@@ -1,7 +1,8 @@
 param(
   [string]$Version = "latest",
   [string]$Prefix = "",
-  [string]$PackageName = ""
+  [string]$PackageName = "",
+  [switch]$Repair
 )
 
 Set-StrictMode -Version Latest
@@ -62,6 +63,16 @@ if (Use-LiteralInstallSpec $PackageName) {
 } else {
   $installSpec = "$PackageName@$Version"
 }
+
+if ($Repair) {
+  Write-Host "Repairing existing global pm install..."
+  $repairArgs = @("uninstall", "-g", "@unbrained/pm-cli")
+  if ($Prefix -ne "") {
+    $repairArgs += @("--prefix", $Prefix)
+  }
+  & npm @repairArgs *> $null
+}
+
 Write-Host "Installing or updating $installSpec..."
 # --force keeps repeated installer runs idempotent when pm shim already exists.
 $npmArgs = @("install", "-g", "--force", $installSpec)

package/scripts/install.sh

@@ -4,17 +4,19 @@ set -euo pipefail
 PACKAGE_NAME="${PM_CLI_PACKAGE:-@unbrained/pm-cli}"
 TARGET_VERSION="latest"
 PREFIX=""
+REPAIR="false"
 
 usage() {
   cat <<'EOF'
 Install or update @unbrained/pm-cli globally via npm.
 
 Usage:
-  bash scripts/install.sh [--version <tag>] [--prefix <dir>]
+  bash scripts/install.sh [--version <tag>] [--prefix <dir>] [--repair]
 
 Options:
   --version <tag>   Package tag/version to install (default: latest)
   --prefix <dir>    npm global prefix override
+  --repair          Uninstall the registry package first to clear a stale global shim
   -h, --help        Show this help message
 EOF
 }
@@ -68,6 +70,10 @@ while [[ $# -gt 0 ]]; do
       PREFIX="$2"
       shift 2
       ;;
+    --repair)
+      REPAIR="true"
+      shift
+      ;;
     -h|--help)
       usage
       exit 0
@@ -88,6 +94,16 @@ if is_literal_install_spec "$PACKAGE_NAME"; then
 else
   INSTALL_SPEC="${PACKAGE_NAME}@${TARGET_VERSION}"
 fi
+
+if [[ "$REPAIR" == "true" ]]; then
+  REPAIR_CMD=(npm uninstall -g @unbrained/pm-cli)
+  if [[ -n "$PREFIX" ]]; then
+    REPAIR_CMD+=(--prefix "$PREFIX")
+  fi
+  echo "Repairing existing global pm install..."
+  "${REPAIR_CMD[@]}" >/dev/null 2>&1 || true
+fi
+
 # Force is required for idempotent reruns when an existing pm shim already exists.
 INSTALL_CMD=(npm install -g --force "$INSTALL_SPEC")
 if [[ -n "$PREFIX" ]]; then