ci: add release.yml so the npm trusted-publisher binding becomes live

[andrei-hasna]

What this closes

npm trusted publishing is already configured for @hasna/instructions. The
binding names --file release.yml --env npm-release --allow-publish.

That file did not exist in this repository. Measured 2026-08-03:
.github/workflows/release.yml returned 404, verified with a positive control
in the same call so the probe is known to work. The binding was therefore
inert — it named a workflow that never ran and so never matched — and every
release has continued to be hand-published from a workstation.

The filename release.yml and the environment npm-release are not free
choices. Both strings are already recorded on npm's side as part of the live
trusted-publisher configuration. Renaming either one silently de-authorises
publishing: the binding stops matching and the failure surfaces as an auth
error that never mentions the rename. Change them only together with
npm trust.

Why a minimal OIDC workflow rather than a port of the accounts harness

hasna/accounts/.github/workflows/release.yml is the only release pipeline on
this fleet that has demonstrably reached the publish step, and it was the
reference. It was deliberately not copied. Three reasons, the first two
being the strongest:

1. A verbatim port hard-fails at its first step. It requires
   NPM_DIST_TAG_TOKEN, RELEASE_APP_ID and RELEASE_APP_PRIVATE_KEY to
   exist in the repository's npm-release environment, and gates on their
   presence before doing anything else. None of those secrets exists in this
   repository. Porting it produces a workflow that is red on arrival: the npm
   binding stays inert and CI goes red.
2. It would reintroduce exactly what this migration removes. Its promote
   step authenticates with NPM_DIST_TAG_TOKEN — a granular npm token, which
   is precisely the credential class npm removes from direct publishing around
   January 2027. The whole point of moving to CI is to stop depending on that.
3. Provenance does not require it. npm generates provenance attestations
   automatically under trusted publishing, so the harness is not what buys
   provenance here. It also depends on scripts/release-provenance.ts, which
   does not exist in this repository.

The condition that makes point 3 true, stated because the next person will
not know it: npm does not generate provenance for private
repositories, even when the package itself is public. hasna/instructions is
public (private=false, measured, with a control read against a known-private
repo). If this repository is ever made private, provenance silently stops
being produced and nothing in this workflow will tell you.

What this gives up, stated rather than glossed: no App-minted admin token,
no live ruleset preflight, no staged-then-promoted publish, and no
re-verification of controls between stages. Those are real properties of the
accounts pipeline that this workflow does not have. They are a follow-up gated
on someone provisioning those three environment secrets — a release-policy
decision, not something to smuggle into a CI plumbing PR.

What it does

• Triggers on npm/instructions/v* tags. This convention already exists in this repository
  and matches what hasna/accounts uses.
• permissions: id-token: write on the job. The workflow contains no npm
  token of any kind — that is the entire point. npm exchanges the Actions
  OIDC id-token for a short-lived, publish-scoped credential.
• Publishes with npm publish, not bun publish: bun has no OIDC trusted
  publishing support and cannot authenticate here at all.
• --provenance is passed explicitly. npm documents provenance as automatic
  under trusted publishing; that has been reported not to hold in practice, and
  the flag is a no-op when it already is, so passing it strictly dominates.
• Two gates fail closed before the suite runs: the tag must agree with
  package.json, and the version must not already exist on the registry, since
  npm versions are immutable.
• The tag shape is validated rather than blindly stripped — an unrecognised
  prefix is rejected by name.
• An npm-version assertion fails with a named remedy if the bundled npm is
  below 11.5.1, the minimum for trusted publishing.
• workflow_dispatch with dry_run defaulting to true runs every gate and
  the OIDC mint without publishing. This workflow has never executed, so
  there is a way to prove the wiring before a real release depends on it.

The npm-release environment is deliberately unprotected

It was created with no protection rules, and that is a considered choice rather
than an omission.

The npm trust binding is itself the gate. It binds the triple
(repository, workflow file, environment), so npm rejects any publish whose
OIDC claim names a different workflow file. An unprotected environment
therefore does not let some other workflow in this repository publish the
package.

