[AAASM-3840] 🐛 (release): Fix npm latest dist-tag policy

[Chisanan232]

Target

• Task summary:

  Fix the stale npm latest dist-tag for @agent-assembly/sdk. Pre-releases publish only to channel dist-tags (alpha/beta/rc) and never advance latest, so latest was frozen at an ancient 0.0.1-alpha.3 and a bare npm install @agent-assembly/sdk resolved to it instead of the newest pre-release.

• Task tickets:

  • Task ID: AAASM-3840.
  • Relative task IDs:
    • AAASM-3840.
  • Relative PRs:
    • Sibling AAASM-3841 owns .claude/skills + existing release runbooks (kept out of scope here).

• Key point change (optional):

  release-node.yml gains a latest-management step that runs after the main SDK publish (both all and main-only modes, gated on dry_run). It re-points latest at the highest SemVer version currently on npm across all channels (alpha < beta < rc < GA), so the rule is self-correcting and monotonic — it tracks the newest GA once one exists, tracks the newest pre-release until then, and never regresses to an older build.

  One-time manual ops still required (owner action — needs an npm token, NOT done in this PR): the workflow only advances latest on the next publish, so the currently-stale tag must be corrected once by hand:

  npm dist-tag add @agent-assembly/sdk@<newest> latest   # <newest> = current rc

Effecting Scope

• Action Types:
  • 🔧 Fixing bug
  • 📚 Documentation
• Scopes:
  • 🚀 Building
    • 🤖 CI/CD
  • 📚 Documentation
• Additional description:
  No source/runtime code, package.json, or lockfile touched — strictly the release workflow plus one new doc.

Description

• .github/workflows/release-node.yml: add "Update latest dist-tag to newest published version" step after the main SDK publish; documented policy in a comment block.
• docs/release/npm-dist-tags.md (new): channel-tag table, the latest policy, and the one-time manual correction command.

How to verify: review the new step's SemVer-max logic; on the next real (non-dry-run) publish it will move latest to the highest version on npm. actionlint 1.7.12 passes clean on the workflow.

Closes AAASM-3840

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Chisanan232]

✅ Review — AAASM-3840 (Claude Code)

1. CI: green — 18 pass, 0 fail (build, test 18/20/22/24, napi-build, module-smoke, CodeQL, audit); actionlint clean.
2. Scope vs ticket: complete — root cause confirmed (only channel dist-tags were set; latest froze at the early alpha.3). New publish step re-points latest to the highest SemVer on npm after each non-dry-run publish (alpha<beta<rc<GA → self-correcting, monotonic, GA-tracking), guarded to only change when different and using no untrusted event input. Policy documented in the new docs/release/npm-dist-tags.md.
3. Side effects: none on existing flow — the step is additive (runs post-publish, both modes, skipped on dry-run); existing channel-tag publishing unchanged. The one-time manual npm dist-tag add @agent-assembly/sdk@<rc> latest (needs npm token) is still required and is noted in the PR + doc.

Verdict: approve & merge (then do the one-time manual dist-tag move).

🤖 Generated with Claude Code

[Chisanan232]

✅ Re-review confirmed (Claude Code)

1. CI: re-verified green — 18 pass, 0 fail. 2. Scope (AAASM-3840): complete — release-node.yml advances latest to highest SemVer after each non-dry-run publish + new docs/release/npm-dist-tags.md. 3. Side effects: none on existing flow — additive post-publish step, skipped on dry-run; channel-tag publishing unchanged.
Reminder: one-time manual npm dist-tag add @agent-assembly/sdk@0.0.1-rc.2 latest still needed post-merge. State: MERGEABLE (BLOCKED only on required approval). Ready to merge.

🤖 Generated with Claude Code