VCO Release v3.1.0

• Date: 2026-04-25
• Commit(base): 6d6630b
• Previous public release: v3.0.4
• Previous public release commit: 6c0b418

Highlights

• This is the Phoenix release for the governed Vibe runtime. The public surface is rebuilt around one canonical vibe entry, one public vibe-upgrade entry, and compatibility metadata that no longer leaks retired wrapper names into host-visible command surfaces.
• The host now has a clearer operating contract: natural-language user intent should be interpreted by the host, converted into structured decisions, and then validated by the runtime. This avoids raw prompt keyword drift while keeping the runtime authoritative about stage state, bounded re-entry, and dispatch validity.
• Requirement and plan boundaries are stricter and more honest. vibe is expected to stop at requirement_doc, stop again at xl_plan, and only continue when a later user message authorizes the next governed stage. Continuation context is preserved instead of reducing a complex task to a short approval word.
• Specialist handling is no longer treated as a forced single-skill funnel. Host curation can approve, defer, or reject only surfaced specialists; no-specialist execution remains valid when no relevant skill exists; and stage assistants are kept out of user-facing specialist surfaces when they are only orchestration support.
• Direct current-session specialist execution now has a stronger truth model. Routing, consultation, dispatch, attempted execution, executed units, blocked units, degraded units, and failed units are separated so a routed skill is not confused with work that actually ran.
• TDD evidence no longer pollutes non-code work by default. Document, research, planning, and release tasks can explicitly record not_applicable, while real code tasks still keep the red/green evidence path available when the host or runtime freezes that obligation.
• Windows and host install behavior were hardened across the release train: PowerShell diagnostics are clearer, UTF-8 and non-ASCII path handling is more robust, online configuration keys are hidden from install prompts, and runtime path checks reduce false confidence from stale installs.
• vibe-upgrade remains public as a skill-based upgrade surface. Its job is to update the current host installation from the official upstream main line, not to pin users to a temporary PR branch after that branch has merged.
• The repository release version and Python package metadata are aligned at 3.1.0, so runtime governance, package metadata, release notes, and dist manifests advertise the same release line.

What Changed Since v3.0.4

Entry Surface And Wrapper Cleanup

• Retired public exposure of legacy compatibility wrappers such as vibe-what-do-i-want, vibe-how-do-we-do, and vibe-do-it; these remain compatibility metadata only.
• Unified host-facing wrapper naming so Codex and Claude Code do not maintain separate visible command families for the same stage concepts.
• Preserved vibe-upgrade as the public self-update skill, with its default upstream target staying on the official repository main branch.
• Clarified that bootstrap files such as AGENTS.md are entry surfaces only; canonical proof still requires a real canonical-entry launch and proof artifacts under the launched session root.

Bounded Stage Governance

• Tightened progressive stop behavior so vibe pauses at requirement and plan boundaries rather than silently running through want/how/do-like stages in one assistant turn.
• Hardened bounded re-entry with source-run validation, stable continuation context, and structured host approval payloads.
• Fixed cases where continuation prompts were allowed to drag stale requirement text, workspace memory, or generic review framing into the next stage without enough host-side structure.
• Added protection against missing or malformed local entry-surface config being silently replaced by canonical defaults when the repository has an explicit local surface.

Host-Led Routing And Planning

• Moved the intended routing shape toward user text -> host judgment -> structured decision -> runtime validation.
• Added host phase decomposition so complex tasks can be split into domain phases such as data search, modeling, evaluation, writing, verification, and publication without pretending a single primary skill must own the whole task.
• Added bounded host specialist dispatch curation. The host can reject irrelevant surfaced skills, defer optional ones, or approve relevant ones without inventing unsurfaced specialists.
• Allowed framework-only and no-specialist execution to remain normal. When the router has no suitable expert, the host should still decompose and execute the task instead of forcing noisy specialists into the plan.

Specialist Truth And Delivery Gates

• Recorded current-session specialist handoff state explicitly so direct_current_session_routed does not masquerade as completed specialist work.
• Added sidecar accounting for attempted, executed, degraded, blocked, and failed specialist units.
• Preserved dictionary-backed runtime records in phase metadata paths so hashtable records do not lose fields such as skill_id, native_skill_entrypoint, or rationale during execution annotation.
• Fixed failed specialist outcomes so failed and failing remain failed, not downgraded to generic blocked states.
• Separated stage assistants from user-facing specialist recommendations to reduce the appearance that orchestration support skills were domain experts.

TDD And Artifact Review Discipline

• Reduced false TDD gate pressure on documentation, research, planning, and release work.
• Kept code-task TDD available as an explicit structured decision rather than a rigid keyword side effect.
• Ensured artifact review, document baselines, and code-task TDD evidence remain separate truth layers so one kind of evidence does not block unrelated task types.

