Release preflight

Release Preflight Skill

Pre-checks, version consistency, and deployment discipline.

The Golden Rule

NEVER publish without running the preflight checklist.

Quick Start

# Full preflight check
node scripts/release-preflight.cjs

# With packaging test
node scripts/release-preflight.cjs

# Skip time-consuming tests
node scripts/release-preflight.cjs

Version Locations (Must Stay Synchronized)

#	Location	Field	Example
1	heir/platforms/vscode-extension/package.json	version	"8.2.1"
2	heir/CHANGELOG.md	Latest heading	## [8.2.1] - 2026-04-22
3	BUILD-MANIFEST.json (if present)	version	"8.2.1"
4	Git tag	Tag name	v8.2.1

Preflight Gates

Gate	Check	Script Flag
0	PAT configured	Always
1	Version sync (all 7 locations)	Always
2	VSIX exists	Always
3	Git clean	Always
4	Git tag available	Always
5	VSCE_PAT available	Always
6	Heir sync drift	Always

Full Release Workflow

# VS Code Extension release
node scripts/release-vscode.cjs

# M365 Agent release
node scripts/release-m365.cjs --validate

Version Bump Only

# 1. Bump
npm version patch --no-git-tag-version

# 2. Get version
$v = (Get-Content package.json | ConvertFrom-Json).version

# 3. Update CHANGELOG, commit, tag, push
git add -A; git commit -m "release: v$v"; git tag "v$v"; git push --tags

Common Mistakes

Mistake	Prevention
Published without version bump	Run preflight first
CHANGELOG not updated	Script checks this
Forgot to push tags	Script does this
Version mismatch	Grep entire repo for old version
PAT 401 error	Refresh PAT before release

Go / No-Go Decision Table (RP3)

After preflight runs, classify each finding to decide whether to proceed:

Finding	Severity	Decision	Rationale
Version mismatch across locations	Block	Fix before publish	Silent version drift = wrong artifact on marketplace
VSIX file missing or wrong version in filename	Block	Rebuild VSIX	Publishing a stale or misnamed artifact is irreversible
Git working tree dirty	Block	Commit or stash	Tagged release must match a clean commit
Git tag already exists for target version	Block	Bump version or delete tag	Duplicate tag = ambiguous release provenance
VSCE_PAT missing or expired	Block	Refresh token	Publish will 401; partial state is worse than no-op
Heir sync drift detected	Warning	Review diff, then decide	Drift may be intentional (master-only changes) or accidental
CHANGELOG entry missing for version	Warning	Add entry, or proceed if patch-only fix	Users and future-you need the audit trail
Test failures in extension	Block	Fix tests	Shipping known-broken code violates trust
Brain-qa score below threshold	Warning	Review findings; proceed if cosmetic-only	Brain health affects heirs on next upgrade
Frontmatter audit failures	Warning	Fix if quick; track as debt if not	New files may lack frontmatter; not a ship-blocker unless systemic

Rule: Any Block finding = hard stop. Fix first, re-run preflight, then proceed. Warning findings require explicit operator acknowledgment — the LLM should list them and ask "proceed despite these warnings?"

Changelog Voice QA Decision Table (RP2)

After preflight passes, review CHANGELOG.md entries for the release version against these voice standards:

Condition	Verdict	Action
Entry uses past tense ("Added", "Fixed", "Removed")	Pass	Standard changelog convention
Entry uses present/future tense ("Adds", "Will fix")	Fail	Rewrite to past tense
Entry describes user-visible impact ("Users can now...")	Pass	Preferred framing
Entry describes internal implementation ("Refactored the parser loop")	Warning	Rewrite to user impact; move internal detail to commit message
Entry uses internal jargon ("brain-qa", "trifecta", "sidecar")	Fail	Replace with user-facing language ("health checks", "skill set", "config")
Entry is a single vague line ("Bug fixes and improvements")	Fail	Expand to specific items
Entry references a PLAN task ID ("FM4", "RP2") only	Fail	Add human-readable description alongside
Entry groups related changes under a category header	Pass	Use: Added, Changed, Fixed, Removed, Security
Breaking change is clearly marked with **BREAKING**	Pass	Required for major bumps
Entry length proportional to change significance	Pass	One-liners for patches, paragraphs for features
Links to related docs/issues included for complex changes	Pass	Helps users understand context
Duplicate entries from cherry-pick or merge	Fail	Deduplicate; keep most descriptive version

Related Scripts

Script	Purpose
scripts/release-preflight.cjs	Pre-release validation
scripts/release-vscode.cjs	Full VS Code release
scripts/release-m365.cjs	M365 agent packaging

Triggers

• "release", "publish", "deploy"
• "preflight", "pre-release check"
• "version bump", "version sync"

---

Scripts: scripts/release-preflight.cjs, scripts/release-vscode.cjs