@ciqol/resenv 0.1.0-beta.1 → 0.1.0

package/docs/doppler.md

@@ -1,4 +1,4 @@
-# Doppler references and login
+# Doppler references and CLI authentication
 
 Doppler is resenv's only built-in cloud provider. After Nx or another loader
 populates the environment, resenv fetches referenced values through HTTPS and
@@ -13,40 +13,57 @@ a provider option. `resolve-doppler` and
 
 ## Local setup
 
-From the checkout, build and log in:
+After [installing resenv](../README.md#install) in your application project,
+install the [official Doppler CLI](https://docs.doppler.com/docs/cli) and run
+this from the application's directory:
 
 ```sh
-npm run build
-node dist/bin/resenv.cjs login doppler
+doppler login
 ```
 
-After installing a packed build, the same command is `resenv login doppler`.
-If the references are already loaded into the shell environment, `resenv login`
-infers Doppler without naming it. No cloud references means no login is needed.
-Neither command loads dotenv files; Nx remains responsible for file selection.
-It requests a browser authorization code, opens Doppler's authorization page,
-and waits up to five minutes for you to approve the login. `--no-browser`
-prints the page and code without opening it. Login requires a terminal outside
-CI; application startup never opens a browser or prompts for credentials.
-If login falls back to the Doppler CLI, that CLI handles its own browser prompt.
-
-The native flow follows the protocol observed in Doppler's published
-`@dopplerhq/mcp-server` 1.0.5 package. These login endpoints are not a documented
-third-party OAuth contract. They can change independently of the public API.
-resenv identifies itself with its own version and user agent.
-
-The user token is saved in the OS credential store under service
-`ciqol.envref.doppler`, account `default`. The identifier is retained across
-the resenv rename so existing logins continue to work. Nothing is saved in the repository,
-dotenv files or worktree. The current prototype stores one workplace login per
-OS user; logging in again replaces that saved identity. Each developer logs in
-separately and receives the permissions of their own Doppler account.
-
-Native persistence supports macOS Keychain via `/usr/bin/security` and Linux
-Secret Service via an installed `/usr/bin/secret-tool`. The token is passed to
-the helper through stdin, never through process arguments. resenv does not
-install these tools or fall back to a plaintext credential file. Windows can
-use a supplied `DOPPLER_TOKEN`; native Windows login/storage is not implemented.
+Doppler owns browser authorization, token persistence, login scopes and logout.
+Use `doppler logout` to manage the CLI login. resenv never opens a browser,
+prompts for login, issues or revokes tokens, or reads or writes the OS
+credential store directly. There is no separate resenv login.
+
+Existing Doppler users can reuse their login. resenv asks the CLI for the token
+selected by its current working directory, so Doppler's directory-scoped
+workplace identities continue to apply. See
+[Doppler's scope guide](https://docs.doppler.com/docs/multiple-workplaces).
+`doppler setup` is not required for resenv references: their project and config
+are already explicit in each `doppler://` value. Nx or the caller remains
+responsible for dotenv file loading.
+
+### Platforms and installation locations
+
+The CLI handles its own credential storage on macOS, Linux and Windows. resenv
+does not require `secret-tool`, a separate keyring package or native Node addons.
+It discovers the CLI in these standard locations:
+
+| Platform | Locations, in lookup order |
+| --- | --- |
+| macOS / Linux | `/opt/homebrew/bin/doppler`, `/usr/local/bin/doppler`, `/usr/bin/doppler`, `~/.local/bin/doppler`, `~/bin/doppler` |
+| Windows | `~/AppData/Local/Microsoft/WinGet/Links/doppler.exe`, `~/scoop/apps/doppler/current/doppler.exe` |
+
+Here `~` is the OS user's home directory. Windows paths cover default per-user
+WinGet and Scoop installations. Custom and system-wide Windows installations
+outside these locations need an explicit `DOPPLER_TOKEN`. WSL uses the Linux
+installation and login within WSL. The runtime deliberately ignores the
+application's `PATH` so a repository-local executable cannot replace the
+credential helper.
+
+Windows discovery is covered with injected process tests; a native Windows
+end-to-end run is not yet verified. Automated checks never use a developer's
+Doppler login or OS credential store.
+
+### Migration from resenv-managed login
+
+`resenv login` and `resenv logout` have been removed. Run `doppler login` to
+establish the CLI identity, then start the application normally. Earlier resenv
+credentials stored under service `ciqol.envref.doppler`, account `default`, are
+ignored and are not migrated or deleted automatically. If you used that flow,
+remove the obsolete entry through your OS credential manager and revoke the
+obsolete token in Doppler when it is no longer needed.
 
 ## Declare a reference
 
@@ -73,38 +90,31 @@ For an Nx command target, use `resenv run -- node app.mjs` inside the
 target. Preloading the outer Nx process would run before Nx loads target files.
 resenv does not choose, read or rewrite dotenv files.
 
-## Credentials and CLI fallback
+## Runtime credential lookup
 
 Resolution checks these sources in order:
 
 1. An explicitly supplied `DOPPLER_TOKEN`.
-2. The resenv credential in the OS store.
-3. The current directory's existing Doppler CLI login, retrieved with the
+2. The current directory's existing Doppler CLI login, retrieved with the
    documented `doppler configure get token --plain` operation.
 
-The fallback captures that token internally and still fetches secrets through
-HTTPS. It does not parse the CLI's private config format. It invokes a fixed
-executable with separate arguments and a restricted environment. Current
-executable locations are `/opt/homebrew/bin/doppler`,
-`/usr/local/bin/doppler` and `/usr/bin/doppler`; a repository's `PATH` cannot
-select a different credential helper. Other installations can supply a token.
+resenv captures the token internally and fetches secrets through HTTPS; it does
+not parse the CLI's private config format. The command uses a fixed executable,
+separate arguments, `--no-check-version` and `--no-read-env`, with a restricted
+environment. It inherits the application's working directory to preserve login
+scopes. Lookup has a fifteen-second timeout and a 16 KiB output limit. Captured
+output and helper errors are never forwarded to application logs.
 
-Native login falls back to `doppler login` when the OS store is unavailable or
-the authorization endpoint returns HTTP 404, 405 or 501. To select it directly:
+If the CLI is missing, install it in a supported location and run `doppler login`,
+or supply `DOPPLER_TOKEN`. A failed or empty CLI lookup reports that login is
+required. An explicitly supplied invalid token, malformed CLI token, access
+denial or network failure stops the operation without switching identities or
+starting login.
 
-```sh
-resenv login doppler --cli
-```
-
-An explicit invalid token, access denial, login rejection, timeout or network
-error stops the operation. These failures do not silently switch identities.
-Unset `DOPPLER_TOKEN` before interactive login because it overrides saved logins.
-In CI, supply a suitably scoped token through the runner's credential facility.
-
-`resenv logout doppler` removes only resenv's local credential. It does not
-revoke the remote token, unset an environment variable or log the Doppler CLI
-out. Those other credential sources can still authenticate. Revoke unwanted
-tokens from Doppler's CLI Tokens page.
+In CI, containers and other unattended environments, supply a suitably scoped
+`DOPPLER_TOKEN` through the runner's secret facility. No CLI installation or
+local credential store is needed in that mode. Changing the CLI login affects
+the next application startup; resenv does not keep a persistent token cache.
 
 ## Resolution and security boundaries
 
@@ -126,10 +136,9 @@ tokens from Doppler's CLI Tokens page.
 - Preloads use a child Node process to wait for asynchronous HTTPS while
   retaining `--require` compatibility. It receives only references and an
   explicit credential through stdin, with results returned through a private
-  pipe. No Doppler CLI is required when a native credential is available.
+  pipe. No Doppler CLI is required when `DOPPLER_TOKEN` is supplied.
 - Diagnostics show variable names and error codes, never tokens, provider
-  response bodies or resolved values. Only explicit interactive login displays
-  its temporary human authorization code.
+  response bodies, CLI output or resolved values.
 
 This removes shell evaluation from Doppler lookups. It does not isolate
 untrusted repository code or agents that can access the same user's credential
@@ -139,8 +148,8 @@ to a specific config.
 
 ## Sources
 
-- [Doppler MCP authentication](https://docs.doppler.com/docs/mcp#1-authenticate)
-- [Published MCP package](https://www.npmjs.com/package/@dopplerhq/mcp-server/v/1.0.5)
+- [Doppler CLI installation and authentication](https://docs.doppler.com/docs/cli)
+- [Directory-scoped workplace logins](https://docs.doppler.com/docs/multiple-workplaces)
 - [Retrieve a secret](https://docs.doppler.com/reference/secrets-get)
 - [API authentication](https://docs.doppler.com/reference/api)
 - [Retrieve the CLI token](https://docs.doppler.com/docs/cli#fetch-cli-token-from-your-local-environment)

package/docs/maintainer-handoff.md

@@ -1,112 +1,40 @@
-# Maintainer handoff
+# Maintainer guide
 
-## Start a session
+Start with [AGENTS.md](https://github.com/ciqol/resenv/blob/main/AGENTS.md) for repository policy and
+[CONTRIBUTING.md](../CONTRIBUTING.md) for setup and verification. Work in an
+isolated task worktree on a `titan/*` branch. Authenticate as `titan-ron` for
+[ciqol/resenv](https://github.com/ciqol/resenv); `main` is the default and sole
+release branch.
 
-Open the repository folder as its own Codex project. Use the same checkout for
-local work or create an isolated worktree for a separately authorized task.
-Read [AGENTS.md](https://github.com/ciqol/resenv/blob/beta/AGENTS.md), [CONTRIBUTING.md](../CONTRIBUTING.md) and
-[the release guide](releasing.md). Inspect `git status`, the current branch,
-the push remote and recent commits before changing anything.
+Inspect current Git status, branches, push remote and recent commits before
+editing. Read live GitHub checks, releases and npm metadata before release
+work; old chat messages or check results are not authoritative. Never copy
+credentials between sessions.
 
-The repository is [ciqol/resenv](https://github.com/ciqol/resenv). Authenticate
-GitHub as `titan-ron` using the repository-local credential setup in AGENTS.md.
-`beta` is the sole remote and default branch. Work on a local `titan/*` branch;
-never commit directly on the default branch. The repository stores all source,
-tests, build configuration and operating instructions needed to continue.
-Do not depend on previous chat history or copy credentials between sessions.
-
-## Product contract
-
-- Package: `@ciqol/resenv`; CLI: `resenv`.
-- Node preloads: `--require @ciqol/resenv/resolve` and
-  `--import @ciqol/resenv/resolve`.
-- Public API: `resolve(env = process.env, { replace: false })`. Always return a
-  copy; update the input only with `replace: true`.
-- Let Nx or the caller load dotenv files. Resolve values already in the
-  environment, once before application imports.
-- Doppler is the only cloud provider. Infer it from
-  `doppler://project/config/SECRET_NAME`; that syntax belongs to resenv.
-- Commands require explicit opt-in. Fetched values remain literal, and a
-  failed pass leaves the caller's environment unchanged.
-- Debug selector: `NODE_DEBUG=ciqol:resenv`. Never log secret values, tokens,
-  command text or provider response bodies.
-- Runtime npm dependencies: none. Dotenvx decryption has been removed;
-  `encrypted:` values remain literal.
+| Guide | Maintained information |
+| --- | --- |
+| [README](../README.md) | Application installation, API and CLI usage |
+| [Doppler](doppler.md) | CLI authentication, lookup, migration and platform limits |
+| [Build](build.md) | Module formats, declarations, archive and CI contract |
+| [Dependencies](dependencies.md) | Tool rationale, installation and update policy |
+| [Releasing](releasing.md) | PR approval, main releases and recovery |
+| [Release security](release-security.md) | Dependency audit and release-tool review deadline |
+| [Security](../SECURITY.md) | Trust boundaries and private vulnerability reporting |
 
 ## Code map
 
 | Path | Responsibility |
 | --- | --- |
-| `src/index.ts` | Resolution API and atomic replacement |
+| `src/index.ts` | Resolution API and atomic environment replacement |
 | `src/preload.ts`, `src/resolve*.ts` | Startup integration and shared preload state |
-| `src/doppler/` | Reference parsing, HTTPS, bounded concurrency, credentials and login |
+| `src/doppler/` | References, HTTPS, concurrency and CLI credential lookup |
 | `src/commands.ts` | Explicit shell substitution and process limits |
-| `bin/resenv.ts` | Login, logout and child-process CLI |
-| `rollup.config.mjs`, `scripts/build.mjs` | CJS implementation, shared ESM facades and generated types |
-| `scripts/release-plan.mjs` | Official semantic-release analysis/notes plugins and beta counter |
-| `scripts/publish.mjs` | OIDC staging of the tested archive and post-publication tag recording |
-| `.github/workflows/ci.yml` | Build once, test the archive across runtimes, manually dispatched release |
-
-## Verify changes
-
-Use the exact Node.js version in `.nvmrc` and normal npm lifecycle behavior:
-
-```sh
-nvm use
-npm ci
-npm run audit
-npm run verify
-```
-
-Unit specs live beside source modules and run with Vitest. Process tests live
-in `test/`. Clean-consumer checks exercise CJS, ESM, declarations, CLI and
-preloads against the packed archive. Tests use dummy values and mocked effects;
-do not use a developer's Doppler account or OS credential store as a fixture.
-See CONTRIBUTING for Nx integration checks and benchmarking.
-
-## Recover release state before pushing
-
-Read current state rather than treating a dated handoff as authoritative:
-
-```sh
-gh run list --repo ciqol/resenv --workflow ci.yml --limit 5
-gh release list --repo ciqol/resenv
-npm view @ciqol/resenv versions dist-tags --json
-npm stage list @ciqol/resenv --json
-```
-
-The first intended version is `0.1.0-beta.1` on npm's `beta` tag. The planner
-uses semantic-release's official commit-analysis and notes plugins directly;
-it does not run the full semantic-release engine. Real published release tags
-supply later beta counters. Do not fabricate tags to advance a version.
-
-Publishing is staged: a trusted manual CI dispatch submits the exact archive
-that passed all consumer checks. The `release` environment accepts only `beta`
-and has no GitHub reviewer gate. npm approval with 2FA makes a stage public.
-After public availability and integrity verification, rerun the original
-release job to record its Git tag and GitHub prerelease. Keep `beta` at that
-candidate's commit until this step finishes, unless the maintainer explicitly
-chooses to reject and replace the pending stage. Do not rerun the whole
-workflow to recover an existing stage.
-
-A staged version reserves its version number. To replace an unapproved
-candidate, the maintainer must reject the old stage with npm 2FA before CI
-stages the replacement. Check stage status before retrying an ambiguous result.
-Never publish from a developer machine, add a publishing token, promote a beta
-to `latest`, or delete the whole npm package. The `0.0.0-stage` placeholder must
-remain until a functional beta is public; removing the last published version
-would remove the package and impose npm's publishing cooldown.
-
-## Known limits and follow-ups
-
-- Native Doppler browser login has unit/mock coverage but has not been verified
-  end to end with a fresh account. Linux credential storage has mock coverage;
-  Windows native login/storage is not implemented. Explicit tokens and existing
-  CLI credentials are supported. See [Doppler details](doppler.md).
-- The development release-tool tree has reviewed advisories. Exceptions expire
-  November 9, 2026, and executable guards fail on expiry or drift. Review
-  [release security](release-security.md); never broaden or bypass the policy.
-- This beta has not had an independent security audit. Passing tests or the
-  static maturity checklist does not establish production readiness.
-- Consumer repositories are separate. Keep local links out of their committed
-  package manifests, lockfiles and CI.
+| `bin/resenv.ts` | Child-process CLI |
+| `rollup.config.mjs`, `scripts/build.mjs` | CJS implementation, ESM facades, types and manifest |
+| `release.config.mjs` | Standard semantic-release plugins and main/0.x policy |
+| `scripts/release.mjs` | One-time 0.1.0 bootstrap, then the standard release command |
+| `scripts/verify-release.mjs` | Trusted event, review expiry, 0.x and final package checks |
+| `.github/workflows/ci.yml` | Checks, one compiled build and publication on main merges |
+
+Keep docs focused on current contracts, decisions and procedures. Put per-run
+test results, benchmarks, audit snapshots and session history in PRs or CI.

package/docs/release-security.md

@@ -1,134 +1,64 @@
-# Release-tool security review
-
-Reviewed October 10, 2026. Owner: `titan-ron`. Scope: semantic-release version
-planning in read-only CI. The runtime package has no advisory exceptions.
-
-## Decision and controls
-
-Admit semantic-release 25.0.9, commit-analyzer 13.0.1 and release-notes-generator
-14.1.1 as exact development dependencies for version calculation and notes.
-Use the bounded exceptions in [security-exceptions.json](security-exceptions.json)
-only with the executable controls below. These are engineering risk exceptions,
-not upstream fixes or a clean vulnerability scan. They expire November 9, 2026.
-
-The isolated audit reports 10 high and two moderate affected-package entries.
-Several entries propagate the same underlying finding to their parent packages.
-The final merged installation reports 12 active advisory IDs affecting six distinct packages:
-
-| Package | Reviewed location | Why its affected code cannot execute in the planner |
-| --- | --- | --- |
-| braces | Development dependency of micromatch | Every callable export is replaced by a throwing guard before loading semantic-release. The selected matching calls delegate to picomatch. |
-| brace-expansion | npm's bundled dependency | The unselected npm plugin and its bundled npm module are blocked by a Node resolution hook. |
-| http-cache-semantics | npm's bundled dependency | Same blocked npm module. |
-| ip-address | npm's bundled dependency | Same blocked npm module. |
-| postcss-selector-parser | npm's bundled dependency | Same blocked npm module. |
-| undici | npm's bundled dependency | Same blocked npm module. |
-
-The branch expander calls `micromatch(list, branch.name)`. The analyzer calls
-`micromatch.isMatch(commitField, ruleField)`. Both functions in micromatch 4.0.8
-delegate to picomatch rather than its braces-based parse/expand helpers. Patterns
-are the fixed branch `beta` and the analyzer's reviewed default rules; commit
-fields and remote branch names are matching subjects. Guarding all braces calls
-also prevents a later caller from silently opening the vulnerable path.
-
-Sources: [branch expansion](https://github.com/semantic-release/semantic-release/blob/v25.0.9/lib/branches/expand.js),
-[commit matching](https://github.com/semantic-release/commit-analyzer/blob/v13.0.1/lib/analyze-commit.js),
-[micromatch matching](https://github.com/micromatch/micromatch/blob/4.0.8/index.js),
-[braces advisory](https://github.com/advisories/GHSA-vfj7-8cjw-p6xm).
-
-The guards pin the engine, analyzer, notes generator, micromatch and braces
-versions. Changed versions fail until the control is reviewed. The audit checks
-each advisory URL, exact affected version and development-only lockfile path.
-New findings, runtime occurrences, changed paths and expired reviews fail CI.
-Propagated parent findings do not create additional blanket exemptions.
-`npm audit --omit=dev --audit-level=high` also runs without exceptions.
-
-The planner receives no GitHub write token, npm credential or OIDC permission.
-It reads Git history and actual beta tags locally. The official commit-analysis
-and release-notes plugins are fixed in code; the full semantic-release engine
-is not invoked while beta is the sole branch. An explicit 0.1.0 beta line and
-monotonic counter replace its default 1.0.0 initial version. The publisher does
-not install dependencies or import release tools. It verifies candidate hashes
-and source identity, then stages the tested archive through npm OIDC. Maintainer approval through npm publishes it.
-A rerun verifies registry integrity before recording the computed tag/release
-through GitHub's API. Conventional Commit classification remains upstream.
-
-## Verification
-
-An isolated test blocked direct braces calls and imports of the unselected npm
-and GitHub plugins. Normal and adversarial commit analysis passed with 10,000
-nested brace pairs in subjects and bodies. The planner tests cover
-`0.1.0-beta.1`, unchanged history, and subsequent beta counters using real history in a disposable clone without changing source refs.
-
-An isolated attempt to override npm's bundled vulnerable components did not
-replace their distributed copies. No ineffective override was admitted.
-Standalone patched releases do not establish that the bundled copy is fixed.
-Review and remove these exceptions when the upstream distributions are fixed.
-
-## Dependency admission
-
-- **Need:** automate Conventional Commit analysis and release notes, as selected
-  by the user. Platform APIs do not implement that versioning contract.
-- **Fit:** retain the selected engine rather than switch to release-please or
-  maintain a custom analyzer. Native publication glue preserves the tested
-  archive instead of letting a package-directory plugin repack it.
-- **Health:** registry review recorded monthly downloads of 12,515,497 for the
-  engine, 12,542,138 for the analyzer and 12,802,125 for the notes generator,
-  with three listed maintainers each. Selected release dates are August 5, 2026;
-  January 3, 2025; and May 8, 2026. The older analyzer remains the component
-  required by the current engine. Maintenance evidence is not a security guarantee.
-- **Trust:** the canonical semantic-release repositories match the distributed
-  modules. The isolated installation verified 447 registry signatures and 121
-  provenance attestations; the final merged installation verified 606 signatures
-  and 186 attestations. Registry metadata does not expose individual MFA or
-  independently prove historical ownership continuity; those limits remain.
-- **License:** the three direct artifacts contain MIT license text. The isolated
-  tree's licenses are MIT, ISC, BSD-2-Clause, BSD-3-Clause, Apache-2.0, BlueOak-1.0.0,
-  Python-2.0, Artistic-2.0, CC-BY-3.0, CC0-1.0 and permissive alternative sets.
-  qrcode-terminal's absent SPDX metadata is resolved by its Apache-2.0 LICENSE.
-  Some artifacts express the license in package metadata rather than a separate
-  license file. No reciprocal source-disclosure license was identified. These
-  development modules are excluded from the consumer package.
-- **Capabilities:** filesystem, subprocess and Git access are required for local
-  history analysis. The selected plugin path does not publish, contact npm or
-  post GitHub comments. The isolated tree contains no install lifecycle hooks.
-- **Control:** exact direct versions and the lockfile pin the tree; CODEOWNERS
-  and Dependabot retain ownership and update visibility. The guards and expiring
-  audit policy fail on drift. Removal means deleting the three development
-  dependencies and disabling release planning/publication; local build and
-  consumer verification remain available.
-
-The audit result must remain visible. Do not describe the release-tool tree as
-vulnerability-free, use an audit-wide ignore, or pass it to a privileged job.
-
-## Publishing platform
-
-The publisher uses the npm CLI shipped with the pinned Node.js 24.19.0 runtime
-(npm 11.17.0). That platform CLI also bundles older components affected by
-advisories. npm 12.2.0 was inspected and still distributes affected versions;
-upgrading to it would not remove this risk. The development-only policy does
-not imply that the platform CLI is vulnerability-free.
-
-The staging path uses npm 11.17.0's existing `stage publish` subcommand and
-accepts only the validated archive, with no lifecycle
-scripts in its manifest. It uses a fresh home, configuration and cache, fixes
-the registry to HTTPS npmjs.org, and strips proxy, token and arbitrary npm
-configuration from the child environment. No package-query, login, shell,
-selector or arbitrary URL input is accepted. OIDC is supplied by GitHub for the
-specific repository, workflow and protected environment. Registry and signing
-services remain trusted inputs. This bounds exposure; it is not an upstream
-fix. The publisher checks the policy expiry again when it runs, including on a
-failed-job retry, and rejects platform version drift. Review the platform CLI
-again before November 9 alongside this policy.
-
-## October 12 staging review
-
-The pinned npm platform includes `lib/commands/stage/publish.js`, which extends
-its reviewed publish command and sets `stage: true`. The same fixed tarball,
-registry, OIDC identity and provenance options apply. Approval/rejection remain
-interactive npm operations, outside CI. The publisher validates npm's JSON
-receipt against the candidate's name, version and SHA-512 integrity and records
-only its stage identifier and hashes. It creates no tag while the archive is
-staged or pending registry availability. After approval, rerun the same release
-job: its existing-version path verifies integrity and records the release.
-No dependency version, advisory exception or expiry was broadened.
+# Release-tool security
+
+Maintainer: `titan-ron`. The complete installed tree must pass
+`npm audit --audit-level=moderate`; there are no advisory exceptions. The
+[review deadline](security-exceptions.json) remains **November 9, 2026 at
+00:00 UTC** and is enforced before publication. Do not extend it or suppress
+findings to unblock a release.
+
+Standard semantic-release and the official npm/GitHub plugins replace the
+standalone planner and staging controller. Their dependencies are now installed
+and audited normally. The old peer-omission and module-blocking policy no longer
+applies to tools explicitly selected for this pipeline. No release tool ships
+to package consumers.
+
+## Publishing authority
+
+PR merge is approval. Branch rules require the real CI/CodeQL checks and prevent
+direct pushes, force pushes, deletion and bypass. PRs and manual dispatches
+cannot publish. Only main pushes may enter the `release` environment, with
+contents write and OIDC permissions. There are no npm tokens or additional
+reviewers. The release token is exposed only to the release step, and checkout
+does not persist credentials.
+
+The job consumes compiled output tested by CI. The npm plugin changes release
+metadata and packs it; the verification hook tests the final package. Publishing
+uses the prepared directory, whose manifest has no package lifecycle scripts.
+The source is not rebuilt. The bootstrap publishes its checked tarball directly.
+GitHub issue/PR comments and labels are disabled in the GitHub plugin so it
+needs no issue or pull-request write permission.
+
+## Dependency review
+
+Review actual installed artifacts, including npm's bundled dependencies.
+Overrides are not evidence that bundled files changed: inspect their manifests
+on disk. A failing dependency audit blocks merge and release; it is not a
+non-blocking report. Do not broaden exceptions or silently substitute an
+unreviewed npm version.
+
+### Temporary npm bundle repair
+
+npm 11.21.1 bundles vulnerable `undici` and `ip-address` files that npm overrides
+do not replace. Until an upstream npm release includes the fixes, the reviewed
+root `postinstall` hook replaces those two directories with the exact registry
+packages `undici@6.29.1` and `ip-address@10.7.5`, installed under development-only
+aliases. Their integrity hashes are pinned in the lockfile, which also records
+the repaired bundle versions. This is an actual file replacement, not an audit
+exception or a metadata-only override.
+
+`npm run audit` first compares every installed bundle file with the corresponding
+locked upstream package. Missing, extra or modified files fail the check. The
+repair accepts only the reviewed npm and dependency versions and rejects patch
+packages with runtime dependencies. It does not fetch code or use credentials.
+Registry signatures verify the upstream packages; they do not attest the locally
+repaired npm bundle as an npm-maintained distribution.
+
+Remove the hook, repair script/tests, aliases and repaired lock entries together
+when upgrading to an npm release containing both fixes. Regenerate the lockfile
+and validate a clean install, on-disk versions, audit, signatures and package
+checks before removing the repair. The existing review deadline still applies.
+
+Use pinned versions and the lockfile. Validate normal installs, registry
+signatures/attestations, the full audit and the package tests. See
+[dependencies](dependencies.md) for tool choices. Record dated findings and
+per-run evidence in the PR, not in this document.