Install, Upgrade, And Cross-Host Runtime Parity

• Clarified install docs and runtime path checks for Codex and Claude Code.
• Kept online model/config keys out of install prompts and generated host surfaces.
• Restored public vibe-upgrade host surfaces in skill form rather than relying on command-only wrappers.
• Improved installed-runtime remapping and path validation so the live host install can be tied back to the correct source commit.
• Kept Codex and Claude Code on the same runtime content model to reduce duplicated maintenance surfaces.

Windows Runtime Robustness

• Hardened PowerShell startup diagnostics, shell quoting, and UTF-8 subprocess handling.
• Improved router behavior around Windows path and encoding edge cases.
• Avoided WindowsApps Python alias traps in verification flows by using governed Python resolution and clearer diagnostics.
• Added more route and runtime tests around PowerShell structured decisions, hashtable handling, and Windows path comparisons.

Documentation And Positioning

• Reframed the README around VibeSkills as a governed super-skill / harness model rather than a loose command pack.
• Clarified quick start, install prompts, skill-plane extensibility, and the relationship between runtime governance and host-native skills.
• Added contributor acknowledgement and updated Chinese / English README messaging to match the current public positioning.

Why This Is A Phoenix Release

v3.1.0 is not just a patch train. The runtime was rebuilt from several painful real-world failure modes:

• Asking for one phase accidentally triggered later phases.
• Routed skills appeared in plans even when they were irrelevant.
• A skill could be routed without being materially used.
• Research or writing tasks could be blocked by code-task TDD evidence.
• Continuation could carry stale requirement, memory, or review wording into a new plan.
• Codex and Claude Code could drift because they exposed different wrapper names or install surfaces.

This release turns those failures into explicit contracts. The host gets more responsibility to understand the user and structure the decision; the runtime keeps authority over validation, proof, stage lineage, and completion language.

Validation Notes

• powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\governance\release-cut.ps1 -Version 3.1.0 -Updated 2026-04-25 -Preview -RunGates -> preview succeeded and wrote outputs/governance/preview/release-cut.json.
• powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\governance\release-cut.ps1 -Version 3.1.0 -Updated 2026-04-25 -> release governance files and dist manifests updated.
• powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify\vibe-version-consistency-gate.ps1 -> PASS, 10 assertions.
• powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify\vibe-release-notes-quality-gate.ps1 -> PASS.
• powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify\vibe-version-packaging-gate.ps1 -> PASS, 9 assertions.
• powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify\vibe-dist-manifest-gate.ps1 -> PASS.
• powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify\vibe-release-install-runtime-coherence-gate.ps1 -> PASS.
• powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify\vibe-config-parity-gate.ps1 -> PASS, 45 config pairs matched.
• powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify\vibe-bom-frontmatter-gate.ps1 -> PASS for canonical surfaces, with non-applicable bundled/installed surfaces skipped.
• python -m pytest tests/runtime_neutral/test_runtime_delivery_acceptance.py tests/runtime_neutral/test_structured_bounded_reentry_continuation.py tests/unit/test_canonical_vibe_entry_launcher.py -q -> 107 passed.
• python -m pytest tests/runtime_neutral/test_governed_runtime_bridge.py tests/runtime_neutral/test_l_xl_native_execution_topology.py::NativeExecutionTopologyTests::test_public_vibe_defaults_to_requirement_confirmation_boundary -q -> 17 passed.
• GitHub Actions on the merged main release commit a9914d8 passed: gates completed in 1m20s and python-validation completed in 3m31s.

Migration Notes

• Hosts should use only vibe and vibe-upgrade as public Vibe entry skills. Legacy stage names should be treated as compatibility metadata, not visible commands.
• Operators should expect vibe to pause at requirement and plan boundaries. This is intentional; it prevents accidental full-pipeline execution from a single ambiguous instruction.
• If no relevant specialist exists, execution should continue host-led under governed vibe rather than forcing unrelated skills into the plan.
• Release, documentation, and research tasks should not be blocked by code-task TDD unless a structured host or runtime decision explicitly marks the task as code-TDD-required.
• Upgrade flows should pull from the official upstream main release line after merge; temporary PR branches are not long-lived upgrade targets.

Claude Code vibe-upgrade routing inclusion

• The v3.1.0 release package now includes PR #211, which makes vibe-upgrade a hard upgrade skill surface instead of a normal staged vibe routing wrapper.
• The upgrade backend can start from an installed runtime root and prepare the official default-branch source checkout when no git checkout is present.
• This prevents Claude Code from routing /vibe-upgrade back through requirement_doc, TDD, or unrelated specialist dispatch before running the shared upgrade backend.