# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: patch -->

## What Changed

`scripts/check-repo-invariants.mjs` gains invariant #3 (assemble + validate fragments in-memory; throws and validator issues are failures; zero fragments passes). Reuses `assembleNextMd` + `validateGuideContent` — no duplicated rules, no drift. Tests cover all four boundary states (valid, malformed-assembly, missing-section, empty). Task #42.

One change in `writeDecisionAudit` (auto-stage after append) + a regression test (`tests/unit/instar-dev-precommit-audit-staging.test.ts`) pinning that the line is written AND staged even when the gate blocks. Root cause of the task-#62 "decision-audit didn't fire" mystery: it fired; the line sat uncommitted in the building worktree and was deleted with it.

One discipline line appended in `buildAutoloopGoal` (`src/scheduler/MentorAutonomousGuardian.ts`), pinned by the existing deterministic prompt-assembly unit test (2 new assertions). Earned from the 2026-06-05 double parallel-collision and the live #813 eli16-gate hit.

## What to Tell Your User

Nothing user-visible. A release-pipeline failure mode is closed: a malformed release-note fragment can no longer sit silently on the main branch and jam every subsequent release — it now turns CI red immediately on the PR that carries it (or on main itself, loudly attributable).

Nothing user-visible. An internal audit-trail leak is closed: the per-commit build-decision record (tier declared vs suggested) used to evaporate with reclaimed worktrees; it now travels inside the commit it describes.

Nothing user-visible. The autonomous mentor-development loop's built-in working instructions now include two recently-earned ship rules, so future cycles don't rediscover them the hard way.

## Summary of New Capabilities

- The Repo Invariants required CI check now assembles and validates all release-note fragments (`upgrades/next/*.md` + legacy `NEXT.md`) using the same shared validators the publish workflow uses.
- Admin/web merges can no longer bypass fragment validation (the pre-push hook was local-only).

- `scripts/instar-dev-precommit.js` stages `.instar/instar-dev-decisions.jsonl` right after appending the audit line, so the line lands in the same commit it audits.
- A gate-blocked commit leaves the line staged; it rides the retry commit (both evaluations were real).

- The mentor autoloop goal prompt instructs each cycle to run `instar dev:claim-check` before starting a build (parallel-claim collision prevention) and to include the `## ELI16` section in every PR description from the start (the required CI gate).

## Evidence

Reproduced live twice on 2026-06-05 before the fix: two build worktrees (`keychain-per-agent`, then `dev-claim-check`) each held an orphaned, uncommitted `+{"ts":"2026-06-05T08:49:24Z","slug":"keychain-per-agent-master-key",...}` line in the tracked `.instar/instar-dev-decisions.jsonl` after their PR commit — `git status` showed ` M .instar/instar-dev-decisions.jsonl` post-commit, and removing the worktree would have deleted the only copy (one line was hand-rescued before reclaim). After the fix, observed on PR #814's own commit: `git status --short .instar/instar-dev-decisions.jsonl` is CLEAN immediately post-commit and the commit diff contains the gate's own audit line for that very commit — the dogfood proof quoted in the PR body.
