Real version-bump wrap-step handler (open-queue #3 post-#139)

[Jason-Vaughan]

What

Replaces the last remaining no-op stub in lib/wrap-steps/ — version-bump, sitting unchanged since #139 Chunk 3 — with a real handler that promotes CHANGELOG.md's [Unreleased] section to a dated release and bumps version.json.

Why

version-bump was the final piece of the V2 wrap pipeline still returning a placeholder {ok:true, status:'done'} from the early Chunk-3 scaffolding. After PR #200 populated the prawduct ai-content prompts, this is the cleanest remaining open-queue item before V2 prawduct wraps produce complete output end-to-end. Closes that gap and unblocks future v3.17.0 release cuts being driven through the V2 pipeline rather than manual version.json + CHANGELOG edits.

How

Bump-level precedence

1. options.bumpLevel override (patch | minor | major) — wins outright if in the allowed set
2. BREAKING marker anywhere in [Unreleased] body → major
3. ### Added / ### Changed / ### Removed / ### Deprecated present → minor
4. Otherwise (only ### Fixed / ### Security) → patch

Single-transaction discipline + composite-staged-keys

Handler never writes the filesystem; it stages two entries under composite keys:

context.staged['version-bump:version-json'] = {primingPath, newContent, changed:true, oldVersion, newVersion, bumpLevel}
context.staged['version-bump:changelog']    = {primingPath, newContent, changed:true, oldVersion, newVersion, bumpLevel}

The Chunk-9 commit step's _flushStagedWrites is already duck-typed on {primingPath, newContent, changed} — it iterates Object.entries(staged) and flushes any matching shape, so both composite-keyed entries get written without a dispatch-table edit. This establishes the multi-file write-staging convention for any future step that needs to stage more than one file write.

Commit body line

lib/wrap-steps/commit.js:_buildBodyLines gains a new duck-type matching {oldVersion, newVersion, bumpLevel} — emits - Bumped <old> → <new> (<level>) once per pipeline run (deduped via a local emittedVersionBump flag since both staged entries carry the metadata). Pinned with a dedupe test (both insertion orders).

Never blocks

Per the ADR 0002 step-kind contract ("Optional, never blocks"). Every degraded condition — missing version.json, malformed JSON, non-semver version field, missing CHANGELOG.md, missing [Unreleased] section, empty [Unreleased] body — returns {ok:true, status:'skipped'} with output.reason + output.detail for the wrap drawer to render inline.

Idempotent on re-wrap

After a successful bump, the [Unreleased] body is empty (just the heading + blank line). On the next wrap the handler observes no entries and returns {status:'skipped', output:{reason:'no entries to promote'}} — no double-bump. Pinned with a dedicated test.

Banner emoji NOT auto-injected

> 🛟 (bug-fix) / > 🚀 (feature) leading banners stay a curated operator decision per the project's CHANGELOG convention. The handler promotes [Unreleased] body byte-for-byte under the new dated heading; banner insertion is out of scope and tracked separately in the build plan.

Output for the wrap drawer

output.from, output.to, output.bumpLevel, output.detail (pre-formatted "3.16.2 → 3.17.0 (minor)" string). Matches the existing public/wrap-drawer.js:deriveDetail's version-bump case (if (output.from && output.to) return …) — no drawer-side change required.

Test plan

• 39 net new tests in test/wrap-pipeline.test.js:

  • _parseSemver (5): canonical x.y.z, all invalid forms (no v prefix, no pre-release, partial, non-string).
  • _bumpSemver (5): patch / minor / major arithmetic + reset behavior + invalid input.
  • _parseUnreleased (6): finds + categorizes, stops at next ## [ heading, hasEntries true/false, ok:false on missing, nullish-safe, dedupes duplicate subsections.
  • _decideBumpLevel (6): override wins, unknown-override fallthrough, BREAKING marker, minor-trigger subsections, patch-only path, mixed-subsection vote, default to patch.
  • _promoteUnreleased (4): promote shape pin, no auto-banner injection, no-op when [Unreleased] missing, multi-paragraph + nested-bullet preservation.
  • Handler (13): skip when no project.path, skip when version.json missing, skip when version.json malformed, skip when non-semver, skip when CHANGELOG.md missing, skip when [Unreleased] missing, skip when [Unreleased] empty, happy path stages both writes + populates output, options override wins, BREAKING forces major, idempotent on re-wrap, only Fixed → patch, never-blocks contract sweep.
  • Commit body-line (2): renders Bumped line from staged metadata, deduped across the two staged write entries (both insertion orders).
  • Stub-block sentinel (1): kinds array now empty + sentinel pin so a future stub-introducing chunk has to update the list.

• Full suite: 2324 / 2324 pass on this branch (was 2285 on main post-PR-Populate prawduct ai-content prompts (open-queue #2 post-#139) #200; net +39).

Migration note

This is template-and-handler-only; no schema changes, no template structure changes. Existing prawduct projects pick up the new handler automatically on next TC server restart (no methodology template cache invalidation needed since the step's kind and id are unchanged — only the implementation behind the kind moved from no-op to real). Projects that don't have a CHANGELOG.md or version.json continue to see the step report skipped cleanly; no breaking behavior.

Files touched

• lib/wrap-steps/version-bump.js — replaces no-op stub with real handler
• lib/wrap-steps/commit.js — adds version-bump duck-type to _buildBodyLines
• test/wrap-pipeline.test.js — adds 41 new tests + adjusts 2 existing tests for the stub-→-real transition (Chunk-3 stub-block sentinel + monkey-patch list in the "no-op stubs end-to-end" test)
• docs/adr/0002-wrap-pipeline-contract.md — Status line extension marker
• CHANGELOG.md — [Unreleased] ### Added entry

Out of scope

• Auto-injection of > 🛟 / > 🚀 release banners (curated decision per repo convention).
• GitHub Release creation (gh release create) — separate step per CLAUDE.md "Releases & Versioning".
• Pre-1.0 version handling refinement (TC is at 3.x; documented in handler module docstring).
• End-to-end smoke test on a real wrap session — Chunk 2 of the build plan, post-merge.
• Per-field reconciler for step.prompt (cross-cutting concern shared with PR Populate prawduct ai-content prompts (open-queue #2 post-#139) #200's migration note).

The full build plan lives at .claude/plans/version-bump-handler.md (project-local, gitignored per CLAUDE.md plan convention).