pantheon-opencode 1.5.0-beta.2 → 1.5.0-beta.3

package/scripts/version-check.mjs

@@ -1,151 +1,156 @@
 #!/usr/bin/env node
-/**
- * version-check.mjs — Single source of truth enforcement
- *
- * package.json is the SOURCE OF TRUTH for the Pantheon version.
- * Every other manifest (pyproject.toml, plugin.json, src/plugins/tui/package.json)
- * MUST carry the same version. This script:
- *
- *   - compares every manifest against package.json and prints a divergence
- *     table when they differ (exit code 1),
- *   - with --fix, rewrites each divergent manifest to the package.json version.
- *
- * Mirrors the MANIFEST_FILES list in scripts/versioning.mjs so `apply`
- * and `check` can never drift apart.
- *
- * Usage:
- *   node scripts/version-check.mjs          # verify (exit 0 = in sync)
- *   node scripts/version-check.mjs --fix    # sync all manifests
- */
+/** Fail-closed version and lockfile validation. */
 
-import { readFileSync, writeFileSync } from 'node:fs'
+import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
+import { pathToFileURL } from 'node:url'
+import {
+  LOCK_INVENTORY,
+  VERSION_MANIFEST_INVENTORY,
+  validateInventory,
+  writeInventoryVersion,
+} from './manifest-inventory.mjs'
 
-/** Same set of manifests as versioning.mjs (minus package.json itself). */
-export const MANIFESTS = [
-  { name: 'pyproject.toml', file: 'pyproject.toml', kind: 'toml' },
-  { name: 'plugin.json', file: 'plugin.json', kind: 'json' },
-  {
-    name: 'src/plugins/tui/package.json',
-    file: join('src', 'plugins', 'tui', 'package.json'),
-    kind: 'json',
-  },
-]
-
-function readTomlVersion(filePath) {
-  const text = readFileSync(filePath, 'utf-8')
-  const match = text.match(/^version\s*=\s*"([^"]+)"/m)
-  if (!match) throw new Error(`no version field in ${filePath}`)
-  return match[1]
-}
+// Kept as a public compatibility API. New code must use MANIFEST_INVENTORY.
+export const MANIFESTS = Object.freeze(
+  ['pyproject.toml', 'plugin.json', 'src/plugins/tui/package.json'].map((file) => {
+    const entry = VERSION_MANIFEST_INVENTORY.find((item) => item.file === file)
+    return { name: file, file, kind: entry.kind }
+  }),
+)
 
-function readJsonVersion(filePath) {
-  return JSON.parse(readFileSync(filePath, 'utf-8')).version
+function readLegacyVersion(root, manifest) {
+  const path = join(root, manifest.file)
+  const text = readFileSync(path, 'utf8')
+  if (manifest.kind === 'toml') {
+    const match = text.match(/^version\s*=\s*"([^"]+)"/m)
+    if (!match) throw new Error(`${manifest.file} is missing version`)
+    return match[1]
+  }
+  const data = JSON.parse(text)
+  if (typeof data.version !== 'string') throw new Error(`${manifest.file} is missing version`)
+  return data.version
 }
 