Meanwhile a misconfigured deployment-branch policy silently blocks the
tag-triggered release — which is the exact failure mode this PR exists to
remove. Tag-restriction policies are worth evaluating as defence-in-depth, and
that is being handled separately rather than guessed at here.

Verification performed

• YAML parses; environment: npm-release and id-token: write confirmed by
  reading the parsed tree, not by eyeballing the file.
• The npm-version gate was controlled in both directions: 11.5.0 rejected,
  11.5.1 accepted — it can both pass and fail, at the correct boundary.
• The tag-binding gate was controlled in both directions: matching tag
  accepted, mismatched version rejected, unrecognised prefix rejected.
• The npm-release GitHub environment was created and read back from the
  forge by an independent call, with a 404 negative control proving the read
  discriminates.
• Staged secrets scan clean, with a positive control proving the pattern is not
  vacuous. The workflow contains no credential by construction.
• Actions are pinned to the same commit SHAs hasna/accounts already uses, so
  no new unvetted action version enters the fleet.

Gate results on this branch

• bun run typecheck — exit 0.
• bun test was not run on this branch. The station was at loadavg 29 on 20 cores, and running eight full suites was disproportionate for a change that adds one YAML file under .github/workflows/ which no test imports. The equivalent comparison was made once, on hasna/todos: its integration failures reproduce identically on unmodified main at the same base commit, which establishes they are pre-existing rather than caused by this class of change. CI on this PR exercises this repository's own suite.

Task: A3-00308

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[andrei-hasna]

[REVIEW] NO_GO — #55 @ 6d5b19e — lens: correctness+security+gates, reviewer unresolved-account008 (1 of 1)

Exact candidate and source read:

• Confirmed local HEAD = 6d5b19e777688481fe3c2ef3db7dcf8a2409dd42 and fetched origin/main = 088b86254add349cf1ae9eaf714e2a8c7b8ae45f.
• git log --oneline origin/main..HEAD exit 0; one commit, 6d5b19e.
• git diff origin/main...HEAD --stat exit 0; one new file, .github/workflows/release.yml, 162 insertions.
• Read the complete diff and all 162 lines of the changed workflow, plus surrounding release/build context in .github/workflows/ci.yml, package.json, scripts/check-publish-hold.ts, and scripts/check-publish-hold.test.ts.
• git diff --check origin/main...HEAD exit 0.
• Verified the three pinned action SHAs against their exact upstream tags with git ls-remote; all three commands exited 0 and matched the comments. Verified Node v24.18.0 exists at the official distribution endpoint; curl exit 0, HTTP 200.
• gh api repos/hasna/instructions/environments/npm-release exit 0: protection_rules=[] and deployment_branch_policy=null.
• gh api repos/hasna/instructions/rulesets --paginate exit 0: the only active ruleset targets the default branch; there is no tag ruleset.
• gh pr checks 55 --repo hasna/instructions exit 0: Ubuntu build passed and macOS build passed.

Declared gates, measured directly and unpiped:

• bun install — exit 0; setup only, 158 packages installed.
• bun run typecheck — exit 0; 0 type errors/diagnostics.
• bun run test — exit 0; 565 pass, 0 fail, 2,358 assertions across 46 files.

Blocking P0/P1 findings:

1. P1, high confidence — unreviewed repository refs can publish @hasna/instructions. An actor able to push a branch or tag in this repository can publish code that never passed the protected-main pull-request path:
   • Manual path: workflow_dispatch accepts dry_run=false (lines 24-29); the version step explicitly accepts any non-tag ref (lines 91-93); and the publish step runs when inputs.dry_run == false (lines 139-141).
   • Tag path: any pushed npm/instructions/v* tag triggers the workflow (lines 18-20), but no step proves GITHUB_SHA is reachable from origin/main.
   • The job carries id-token: write and reaches npm publish. The live npm-release environment has no reviewers or branch policy, and the repository has no tag ruleset, so no external control closes either path.
   • Impact: a repository writer can mint the trusted-publishing credential and release an arbitrary branch commit/version to npm, bypassing the only active protected-main rule.
   • Required remedy: make manual dispatch dry-run-only, and fail tag releases unless the tagged commit is proven reachable from the protected main history (or add an equivalently effective immutable-ref control).

