Add CI coverage for npm README install and release-surface drift

[luoyuctl]

Background

The repository has npm wrapper documentation, but the package is not published yet. Current release-surface CI checks README, Homebrew, site metadata, and the demo report, while npm/README.md can still drift independently.

Evidence

• Latest release is v0.4.6.
• npm view agenttrace version --json currently returns npm E404.
• origin/master npm/README.md still presents an npm install -g agenttrace block and includes AGENTTRACE_RELEASE_TAG=v0.4.2 node install.js in maintainer checks.
• scripts/ci/check-release-surfaces.sh does not scan npm/README.md for stale versions or unavailable active install paths.
• PR Add growth assets and npm launch docs #156 improves the npm README copy, but the current CI gates do not prevent this class of drift from returning later.

User value

Users and maintainers should not be pointed at an unavailable npm install path or stale release tag when checking package-wrapper docs.

Adoption rationale

Keeping package docs under the same release-surface validation reduces install confusion and keeps public package-channel messaging consistent while npm publication remains undecided.

Suggested scope

• Extend release/docs CI validation so npm/README.md is checked for stale explicit release tags.
• While npm remains unpublished, fail if npm/README.md presents npm install -g agenttrace as an active install method instead of a future/after-publish path.
• Keep the check small and deterministic; do not publish npm or change package registry state.

Non-goals

• Do not run npm publish.
• Do not create tags, releases, Homebrew updates, or external posts.
• Do not make a package-channel decision in this task; Decide npm package publication path before launch docs go live #174 remains the decision issue.

Acceptance criteria

• CI fails if npm/README.md contains a stale explicit version tag such as an old AGENTTRACE_RELEASE_TAG example.
• CI fails if npm is still unpublished and npm/README.md advertises npm install -g agenttrace as an active install path.
• Existing release/docs checks still pass after the npm README validation is added.
• The task remains compatible with PR Add growth assets and npm launch docs #156's cautious npm wording and Decide npm package publication path before launch docs go live #174's unresolved package-channel decision.

Suggested lane

lane/quality

Risk

Low to medium. The check should avoid blocking future npm publication once a maintainer records the package-channel decision and the package is actually published.

Source

Product release-surface audit on 2026-05-10, npm view agenttrace version --json, npm/README.md, and scripts/ci/check-release-surfaces.sh.

[luoyuctl]

Event: Handoff
Actor: Product
Scope: Issue #177
State change: keep lane/quality + status/ready-for-agent
Evidence: npm view agenttrace version --json returns E404 while origin/master npm/README.md can still drift independently from scripts/ci/check-release-surfaces.sh; PR #156 improves the wording, but current CI does not prevent stale npm README release tags or unavailable active install copy from returning later.
Next owner: Quality

Handoff to: Quality
Reason: This is a small repeatable validation gap, not a package-channel decision.
Expected output: extend release/docs CI validation so npm README stale explicit version tags and unavailable active npm install wording are caught while npm remains unpublished.
Acceptance check: existing release/docs checks still pass, and CI fails on stale AGENTTRACE_RELEASE_TAG examples or active npm install -g agenttrace wording before npm publication is explicitly authorized and completed.
Context: package-channel decision remains tracked separately in #174; do not publish npm from this task.

[luoyuctl]

Event: Validation
Actor: Product
Scope: Issue #177 / PR #178
State change: keep lane/quality + status/in-progress
Evidence: PR #178 closes this issue, is non-draft, mergeStateStatus=CLEAN, and GitHub CI Test and build is SUCCESS. Diff updates npm/README.md so npm install is explicitly after publication and AGENTTRACE_RELEASE_TAG matches v0.4.6; it also extends scripts/ci/check-release-surfaces.sh to check npm README release tag drift and inactive npm install wording.
Next owner: Quality / Human

Validation: PR #178 appears to satisfy the Product acceptance criteria for this issue. Product is not merging; Quality/Human should review and merge if the implementation is acceptable.

Acceptance check before merge: ensure the unpublished-npm wording remains future/after-publish only, the release-surface check remains deterministic, and #174 continues to own the actual npm package-channel decision.

[luoyuctl]

Event: Decision
Actor: Product
Scope: Issue #177 / PR #178
State change: status/in-progress -> status/ready-for-review
Evidence: PR #178 closes this issue, is non-draft, mergeStateStatus=CLEAN, and GitHub CI Test and build is SUCCESS. Product validation already found the patch aligned with this issue while leaving #174 as the package-channel decision source of truth.
Next owner: Quality / Human

Decision: Move the issue to ready-for-review to match PR #178. Product will not merge.

Acceptance check before close/merge: Quality/Human confirms the release-surface check remains deterministic, unpublished npm install wording is future/after-publish only, and future npm publication can be supported by updating docs once #174 is resolved.