-function readManifestVersion(filePath, kind) {
-  try {
-    return kind === 'toml' ? readTomlVersion(filePath) : readJsonVersion(filePath)
-  } catch {
-    return null
-  }
+function readSourceVersion(root) {
+  const data = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+  return typeof data.version === 'string' ? data.version : null
 }
 
-function writeManifestVersion(filePath, kind, version) {
-  if (kind === 'toml') {
-    const text = readFileSync(filePath, 'utf-8')
-    const updated = text.replace(/^(version\s*=\s*")[^"]+(")/m, `$1${version}$2`)
-    writeFileSync(filePath, updated)
-  } else {
-    const content = JSON.parse(readFileSync(filePath, 'utf-8'))
-    content.version = version
-    writeFileSync(filePath, `${JSON.stringify(content, null, 2)}\n`)
-  }
+function readLockVersion(root, entry) {
+  const data = JSON.parse(readFileSync(join(root, entry.file), 'utf8'))
+  return typeof data.version === 'string' ? data.version : null
 }
 
 /**
- * Compare every manifest version against package.json (source of truth).
- *
- * @param {string} root - repository root containing package.json + manifests
- * @returns {{source: string, manifests: Array<{name: string, version: string|null, ok: boolean}>, ok: boolean}}
- *   - source: version read from package.json
- *   - manifests: per-manifest {name, version (null when unreadable), ok}
- *   - ok: true when every manifest matches the source version
+ * Compare versions while retaining the historical MANIFESTS result shape.
+ * Invalid/missing inventory entries are represented as null so callers can
+ * display a useful table; all CLI mutation paths use validateInventory first.
  */
 export function compareVersions(root) {
-  const source = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')).version
-  const manifests = MANIFESTS.map(({ name, file, kind }) => {
-    const version = readManifestVersion(join(root, file), kind)
-    return { name, version, ok: version === source }
+  let source = null
+  const errors = []
+  try {
+    source = readSourceVersion(root)
+  } catch (error) {
+    errors.push(`package.json: ${error.message}`)
+  }
+  const manifests = MANIFESTS.map((manifest) => {
+    let version = null
+    try {
+      version = readLegacyVersion(root, manifest)
+    } catch (error) {
+      errors.push(`${manifest.file}: ${error.message}`)
+    }
+    return { name: manifest.name, version, ok: version !== null && version === source }
   })
-  return { source, manifests, ok: manifests.every((m) => m.ok) }
+  const locks = LOCK_INVENTORY.map((entry) => {
+    let version = null
+    try {
+      version = readLockVersion(root, entry)
+    } catch (error) {
+      errors.push(`${entry.file}: ${error.message}`)
+    }
+    return { name: entry.file, version, ok: version !== null && version === source }
+  })
+  try {
+    validateInventory(root)
+  } catch (error) {
+    errors.push(error.message)
+  }
+  return {
+    source,
+    manifests,
+    locks,
+    errors: [...new Set(errors)],
+    ok:
+      source !== null &&
+      manifests.every((item) => item.ok) &&
+      locks.every((item) => item.ok) &&
+      errors.length === 0,
+  }
 }
 
 /**
- * Rewrite every divergent manifest to the package.json version.
- *
- * @param {string} root - repository root
- * @returns {number} count of manifests rewritten
+ * Rewrite only version metadata after every inventory entry has passed the
+ * structural preflight. A second validation is performed by the CLI.
  */
 export function syncToSource(root) {
-  const { source, manifests } = compareVersions(root)
-  let changed = 0
-  for (const manifest of manifests) {
-    if (manifest.ok) continue
-    const def = MANIFESTS.find((m) => m.name === manifest.name)
-    writeManifestVersion(join(root, def.file), def.kind, source)
-    changed += 1
-  }
-  return changed
+  const inventory = validateInventory(root, { allowVersionDivergence: true })
+  const source = inventory.sourceVersion
+  const changed = inventory.versions.filter(({ version }) => version !== source).length
+  const lockChanged = inventory.documents.filter(
+    ({ entry, data }) => entry.role === 'lock' && data.version !== source,
+  ).length
+  if (changed || lockChanged) writeInventoryVersion(inventory, source)
+  return changed + lockChanged
 }
 
 function printDivergenceTable(result) {
   const rows = [
     ['manifest', 'version', 'status'],
-    ...result.manifests.map((m) => [m.name, m.version ?? 'MISSING', m.ok ? 'ok' : 'DIVERGENT']),
+    ...result.manifests.map((item) => [
+      item.name,
+      item.version ?? 'MISSING',
+      item.ok ? 'ok' : 'DIVERGENT',
+    ]),
+    ...result.locks.map((item) => [
+      item.name,
+      item.version ?? 'MISSING',
+      item.ok ? 'ok' : 'DIVERGENT',
+    ]),
   ]
-  const widths = rows[0].map((_, i) => Math.max(...rows.map((row) => row[i].length)))
-  console.log(`Source of truth: package.json → v${result.source}\n`)
-  for (const row of rows) {
-    console.log(row.map((cell, i) => cell.padEnd(widths[i])).join('  '))
-  }
+  const widths = rows[0].map((_, index) => Math.max(...rows.map((row) => row[index].length)))
+  console.log(`Source of truth: package.json → v${result.source ?? 'INVALID'}\n`)
+  for (const row of rows)
+    console.log(row.map((cell, index) => cell.padEnd(widths[index])).join('  '))
+  for (const error of result.errors) console.error(`version-check: ${error}`)
   console.log('')
 }
 
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href
 
 if (isDirectRun) {
-  // npm scripts run from the package root, so the working directory is the
-  // repository root to check. Explicit cwd keeps the CLI testable.
   const root = process.cwd()
   const fix = process.argv.includes('--fix')
-  let result
-  try {
-    result = compareVersions(root)
-  } catch (error) {
-    console.error(`version-check: cannot read package.json — ${error.message}`)
-    process.exit(1)
-  }
-
+  const result = compareVersions(root)
   if (result.ok) {
-    console.log(`✓ All manifests match package.json v${result.source}`)
+    console.log(`✓ All manifests match package.json v${result.source}; locks are in sync`)
     process.exit(0)
   }
-
   printDivergenceTable(result)
-  if (fix) {
+  if (!fix) {
+    console.error('version-check: inventory is invalid or out of sync')
+    process.exit(1)
+  }
+  try {
     const changed = syncToSource(root)
     const after = compareVersions(root)
-    if (after.ok) {
-      console.log(`✓ Synced ${changed} manifest(s) to v${after.source}`)
-      process.exit(0)
-    }
-    console.error(
-      `version-check: sync incomplete — ${after.manifests.filter((m) => !m.ok).length} manifest(s) still divergent`,
-    )
+    if (!after.ok) throw new Error(after.errors.join('; ') || 'inventory remains divergent')
+    console.log(`✓ Synced ${changed} metadata entries to v${after.source}`)
+    process.exit(0)
+  } catch (error) {
+    console.error(`version-check: refusing to write: ${error.message}`)
     process.exit(1)
   }
-  console.error('version-check: manifests out of sync (run with --fix to sync)')
-  process.exit(1)
 }

package/scripts/versioning.mjs

@@ -6,45 +6,44 @@
  *   recommend            Analyze commits and suggest next version bump type
  *   apply [type]         Bump manifests + move [Unreleased] → [vX.Y.Z] in CHANGELOG
  *                        type: patch | minor | major | auto (default: auto)
+ *                        --beta: bump the committed beta line instead
+ *   beta                 Alias for `apply --beta`
  *   changelog [ver]      (Internal) Insert a versioned section into CHANGELOG
  *                        Normally called by `apply`; can be run standalone.
  *   status               Show current version, latest tag, and pending bump type
  *
- * Design: the release signal is "package.json version > latest git tag".
- * Developers (or AI agents) call `apply` to bump + update CHANGELOG, then push.
- * The auto-release workflow detects the version bump and creates the release.
- * No version bumping ever happens inside GitHub Actions.
+ * Design: the release signal is "package.json version > latest git tag" for
+ * stable, and "package.json version is a committed X.Y.Z-beta.N" for beta.
+ * Developers (or AI agents) call `apply` (or `apply --beta` / `beta`) to bump
+ * the manifests and promote CHANGELOG.md, then push. The dispatch-only release
+ * workflow reads the committed version and creates the release. No version
+ * bumping ever happens inside GitHub Actions.
  */
 
-import { execSync } from 'node:child_process'
-import { readFileSync, writeFileSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import {
+  commitPreparedUpdates,
+  prepareInventoryVersion,
+  SEMVER_PATTERN,
+  validateInventory,
+} from './manifest-inventory.mjs'
+import { nextBetaVersion } from './release-beta-version.mjs'
 import { collectEntries, groupCommits, parseCommitLine, renderChangelog } from './release-notes.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const ROOT = join(__dirname, '..')
 
-const MANIFEST_FILES = [
-  // 'platform/forge.json' removed in v1.0 — directory no longer exists
-  'pyproject.toml',
-  'package.json',
-  'plugin.json',
-  'src/plugins/tui/package.json',
-]
-
 const CHANGELOG_PATH = join(ROOT, 'CHANGELOG.md')
 
 // ---------------------------------------------------------------------------
 // Git helpers
 // ---------------------------------------------------------------------------
 
-function run(cmd) {
-  try {
-    return execSync(cmd, { cwd: ROOT, encoding: 'utf-8' }).trim()
-  } catch {
-    return ''
-  }
+function runGit(args) {
+  return execFileSync('git', args, { cwd: ROOT, encoding: 'utf8' }).trim()
 }
 
 function getLatestTag() {
@@ -52,12 +51,15 @@ function getLatestTag() {
   // The loose glob `v[0-9]*.[0-9]*.[0-9]*` ALSO matches v1.2.0-beta.9.*
   // (the trailing `*` swallows the -beta suffix), which would poison the
   // version gate — so filter strictly before sorting.
-  const tag = run("git tag -l 'v*' | grep -E '^v[0-9]+\\.[0-9]+\\.[0-9]+$' | sort -V | tail -1")
-  return tag || 'v0.0.0'
+  const tags = runGit(['tag', '-l', 'v*'])
+    .split('\n')
+    .filter((tag) => /^v\d+\.\d+\.\d+$/.test(tag))
+  tags.sort((left, right) => compareStable(left.slice(1), right.slice(1)))
+  return tags.at(-1) || 'v0.0.0'
 }
 
 function getCurrentVersion() {
-  return JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8')).version
+  return validateInventory(ROOT).sourceVersion
 }
 
 // ---------------------------------------------------------------------------
@@ -65,7 +67,10 @@ function getCurrentVersion() {
 // ---------------------------------------------------------------------------
 
 function bumpVersion(version, type) {
-  const [major, minor, patch] = version.split('.').map(Number)
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?$/.exec(version)
+  if (!match) throw new Error(`cannot bump invalid semver: ${version}`)
+  if (!['major', 'minor', 'patch'].includes(type)) throw new Error(`invalid bump type: ${type}`)
+  const [major, minor, patch] = match.slice(1).map(Number)
   switch (type) {
     case 'major':
       return `${major + 1}.0.0`
@@ -76,8 +81,17 @@ function bumpVersion(version, type) {
   }
 }
 
+function compareStable(left, right) {
+  const a = left.split('.').map(Number)
+  const b = right.split('.').map(Number)
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] - b[index]
+  }
+  return 0
+}
+
 function analyzeConventionalCommits(since) {
-  const log = run(`git log ${since}..HEAD --format="%s"`)
+  const log = runGit(['log', `${since}..HEAD`, '--format=%s'])
   if (!log) return 'patch'
   let bump = 'patch'
   for (const msg of log.split('\n').filter(Boolean)) {
@@ -91,27 +105,10 @@ function analyzeConventionalCommits(since) {
 // Manifest updater
 // ---------------------------------------------------------------------------
 
-function updateManifests(newVersion) {
-  for (const file of MANIFEST_FILES) {
-    const path = join(ROOT, file)
-    try {
-      const raw = readFileSync(path, 'utf-8')
-      if (file.endsWith('.toml')) {
-        // TOML: replace version = "X.Y.Z"
-        const updated = raw.replace(/^(version\s*=\s*")[^"]+(")/m, `$1${newVersion}$2`)
-        writeFileSync(path, updated)
-        console.log(`  ✓ ${file} → ${newVersion}`)
-      } else {
-        // JSON
-        const content = JSON.parse(raw)
-        content.version = newVersion
-        writeFileSync(path, `${JSON.stringify(content, null, 2)}\n`)
-        console.log(`  ✓ ${file} → ${newVersion}`)
-      }
-    } catch {
-      console.log(`  ⚠ ${file} not found — skipped`)
-    }
-  }
+function prepareManifests(newVersion) {
+  if (!SEMVER_PATTERN.test(newVersion)) throw new Error(`invalid version: ${newVersion}`)
+  const inventory = validateInventory(ROOT, { allowVersionDivergence: true })
+  return { inventory, updates: prepareInventoryVersion(inventory, newVersion) }
 }
 
 // ---------------------------------------------------------------------------
@@ -181,15 +178,17 @@ function stripEmptySections(body) {
   return keep.join('\n').replace(/\n{3,}/g, '\n\n')
 }
 
-function promoteUnreleased(newVersion, dateStr, notesBody = null) {
+function prepareUnreleased(newVersion, dateStr, notesBody = null) {
+  if (!SEMVER_PATTERN.test(newVersion)) throw new Error(`invalid changelog version: ${newVersion}`)
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) throw new Error(`invalid changelog date: ${dateStr}`)
+  if (notesBody !== null && typeof notesBody !== 'string') {
+    throw new Error('generated release notes must be text')
+  }
   const content = readFileSync(CHANGELOG_PATH, 'utf-8')
 
   const unreleasedHeader = '## [Unreleased]'
   const idx = content.indexOf(unreleasedHeader)
-  if (idx === -1) {
-    console.log('  ⚠ [Unreleased] section not found in CHANGELOG — skipping')
-    return false
-  }
+  if (idx === -1) throw new Error('CHANGELOG.md is missing the [Unreleased] section')
 
   // Find the end of [Unreleased]: next ## header or end of file
   const afterHeader = idx + unreleasedHeader.length
@@ -211,15 +210,10 @@ function promoteUnreleased(newVersion, dateStr, notesBody = null) {
     .map((l) => l.trim())
     .filter((l) => l && !l.startsWith('###') && !l.startsWith('## '))
 
-  if (notesBody === null && realLines.length === 0) {
-    console.log('  ℹ [Unreleased] is empty — CHANGELOG not modified')
-    return false
-  }
+  if (notesBody === null && realLines.length === 0) return { changed: false, content }
 
   if (notesBody !== null && realLines.length > 0) {
-    console.log(
-      '  ⚠ --notes replaces the manual [Unreleased] content — review the diff before committing',
-    )
+    console.log('  --notes replaces the manual [Unreleased] content')
   }
 
   // Strip lines that are just empty subsections (### X or ## 🆕/🐞/⚠️/✅
@@ -239,13 +233,32 @@ function promoteUnreleased(newVersion, dateStr, notesBody = null) {
 
   const updated = `${before + unreleasedHeader + newTemplate}\n\n${newVersionHeader}${writtenBody}${after}`
 
-  writeFileSync(CHANGELOG_PATH, updated)
-  console.log(
-    notesBody !== null
-      ? `  ✓ CHANGELOG: [Unreleased] → [v${newVersion}] (notes generated from commits)`
-      : `  ✓ CHANGELOG: [Unreleased] → [v${newVersion}]`,
-  )
-  return true
+  if (!updated.includes('## [Unreleased]') || !updated.includes(newVersionHeader)) {
+    throw new Error('prepared CHANGELOG.md failed structural validation')
+  }
+  return { changed: true, content: updated, notesGenerated: notesBody !== null }
+}
+
+function contentHasUnreleased() {
+  return readFileSync(CHANGELOG_PATH, 'utf8').includes('## [Unreleased]')
+}
+
+function commitPreparedRelease(manifestPlan, changelogPlan) {
+  const updates = [...manifestPlan.updates]
+  if (changelogPlan.changed) {
+    updates.push({ path: CHANGELOG_PATH, content: changelogPlan.content })
+  }
+  commitPreparedUpdates(updates)
+  for (const document of manifestPlan.inventory.documents) {
+    console.log(`  ✓ ${document.entry.file} → ${manifestPlan.version}`)
+  }
+  if (changelogPlan.changed) {
+    console.log(
+      changelogPlan.notesGenerated
+        ? `  ✓ CHANGELOG: [Unreleased] → [v${manifestPlan.version}] (notes generated from commits)`
+        : `  ✓ CHANGELOG: [Unreleased] → [v${manifestPlan.version}]`,
+    )
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -282,9 +295,31 @@ switch (command) {
     break
   }
 
+  case 'beta':
   case 'apply': {
     const args = process.argv.slice(3)
     const useNotes = args.includes('--notes')
+    const useBeta = command === 'beta' || args.includes('--beta')
+
+    // Beta: advance the committed X.Y.Z-beta.N line and promote the
+    // [Unreleased] CHANGELOG section into [vX.Y.Z-beta.N], exactly like the
+    // stable path. The committed manifest is the single source of truth — no
+    // npm lookup, no git lookup, and no runtime version computation.
+    if (useBeta) {
+      if (!contentHasUnreleased())
+        throw new Error('CHANGELOG.md is missing the [Unreleased] section')
+      const current = getCurrentVersion()
+      const newVersion = nextBetaVersion(current)
+      const date = new Date().toISOString().slice(0, 10)
+      console.log(`Bumping ${current} → ${newVersion} (beta)`)
+      const changelogPlan = prepareUnreleased(newVersion, date)
+      const manifestPlan = prepareManifests(newVersion)
+      commitPreparedRelease({ ...manifestPlan, version: newVersion }, changelogPlan)
+      console.log(`\nDone. Commit the version inventory and CHANGELOG as v${newVersion}.`)
+      console.log(`Tag v${newVersion} will be created by the release workflow after merge to main.`)
+      break
+    }
+
     const type = args.find((a) => !a.startsWith('--')) || 'auto'
     const latestTag = getLatestTag()
     const current = getCurrentVersion()
@@ -298,23 +333,21 @@ switch (command) {
       const since = latestTag === 'v0.0.0' ? null : latestTag
       const raw = collectEntries({ since, draft: since === null })
       const body = renderChangelog(groupCommits(raw.map(parseCommitLine)))
-      if (!body) {
-        console.log('  ⚠ --notes: no groupable commits — manual [Unreleased] content used')
-        return null
-      }
-      console.log(`  ℹ --notes: release notes generated from ${raw.length} commits`)
+      if (!body) return null
+      console.log(`  --notes generated from ${raw.length} commits`)
       return body
     }
 
-    // If package.json is already ahead of the latest tag, someone bumped
-    // without tagging — warn and use the current version as-is. Tags are
-    // workflow-owned, so there is nothing to create here.
+    if (!contentHasUnreleased()) throw new Error('CHANGELOG.md is missing the [Unreleased] section')
     if (current !== latestVer) {
-      console.log(`⚠ package.json (${current}) already ahead of latest tag (${latestTag}).`)
-      console.log(`  Syncing all manifests to ${current} and promoting CHANGELOG.`)
-      updateManifests(current)
+      console.log(
+        `package.json (${current}) is ahead of latest tag (${latestTag}); synchronizing inventory.`,
+      )
       const date = new Date().toISOString().slice(0, 10)
-      promoteUnreleased(current, date, generateNotes())
+      const notesBody = generateNotes()
+      const changelogPlan = prepareUnreleased(current, date, notesBody)
+      const manifestPlan = prepareManifests(current)
+      commitPreparedRelease({ ...manifestPlan, version: current }, changelogPlan)
       console.log(`Tag v${current} will be created by the release workflow after merge to main.`)
       break
     }
@@ -324,13 +357,11 @@ switch (command) {
     const date = new Date().toISOString().slice(0, 10)
 
     console.log(`Bumping ${current} → ${newVersion} (${bumpType})`)
-    updateManifests(newVersion)
-    promoteUnreleased(newVersion, date, generateNotes())
-    console.log(`\nDone. Commit with: git add -A && git commit -m "chore(release): v${newVersion}"`)
-
-    // Tags are owned by the release workflow — never create them locally.
-    // A local tag on a pre-merge commit drifts from the merged main state
-    // (the untagged-v1.2.1 root cause) and would desync the version gate.
+    const notesBody = generateNotes()
+    const changelogPlan = prepareUnreleased(newVersion, date, notesBody)
+    const manifestPlan = prepareManifests(newVersion)
+    commitPreparedRelease({ ...manifestPlan, version: newVersion }, changelogPlan)
+    console.log(`\nDone. Commit the version inventory and CHANGELOG as v${newVersion}.`)
     console.log(`Tag v${newVersion} will be created by the release workflow after merge to main.`)
     break
   }
@@ -339,7 +370,11 @@ switch (command) {
   case 'changelog': {
     const version = arg || getCurrentVersion()
     const date = new Date().toISOString().slice(0, 10)
-    promoteUnreleased(version, date)
+    const changelogPlan = prepareUnreleased(version, date)
+    if (changelogPlan.changed) {
+      commitPreparedUpdates([{ path: CHANGELOG_PATH, content: changelogPlan.content }])
+      console.log(`  ✓ CHANGELOG: [Unreleased] → [v${version}]`)
+    }
     break
   }
 
@@ -353,11 +388,19 @@ Commands:
                        type: patch | minor | major | auto (default: auto)
                        --notes: pre-fill the promoted entry with release
                        notes generated from conventional commits
+                       --beta: advance the committed X.Y.Z-beta.N line and
+                       promote [Unreleased] → [vX.Y.Z-beta.N] in CHANGELOG
+  beta                 Alias for 'apply --beta'
   changelog [version]  Promote [Unreleased] → [vX.Y.Z] without bumping
 
-Release flow:
+Release flow (stable):
   1. node scripts/versioning.mjs apply [minor]
-  2. git add -A && git commit -m "chore(release): vX.Y.Z"
-  3. git push     ← CI passes → auto-release fires because pkg > tag
+  2. Commit the version inventory and CHANGELOG.
+  3. Push after review; CI and the dispatch-only release workflow create the tag.
+
+Release flow (beta):
+  1. node scripts/versioning.mjs apply --beta   (or: node scripts/versioning.mjs beta)
+  2. Commit the version inventory and CHANGELOG.
+  3. Dispatch the release workflow with release_channel=beta.
 `)
 }