ci(release): document unified-versioning invariant; make guard per-package if versioning ever diverges

[stackbilt-admin]

The Verify workspace versions match tag step in .github/workflows/release.yml encodes charter's current convention: all packages/*/package.json versions must match the release tag. This works today because charter does synchronized version bumps across all 11 workspace packages.

If charter ever adopts independent per-package versioning (e.g., @stackbilt/cli@1.0.0 while @stackbilt/blast@0.12.5), this guard needs to be reworked to validate each package against its own expected version rather than against a single tag value.

Current code

TAG="${{ github.event.inputs.tag || github.ref_name }}"
EXPECTED="${TAG#v}"
FAIL=0
for p in packages/*/package.json; do
  V=$(node -p "require('./$p').version")
  N=$(node -p "require('./$p').name")
  if [[ "$V" != "$EXPECTED" ]]; then
    echo "::error::$N version $V does not match tag $EXPECTED"
    FAIL=1
  fi
done

Filed so that any future discussion of per-package versioning surfaces the workflow change as a prerequisite rather than a forgotten dependency. Not urgent — unified versioning works today and there's no concrete plan to migrate.

Originally flagged by CodeBeast review of #118.

[stackbilt-admin]

[routine:issue-triage] classified as docs with high confidence

Proposed action (v0.2): draft PR on auto/docs/issue-122 branch

Why this is eligible:

• Issue body explicitly states the fix is documentation-only: "Filed so that any future discussion of per-package versioning surfaces the workflow change as a prerequisite rather than a forgotten dependency."
• The exact code block to annotate is quoted in the issue (TAG=…EXPECTED=…for p in packages/*/package.json loop in .github/workflows/release.yml)
• Issue confirms current behavior is correct and complete: "Not urgent — unified versioning works today and there's no concrete plan to migrate." — meaning the only deliverable is an inline comment, no logic change.

What would be changed:

• .github/workflows/release.yml — add a block comment (≤10 lines) above the Verify workspace versions match tag step documenting the synchronized-versioning assumption and the rework required if per-package versioning is ever adopted

Unverified:

• Preferred comment style for this repo (block # prefix vs. YAML multi-line | comment block)
• Whether the comment should also note the CodeBeast review of ci(release): publish to npm on tag push #118 as the origin signal

---

This is a v0.1 dry-run classification. No PR has been opened. After operator validation, the routine will flip to v0.2 live PR creation. Close with no-auto label if you want this issue excluded from future fires.

---

Generated by Claude Code

[stackbilt-admin]

Implemented local documentation/guard clarification.

Change:

• The npm release job now names the check Verify tag and workspace versions and documents the current invariant directly in the workflow: every packages/*/package.json version must match the release tag.
• Added a note that independent package versioning should replace this with per-package release metadata.
• PUBLISHING.md continues to document synchronized version bumps and now also requires pnpm run publish:check during release validation.

Verification:

• pnpm run publish:check passes against the current package set.