[bug] Codex whats-new skill loses its release-note asset after a supported install

[sparkling]

Confirmed problem

Brain 4.0.2 exposes the native ruvnet-brain:whats-new Codex skill, but the workflow cannot read its required release notes after a normal supported install with no source checkout.

This is a follow-up to #56, not a recurrence of its command-discovery defect. #56 correctly fixed the 4,000-byte migration skip, added native skills, and made the surviving Console aliases self-contained. The remaining failure is execution-time asset resolution.

Verified on:

• RuvNet Brain 4.0.2, installed and auto-converged through the native Stable Spine
• Codex CLI 0.146.0
• Node 24.14.1
• no ~/Code/ruvnet-brain checkout

The installed skill currently says:

1. Read the installed plugin version from `.codex-plugin/plugin.json` relative to this skill's plugin root.
2. Locate `docs/RELEASE-NOTES-4.0.md` in the current repository, then
   `~/Code/ruvnet-brain/docs/RELEASE-NOTES-4.0.md`.

On a supported install:

• the active Stable Spine generation is ~/.cache/ruvnet-brain/versions/4.0.2/;
• the Codex marketplace source is ~/.cache/ruvnet-brain/codex-marketplace/plugin/;
• Codex's host cache is $CODEX_HOME/plugins/cache/ruvnet-brain/ruvnet-brain/4.0.2/;
• the persistent Console runtime is ${RUVNET_BRAIN_KB:-$HOME/.cache/ruvnet-brain/kb}/.console-runtime/.

None contains docs/RELEASE-NOTES-4.0.md. The npm package does include the file at its package root, but the npx extraction directory is temporary. update-apply.mjs intentionally persists the plugin payload only, and installConsoleRuntime() copies console/, scripts/, plugin/scripts/, one KB helper, bin/install.mjs, and package.json—not docs/RELEASE-NOTES-4.0.md.

The user-visible result is that $ruvnet-brain:whats-new must report that the curated notes are unavailable even though the installed release ships them.

Why the existing proof missed it

tests/integration/codex-skill-discovery.test.mjs exercises Codex's real plugin loader, but asserts only that:

• ruvnet-brain:whats-new appears in debug prompt-input output; and
• migrated Console aliases no longer refer to an absent sibling rvbc.md.

It never runs the whats-new workflow from the installed artifact, removes the source checkout/npx directory, or proves the notes path exists. The published-artifact proof for #56 therefore proves discovery, not runnable release-note grounding.

Expected behavior

A clean supported installation must let both Codex and Claude's What's New workflows read the curated notes for the installed Brain release without:

• a repository checkout;
• a guessed ~/Code path;
• a surviving npx extraction directory; or
• downloading/substituting another Brain version at skill execution time.

If the exact installed release genuinely lacks curated notes, the current honest failure remains appropriate.

Suggested implementation

Use the existing persistent-runtime design introduced for the Console rather than adding another cache or updater:

1. Extend installConsoleRuntime() (or rename it to a general installed-runtime function) to copy docs/RELEASE-NOTES-4.0.md atomically into the persistent runtime, for example:

   ${RUVNET_BRAIN_KB:-$HOME/.cache/ruvnet-brain/kb}/.console-runtime/docs/RELEASE-NOTES-4.0.md

2. Update plugin/skills/whats-new/SKILL.md and the Claude command to resolve that supported path. The persistent bin/install.mjs --whats-new entrypoint may be used instead, provided it reads the same persisted asset and reports a non-zero error when the asset is absent.

3. Keep the notes and active plugin version coherent during Stable Spine updates; do not fetch latest when the installed skill is asked about its own version.

4. Preserve Brain's existing atomic stage/swap behavior and native background updater. No host-specific cache edit should be necessary.

Acceptance criteria

• A clean npm/npx install with no repository checkout persists the curated release notes at a documented stable path.
• After the npx/package source directory is removed, the installed Codex ruvnet-brain:whats-new workflow can read the notes and state the exact active version.
• Claude's corresponding command uses the same installed authority or an equally stable supported path.
• A Stable Spine A→B update atomically replaces both the active plugin generation and the notes it reports, with no mixed-version window presented as ready.
• Missing notes fail honestly and non-zero at the executable boundary; no checkout or ~/Code fallback masks the defect.
• The installed-boundary regression packs the npm artifact, installs/persists the runtime into isolated homes, deletes the source/package directory, and executes the actual What's New entrypoint.
• A mutation that omits the notes from the persistent-runtime copy makes that focused test fail.
• The existing Codex discovery test remains green, proving both visibility and runnable assets rather than either one alone.

Source evidence

• plugin/skills/whats-new/SKILL.md
• tests/integration/codex-skill-discovery.test.mjs
• bin/install.mjs (installConsoleRuntime(), showWhatsNew())
• plugin/scripts/update-apply.mjs
• Codex command migration silently drops rvbc/whats-new and leaves broken Brain Console aliases #56 and commit ac8c9780cb33f341acde3217a4f1ece7cf41d1d6
• 4.0.2 Console runtime follow-up commit 453ae5847e8bbd21b14e175109c2b10788003d82

[stuinfla]

🤖 Automated acknowledgment — received and opened. The maintainer has been paged and this is being worked. The next update here will be a fix, findings, or the maintainer in person.

[stuinfla]

Henrik, thank you for catching the difference between “the skill appears” and “the skill can actually do its job” — a wonderfully annoying distinction.

Fixed and verified in public RuvNet Brain 4.0.4. I downloaded the actual npm tarball, confirmed it contains plugin/docs/RELEASE-NOTES-4.0.md, removed the source-checkout assumption, and executed the installed plugin/scripts/whats-new.mjs; it reported the active 4.0.4 release and rendered the curated notes. The focused installed/A→B/missing-asset suite also passes: 7/7 in tests/integration/whats-new-installed.test.mjs.

Closing this one with gratitude — the release notes can now leave home without needing the repository as a chaperone.

[stuinfla]

Reopening after the independent acceptance review caught one remaining boundary I had not yet proven: the public 4.0.4 artifact must be installed into an isolated real Codex home and invoked through the Codex skill interface after its package/source extraction is gone. The executable and packed-asset tests are green, but the host-level receipt was skipped in CI. That distinction matters, so this stays open until the real door is tested.