Add release-surface guard for npm package metadata

[luoyuctl]

Background

The npm wrapper metadata is a release-facing surface. npm/package.json currently matches engine version v0.4.6, but scripts/ci/check-release-surfaces.sh does not appear to check the package version or metadata drift.

Evidence

• internal/engine/engine.go has Version = "0.4.6".
• npm/package.json currently has "version": "0.4.6".
• scripts/ci/check-release-surfaces.sh checks README/Homebrew/site/npm README release tags, but not npm/package.json version drift.
• Decide npm package publication path before launch docs go live #174 still owns whether npm is published, deferred, or not published; this issue is only about metadata consistency while the wrapper exists in-tree.

User value

If npm publication is authorized later, users should not receive a package whose metadata version or searchable description diverges from the release it wraps.

Adoption rationale

Package metadata is what users and registries see first. Guarding it in CI keeps future package-channel work consistent and reduces release-time manual checks.

Suggested scope

• Extend release-surface validation so npm/package.json version matches internal/engine version.
• Optionally validate that npm package metadata continues to use local-first coding-agent session observability wording and does not claim unavailable package publication state.
• Keep checks deterministic and easy to update if Decide npm package publication path before launch docs go live #174 changes npm publication state.

Non-goals

• Do not publish npm from this task.
• Do not decide npm package-channel policy; Decide npm package publication path before launch docs go live #174 owns that decision.
• Do not rewrite package naming or repository metadata.
• Do not add broad package validation unrelated to release-surface drift.

Acceptance criteria

• CI/release-surface validation fails if npm/package.json version drifts from engine version.
• Existing release/docs checks still pass on current v0.4.6 metadata.
• Decide npm package publication path before launch docs go live #174 remains the source of truth for npm publication authorization.

Suggested lane

lane/quality

Risk

Low. Keep the check narrow so future authorized npm publication can update package metadata intentionally without unrelated blockers.

Source

Product package-surface audit on 2026-05-10.

[luoyuctl]

Event: Handoff
Actor: Product
Scope: Issue #183
State change: keep lane/quality + status/ready-for-agent
Evidence: npm/package.json currently matches engine version v0.4.6, but release-surface validation does not check package metadata drift. #174 remains the package-channel decision source of truth.
Next owner: Quality

Handoff to: Quality
Reason: This is a repeatable release-surface validation gap for an in-tree package wrapper, not a package publication decision.
Expected output: extend CI/release-surface checks so npm package metadata cannot drift from the engine release version.
Acceptance check: validation fails on npm package version drift, passes on current v0.4.6 metadata, and does not publish or authorize npm.

[luoyuctl]

Event: Validation / Decision
Actor: Product
Scope: Issue #183 / PR #184
State change: status/in-progress -> status/ready-for-review
Evidence: PR #184 closes this issue, is non-draft, mergeStateStatus=CLEAN, and GitHub CI Test and build is SUCCESS. The diff extends scripts/ci/check-release-surfaces.sh so npm/package.json version must match the engine version and includes npm/package.json in stale release-surface version scanning.
Next owner: Quality / Human

Validation: PR #184 appears to satisfy the Product acceptance criteria for #183. Product is not merging.

Acceptance check before merge: Quality/Human confirms the guard fails on npm package version drift, passes on current v0.4.6 metadata, and does not publish or authorize npm. #174 remains the package-channel decision source of truth.

[luoyuctl]

Event: Validation / Decision
Actor: Product
Scope: Issue #183 / origin/master after PR #184
State change: status/ready-for-review -> status/auto-merged; issue already closed by merged PR
Evidence: PR #184 was merged at 2026-05-10T14:30:27Z. Post-merge Product validation fetched origin/master at fe0790e, built agenttrace v0.4.6, passed scripts/ci/check-release-surfaces.sh, passed scripts/ci/check-docs-commands.sh, and confirmed npm/package.json version is 0.4.6.
Next owner: none for this issue

Decision: Scope complete. #174 remains open for the actual npm package-channel decision.