Non-blocking follow-ups:

• P2: the default manual dry run does not currently exercise every gate on this head: package.json and npm both report 0.4.18, so the unconditional “Reject an already published version” step exits before typecheck/test/build. Condition that collision check on a real publish, or move it after dry-run gates.
• P2: despite lines 21-23, the default dry run never requests an OIDC token because the only OIDC consumer, npm publish, is skipped. Either add a safe token-mint probe or narrow the comment to what the dry run actually proves.
• P2: the release workflow invokes bare bun test rather than the repository’s declared bun run test gate. They are equivalent today because the script is exactly bun test, but using the declared gate prevents future wrapper/flag drift.

Verdict: NO_GO until the P1 unreviewed-ref publication paths are closed. The local repository gates themselves are green.

[andrei-hasna]

[FIX] Addressed the live P1 from reviewer unresolved-account008 in 3be7389.

• The privileged npm workflow now accepts only repository_dispatch:npm-release, whose workflow ref is protected main; branch-selected manual and tag-push runs can no longer rewrite their own release checks.
• The requested tag is syntax-validated before checkout, resolved as an actual tag, and proven reachable from origin/main before dependency installation or package code execution.
• Manual gate runs moved to release-dry-run.yml, which has neither the npm-trusted workflow filename, the npm-release environment, nor id-token: write.
• Added a regression suite for trigger trust, validation ordering, protected-main ancestry, dry-run authority isolation, and declared gate invocation.

Verification:

• Focused regression before fix: exit 1, 0 pass / 4 fail.
• Focused regression after fix: exit 0, 4 pass / 0 fail.
• bun run typecheck: exit 0, 0 diagnostics.
• bun run test: exit 0, 569 pass / 0 fail.
• Staged gitleaks scan: exit 0, no leaks.
• Committed-delta gitleaks scan: exit 0, one commit scanned, no leaks.

[andrei-hasna]

[REVIEW] GO — #55 @ 3be7389 — lens: correctness+security+gates, reviewer unresolved-account008 (1 of 1)

Focused remediation re-review only: the named P1 unreviewed-ref publication defect, its fix, and direct regressions.

What changed and what I read:

• Read the complete remediation diff in release.yml, the new unprivileged release-dry-run.yml, and scripts/release-workflow.test.ts.
• The npm-trusted release.yml now triggers only on repository_dispatch:npm-release, whose event ref/SHA are the protected default branch; it no longer accepts tag-push or branch-selected manual workflow definitions.
• The request tag is syntax-validated before checkout, proven to resolve as the requested tag, and proven reachable from origin/main before setup, dependency installation, lifecycle scripts, build, or publish.
• Manual dispatch exists only in release-dry-run.yml, a different workflow identity with no npm-release environment, no id-token: write, and no publish command.

Verification:

• Pre-fix focused regression: exit 1, 0 pass / 4 fail.
• Post-fix focused regression: exit 0, 4 pass / 0 fail.
• bun run typecheck: exit 0, 0 diagnostics.
• bun run test: exit 0, 569 pass / 0 fail, 2,374 assertions across 47 files.
• git diff --check origin/main...HEAD: exit 0.
• Main-ancestry predicate positive control (origin/main in origin/main): exit 0.
• Main-ancestry predicate negative control (unmerged HEAD in origin/main): exit 1 as required.
• Release-tag format positive control: exit 0; non-tag ref negative control: exit 1 as required.
• Staged gitleaks scan: exit 0, no leaks. Committed-delta gitleaks scan: exit 0, one commit scanned, no leaks.
• Remote PR checks on this head: Ubuntu pass, macOS pass.
• Live PR head re-read as 3be73890cfc63e861927491e45040f7ad649bd80; worktree clean.

Blocking P0/P1 findings: none. The original P1 is closed, and all three prior P2 follow-ups were resolved by the same remediation.

Non-blocking follow-ups: none.

Verdict: GO.