instar 1.3.152 → 1.3.153

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.152",
+  "version": "1.3.153",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/assemble-next-md.mjs

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+/**
+ * assemble-next-md — fold per-PR release-note FRAGMENTS into a single NEXT.md.
+ *
+ * ── Why this exists ───────────────────────────────────────────────────
+ * The release pipeline consumes a single shared `upgrades/NEXT.md` per merge.
+ * With many agents merging concurrently, EVERY PR rewrote that one file, so
+ * every PR collided on it within minutes — the release notes became an
+ * un-landable hot file. The fix is per-PR FRAGMENTS: each PR ships its note as
+ * `upgrades/next/<slug>.md`, touching a distinct file, so two PRs never
+ * collide. This script concatenates the fragments into `upgrades/NEXT.md`
+ * BEFORE the existing publish pipeline runs, leaving everything downstream
+ * unchanged.
+ *
+ * ── What it does ──────────────────────────────────────────────────────
+ *   1. Reads every `upgrades/next/*.md` fragment (deterministic filename sort).
+ *   2. Folds in a legacy `upgrades/NEXT.md` too, if one exists (backward compat).
+ *   3. Merges by section: the result has ONE "## What Changed", ONE
+ *      "## Summary of New Capabilities", ONE "## What to Tell Your User", ONE
+ *      "## Evidence" — each section is the concatenation of that section across
+ *      all inputs (in source order). Any non-canonical H2 section is preserved
+ *      and appended after the canonical ones (also concatenated by title).
+ *   4. The bump directive is the HIGHEST tier among the inputs
+ *      (major > minor > patch), emitted as `<!-- bump: X -->`. This is a
+ *      documentation hint only — the REAL release tier is
+ *      `.instar/release-tier.json`, which this script never touches.
+ *   5. Writes the merged result to `upgrades/NEXT.md`.
+ *
+ * ── No-op / failure semantics ─────────────────────────────────────────
+ *   - NO fragments AND NO legacy NEXT.md → does nothing, exits 0 quietly. The
+ *     existing publish "skip if no NEXT.md" logic then fires unchanged.
+ *   - A real malformation (a fragment with content but no parseable H2 section
+ *     at all) → exits non-zero with a clear message, so the workflow fails
+ *     loudly rather than shipping a broken guide.
+ *   - Idempotent: running twice produces the same NEXT.md. (When a generated
+ *     NEXT.md is the ONLY input — no fragments — it is re-emitted byte-stable.)
+ *
+ * The core `assembleNextMd()` function is pure (string in / string out) and is
+ * exported for unit testing. The CLI wrapper at the bottom handles I/O.
+ *
+ * Usage:
+ *   node scripts/assemble-next-md.mjs            # assemble + write upgrades/NEXT.md
+ *   node scripts/assemble-next-md.mjs --upgrades-dir <path>   # override (tests)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+// ── Canonical section order ───────────────────────────────────────────
+// These four are the sections check-upgrade-guide.js / upgrade-guide-validator
+// know about. We emit them in this order; any other H2 is appended after.
+export const CANONICAL_SECTIONS = [
+  'What Changed',
+  'What to Tell Your User',
+  'Summary of New Capabilities',
+  'Evidence',
+];
+
+const BUMP_RANK = { patch: 0, minor: 1, major: 2 };
+const RANK_BUMP = ['patch', 'minor', 'major'];
+
+const H1_HEADER = '# Upgrade Guide — vNEXT';
+
+// Stable marker stamped into every machine-assembled NEXT.md. It lets us
+// recognize (and skip re-folding) a NEXT.md that this script generated, which
+// is what keeps the on-disk assemble idempotent: a second run shouldn't fold
+// the previous run's output back in on top of the still-present fragments. A
+// hand-authored legacy NEXT.md (no marker) is still folded for backward compat.
+export const GENERATED_MARKER = '<!-- assembled-by: assemble-next-md -->';
+
+/** True when content was produced by this assembler (carries the marker). */
+export function isAssembledOutput(content) {
+  return String(content).includes(GENERATED_MARKER);
+}
+
+/**
+ * Parse the declared bump type from a fragment's `<!-- bump: TYPE -->` comment.
+ * Returns 'patch' | 'minor' | 'major' | null.
+ */
+export function parseBumpType(content) {
+  const match = /<!--\s*bump:\s*(patch|minor|major)\s*-->/i.exec(content);
+  return match ? match[1].toLowerCase() : null;
+}
+
+/**
+ * Split a fragment body into H2 sections: [{ title, body }] in source order.
+ * `body` excludes the heading line itself and is right-trimmed.
+ * Content before the first H2 (H1 header, bump comment, stray prose) is dropped
+ * from the section map — the assembler synthesizes a fresh H1 + bump comment.
+ */
+export function parseSections(content) {
+  const out = [];
+  const lines = String(content).replace(/\r\n/g, '\n').split('\n');
+  let current = null;
+  for (const line of lines) {
+    const m = /^##\s+(.+?)\s*$/.exec(line);
+    if (m) {
+      if (current) out.push(current);
+      current = { title: m[1].trim(), lines: [] };
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  if (current) out.push(current);
+  return out.map((s) => ({ title: s.title, body: s.lines.join('\n').replace(/\s+$/, '') }));
+}
+
+/**
+ * Is this fragment content "empty" for assembly purposes? True when stripping
+ * HTML comments and whitespace leaves nothing.
+ */
+function isEffectivelyEmpty(content) {
+  return String(content).replace(/<!--[\s\S]*?-->/g, '').trim().length === 0;
+}
+
+/**
+ * Core assembler. Pure: takes named fragment inputs, returns the merged NEXT.md
+ * string (or throws on a real malformation).
+ *
+ * @param {Array<{ name: string, content: string }>} fragments
+ *   Each input fragment, in the order they should be concatenated. `name` is
+ *   used only for error messages.
+ * @returns {string} the assembled NEXT.md content (with trailing newline).
+ * @throws {Error} when a fragment has content but no parseable H2 section.
+ */
+export function assembleNextMd(fragments) {
+  // Idempotency guard: a previously-assembled NEXT.md (carrying GENERATED_MARKER)
+  // is the FOLD of the current fragments — folding it again on top of the same
+  // fragments would duplicate every section. So when at least one non-generated
+  // input is present, drop the generated one(s). When a generated output is the
+  // SOLE input (no fragments), keep it: parse→emit is stable, so it re-emits
+  // identically.
+  const nonGenerated = fragments.filter((f) => !isAssembledOutput(f.content ?? ''));
+  const effective = nonGenerated.length > 0 ? nonGenerated : fragments;
+
+  // Map title -> array of section bodies (in source order).
+  const merged = new Map();
+  // Preserve first-seen order of non-canonical titles.
+  const extraOrder = [];
+  let maxBumpRank = 0;
+  let sawAnyBump = false;
+
+  for (const frag of effective) {
+    const content = frag.content ?? '';
+    const bump = parseBumpType(content);
+    if (bump) {
+      sawAnyBump = true;
+      maxBumpRank = Math.max(maxBumpRank, BUMP_RANK[bump]);
+    }
+
+    const sections = parseSections(content);
+    if (sections.length === 0) {
+      // No H2 sections. An effectively-empty fragment (only comments/whitespace)
+      // is malformed — a fragment file should always carry real notes.
+      // A fragment with real prose but no headings is also malformed: we can't
+      // place its content under a known section.
+      throw new Error(
+        `release-note fragment "${frag.name}" has no recognizable "## " section. ` +
+        `Every fragment must contain at least one section heading ` +
+        `(e.g. "## What Changed"). Fix or remove this fragment.`,
+      );
+    }
+
+    for (const sec of sections) {
+      const body = sec.body.trim();
+      // Skip a section whose body is only whitespace/comments — nothing to fold.
+      if (isEffectivelyEmpty(body)) continue;
+      if (!merged.has(sec.title)) {
+        merged.set(sec.title, []);
+        if (!CANONICAL_SECTIONS.includes(sec.title)) extraOrder.push(sec.title);
+      }
+      merged.get(sec.title).push(body);
+    }
+  }
+
+  // If after folding there is genuinely nothing to say, that's a malformation
+  // for a non-empty input set (every fragment was comments-only).
+  if (merged.size === 0) {
+    throw new Error(
+      'release-note fragments produced no content — every section was empty. ' +
+      'Fill in at least "## What Changed" in one fragment.',
+    );
+  }
+
+  // Emit canonical sections first (only when present), then extras in
+  // first-seen order.
+  const titleOrder = [
+    ...CANONICAL_SECTIONS.filter((t) => merged.has(t)),
+    ...extraOrder,
+  ];
+
+  const bump = sawAnyBump ? RANK_BUMP[maxBumpRank] : 'patch';
+
+  const parts = [];
+  parts.push(H1_HEADER);
+  parts.push('');
+  parts.push(GENERATED_MARKER);
+  parts.push(`<!-- bump: ${bump} -->`);
+  parts.push('');
+  for (const title of titleOrder) {
+    const bodies = merged.get(title);
+    parts.push(`## ${title}`);
+    parts.push('');
+    // Concatenate each fragment's body for this section, separated by a blank
+    // line. Bodies were already trimmed.
+    parts.push(bodies.join('\n\n'));
+    parts.push('');
+  }
+
+  // Single trailing newline, no duplicate blank lines at EOF.
+  return parts.join('\n').replace(/\n+$/, '\n');
+}
+
+// ── CLI entry point ────────────────────────────────────────────────────
+
+/**
+ * Gather fragment inputs from disk in deterministic order: legacy NEXT.md first
+ * (so its content leads), then `next/*.md` sorted by filename.
+ */
+export function gatherFragmentInputs(upgradesDir) {
+  const inputs = [];
+
+  const legacyPath = path.join(upgradesDir, 'NEXT.md');
+  const fragmentsDir = path.join(upgradesDir, 'next');
+
+  let legacyContent = null;
+  if (fs.existsSync(legacyPath)) {
+    legacyContent = fs.readFileSync(legacyPath, 'utf-8');
+  }
+
+  let fragmentFiles = [];
+  if (fs.existsSync(fragmentsDir)) {
+    fragmentFiles = fs
+      .readdirSync(fragmentsDir)
+      .filter((f) => f.endsWith('.md'))
+      .sort((a, b) => a.localeCompare(b, 'en'));
+  }
+
+  // Fold the legacy NEXT.md in first — only when it carries real content
+  // (skip a bare template/empty file so re-runs are idempotent and a fresh
+  // template doesn't masquerade as content).
+  if (legacyContent !== null && !isEffectivelyEmpty(legacyContent)) {
+    inputs.push({ name: 'NEXT.md', content: legacyContent });
+  }
+
+  for (const file of fragmentFiles) {
+    const content = fs.readFileSync(path.join(fragmentsDir, file), 'utf-8');
+    inputs.push({ name: `next/${file}`, content });
+  }
+
+  return { inputs, hadLegacy: legacyContent !== null, fragmentCount: fragmentFiles.length };
+}
+
+function main() {
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const ROOT = path.resolve(__dirname, '..');
+
+  // Allow tests / callers to point at an alternate upgrades dir.
+  const argIdx = process.argv.indexOf('--upgrades-dir');
+  const upgradesDir =
+    argIdx !== -1 && process.argv[argIdx + 1]
+      ? path.resolve(process.argv[argIdx + 1])
+      : path.join(ROOT, 'upgrades');
+
+  const { inputs, hadLegacy, fragmentCount } = gatherFragmentInputs(upgradesDir);
+
+  if (inputs.length === 0) {
+    // No fragments and no (content-bearing) legacy NEXT.md. Do nothing — the
+    // existing publish skip logic handles the "nothing to publish" case.
+    console.log(
+      `[assemble-next-md] no fragments in ${path.join(upgradesDir, 'next')} ` +
+      `and no content-bearing NEXT.md — nothing to assemble.`,
+    );
+    process.exit(0);
+  }
+
+  let assembled;
+  try {
+    assembled = assembleNextMd(inputs);
+  } catch (err) {
+    console.error(`[assemble-next-md] ERROR: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+
+  const nextPath = path.join(upgradesDir, 'NEXT.md');
+  fs.mkdirSync(upgradesDir, { recursive: true });
+  fs.writeFileSync(nextPath, assembled);
+
+  console.log(
+    `[assemble-next-md] assembled ${fragmentCount} fragment(s)` +
+    `${hadLegacy ? ' + legacy NEXT.md' : ''} → ${path.relative(ROOT, nextPath)}`,
+  );
+  process.exit(0);
+}
+
+// Only run main() when invoked directly (not when imported by tests).
+// Compare resolved file URLs rather than string-concatenating argv[1] — that
+// naive form breaks on relative paths and paths containing spaces.
+function invokedDirectly() {
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href;
+  } catch {
+    return import.meta.url === pathToFileURL(process.argv[1]).href;
+  }
+}
+
+if (invokedDirectly()) {
+  main();
+}

package/scripts/pre-push-gate.js

@@ -14,11 +14,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { validateGuideContent } from './upgrade-guide-validator.mjs';
+import { assembleNextMd, gatherFragmentInputs } from './assemble-next-md.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
 const upgradesDir = path.join(ROOT, 'upgrades');
-const nextPath = path.join(ROOT, 'upgrades', 'NEXT.md');
 const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf-8'));
 const version = pkg.version;
 
@@ -34,38 +34,66 @@ const REQUIRED_SECTIONS = [
 let errors = [];
 let warnings = [];
 
-// ── 1. NEXT.md validation ─────────────────────────────────────────────
+// ── 1. Release-note validation (fragment-aware) ───────────────────────
+//
+// Release notes are authored as per-PR FRAGMENTS in upgrades/next/<slug>.md
+// (so concurrent PRs never collide on a single shared NEXT.md). The pre-push
+// gate validates the ASSEMBLED result — fragments folded together with any
+// legacy upgrades/NEXT.md — so a PR that ships only a fragment passes the same
+// section/content checks the publish gate enforces. We assemble in-memory and
+// NEVER write NEXT.md to disk here: the PR keeps its fragment, not a generated
+// guide. publish.yml runs the real assemble step before publishing.
 
 const versionedGuidePath = path.join(upgradesDir, `${version}.md`);
 const versionedGuideExists = fs.existsSync(versionedGuidePath);
-const nextExists = fs.existsSync(nextPath);
-
-// Pick the active guide for this push. NEXT.md wins if present (in-flight
-// release notes); fall back to the versioned guide once NEXT.md has been
-// renamed during a publish.
-const activeGuidePath = nextExists
-  ? nextPath
-  : (versionedGuideExists ? versionedGuidePath : null);
-const activeGuideLabel = nextExists
-  ? 'NEXT.md'
-  : (versionedGuideExists ? `${version}.md` : null);
 
-if (activeGuidePath && activeGuideLabel) {
-  const content = fs.readFileSync(activeGuidePath, 'utf-8');
+// Assemble fragments + legacy NEXT.md in-memory.
+let assembledContent = null;
+let assembleError = null;
+{
+  const { inputs } = gatherFragmentInputs(upgradesDir);
+  if (inputs.length > 0) {
+    try {
+      assembledContent = assembleNextMd(inputs);
+    } catch (err) {
+      assembleError = err instanceof Error ? err.message : String(err);
+    }
+  }
+}
 
+// The active guide for validation: the assembled fragments/NEXT.md (in-flight
+// release notes) win when present; otherwise fall back to the versioned guide
+// (post-release-cut state, when NEXT.md has been renamed and no new fragment is
+// staged yet).
+const activeGuideLabel = assembledContent !== null
+  ? 'assembled release notes (upgrades/next/*.md + NEXT.md)'
+  : (versionedGuideExists ? `${version}.md` : null);
+
+if (assembleError) {
+  // A malformed fragment must fail the push loudly — the same loud failure the
+  // publish workflow would hit.
+  errors.push(`Release-note fragments are malformed: ${assembleError}`);
+} else if (assembledContent !== null) {
   // Run the shared validator (same checks as check-upgrade-guide.js at publish
   // time). This catches the publish-blocker bugs that previously slipped past
   // pre-push: inline code / fenced blocks / camelCase config keys in "What to
   // Tell Your User", and missing "## Evidence" when "What Changed" claims a fix.
   // Before this gate, those defects only surfaced as silently-dropped publish
   // runs on main — agents never received the merged code.
-  const validatorIssues = validateGuideContent(content);
+  const validatorIssues = validateGuideContent(assembledContent);
   for (const issue of validatorIssues) {
     errors.push(`${activeGuideLabel}: ${issue}`);
   }
+} else if (versionedGuideExists) {
+  const content = fs.readFileSync(versionedGuidePath, 'utf-8');
+  const validatorIssues = validateGuideContent(content);
+  for (const issue of validatorIssues) {
+    errors.push(`${version}.md: ${issue}`);
+  }
 } else {
   errors.push(
-    `No upgrade guide found. Create upgrades/NEXT.md with sections: ${REQUIRED_SECTIONS.join(', ')}`
+    `No upgrade guide found. Create a release-note fragment ` +
+    `upgrades/next/<slug>.md (or legacy upgrades/NEXT.md) with sections: ${REQUIRED_SECTIONS.join(', ')}`
   );
 }
 
@@ -221,14 +249,16 @@ if (!process.env.CI) {
     /\bnew\b/i,
   ];
 
-  // When NEXT.md exists, it represents the *next* shipment being prepared in
-  // this push — prefer it over the (frozen) versioned guide, which describes
-  // the already-released version and isn't what this PR is changing. This is
-  // the post-release-cut + new-PR state: both files coexist, but only NEXT.md
-  // is in flight. Falls back to the versioned guide when no NEXT.md is staged.
-  const guidePath = nextExists ? nextPath : (versionedGuideExists ? versionedGuidePath : null);
-  if (guidePath && fs.existsSync(guidePath)) {
-    const guideContent = fs.readFileSync(guidePath, 'utf-8');
+  // The in-flight release notes (assembled fragments + legacy NEXT.md) represent
+  // the *next* shipment being prepared in this push — prefer them over the
+  // (frozen) versioned guide, which describes the already-released version and
+  // isn't what this PR is changing. Falls back to the versioned guide when no
+  // fragment / NEXT.md is staged (post-release-cut state).
+  const inFlight = assembledContent !== null;
+  const guideContent = inFlight
+    ? assembledContent
+    : (versionedGuideExists ? fs.readFileSync(versionedGuidePath, 'utf-8') : null);
+  if (guideContent !== null) {
     // Extract "## What Changed" section
     const whatChangedMatch = guideContent.match(/## What Changed\s*([\s\S]*?)(?=\n##\s|$)/);
     const whatChanged = whatChangedMatch ? whatChangedMatch[1] : '';
@@ -237,10 +267,10 @@ if (!process.env.CI) {
 
     if (qualifies) {
       const sideEffectsDir = path.join(ROOT, 'upgrades', 'side-effects');
-      // If NEXT.md is the active guide, any fresh artifact (last 24h) counts —
-      // the versioned-filename requirement only applies when a versioned guide
-      // is being validated without an in-flight NEXT.md.
-      const artifactName = (!nextExists && versionedGuideExists) ? `${version}.md` : null;
+      // When in-flight notes (fragments/NEXT.md) drive the push, any fresh
+      // artifact (last 24h) counts — the versioned-filename requirement only
+      // applies when a versioned guide is being validated without in-flight notes.
+      const artifactName = (!inFlight && versionedGuideExists) ? `${version}.md` : null;
       let artifactFound = false;
 
       if (fs.existsSync(sideEffectsDir)) {
@@ -248,9 +278,9 @@ if (!process.env.CI) {
         if (artifactName) {
           artifactFound = files.includes(artifactName);
         } else {
-          // For NEXT.md, any fresh artifact from the last 24h counts.
-          // The expectation is that during release cut, NEXT.md -> <version>.md
-          // rename will pair with the artifact rename as well.
+          // For in-flight notes (fragments/NEXT.md), any fresh artifact from the
+          // last 24h counts. The expectation is that during release cut, the
+          // fragment/NEXT.md -> <version>.md rename pairs with an artifact rename.
           const recent = files.filter((f) => {
             const stat = fs.statSync(path.join(sideEffectsDir, f));
             return Date.now() - stat.mtimeMs < 24 * 60 * 60 * 1000;

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-31T09:03:11.651Z",
-  "instarVersion": "1.3.152",
+  "generatedAt": "2026-05-31T09:19:20.889Z",
+  "instarVersion": "1.3.153",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.153.md

@@ -0,0 +1,51 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Release notes are now authored as per-PR **fragments** instead of a single shared
+`upgrades/NEXT.md`. Each PR drops its release note at `upgrades/next/<slug>.md`,
+touching a distinct file, so two concurrent PRs never collide on the release
+notes — the bottleneck that made many-agent merges un-landable in real time.
+
+A new pure script, `scripts/assemble-next-md.mjs`, folds every fragment (sorted
+deterministically by filename) — plus any legacy `upgrades/NEXT.md`, for backward
+compatibility — into a single `upgrades/NEXT.md`, merging by section: one What
+Changed, one What to Tell Your User, one Summary of New Capabilities, one Evidence,
+each being the concatenation of that section across all inputs. Non-canonical
+sections are preserved and appended. The emitted bump directive is the highest tier
+among the fragments (major beats minor beats patch); it is a documentation hint only
+— the real release tier still comes from `.instar/release-tier.json`, which is
+untouched.
+
+The publish workflow gains ONE new step, "Assemble release-note fragments", placed
+immediately before the existing "Check if NEXT.md has content to publish" step.
+Everything downstream — the tier gate, version resolution, the rename, the upgrade
+guide check, publish, and commit — is unchanged. With no fragments and no legacy
+NEXT.md, the assemble step does nothing and the existing skip logic fires exactly as
+before, so the no-fragments path reproduces current behavior byte-for-byte. After a
+release is cut, consumed fragments are deleted (`rm -f upgrades/next/*.md`) and the
+existing commit step stages the deletions. The pre-push gate is now fragment-aware:
+it validates the assembled result in-memory (never writing NEXT.md to disk during
+pre-push), so a PR that ships only a fragment passes the same section and content
+checks the publish gate enforces, and a malformed fragment fails the push loudly.
+`upgrades/NEXT.md` remains fully supported as a legacy, backward-compatible path.
+
+## What to Tell Your User
+
+Behind the scenes, the way I prepare release notes got a lot more robust. Each
+change now writes its own small note in its own file, instead of every change
+fighting over one shared notes file. That means when several updates are being
+prepared at the same time, they no longer block each other, so improvements reach
+you faster and with less risk of a release getting stuck. Nothing changes about how
+I talk to you — this is purely a smoother release pipeline on my side.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Per-PR release-note fragments | Write `upgrades/next/<slug>.md` (one file per change) |
+| Fragment assembler | `node scripts/assemble-next-md.mjs` (runs automatically in publish) |
+| Legacy NEXT.md | Still supported — folded in for backward compatibility |

package/upgrades/side-effects/nextmd-release-note-fragments.md

@@ -0,0 +1,151 @@
+# Side-Effects Review — Per-PR release-note fragments
+
+**Version / slug:** `nextmd-release-note-fragments`
+**Date:** `2026-05-31`
+**Author:** `echo`
+**Second-pass reviewer:** `required` (release-pipeline blast radius — see §1, §7)
+
+## Summary of the change
+
+The release pipeline consumed a single shared `upgrades/NEXT.md` per merge. With
+many agents merging concurrently, every PR rewrote NEXT.md, so every PR collided on
+it within minutes — the release notes became an un-landable hot file. This change
+introduces per-PR release-note FRAGMENTS (`upgrades/next/<slug>.md`): two PRs touch
+different fragment files and never collide.
+
+The mechanism is an ASSEMBLE PRE-STEP. A new pure script
+(`scripts/assemble-next-md.mjs`) folds every fragment (deterministic filename sort)
+plus any legacy `upgrades/NEXT.md` into a single `upgrades/NEXT.md`, merging by
+section. The publish workflow runs it immediately BEFORE the existing
+"Check if NEXT.md has content to publish" step; everything downstream is unchanged.
+The pre-push gate validates the assembled result in-memory (never writing NEXT.md).
+
+## Decision-point inventory
+
+1. **No-fragments / no-legacy-NEXT.md → no-op (exit 0 quietly).** The existing skip
+   logic then fires. This is the load-bearing backward-compat boundary.
+2. **Malformed fragment (content but no parseable `## ` section, or only
+   comments/whitespace) → loud non-zero exit.** Fails the workflow rather than
+   shipping a broken guide.
+3. **Idempotency guard:** an input carrying `GENERATED_MARKER` is dropped when any
+   non-generated input is present; folded straight through (stable re-emit) when it
+   is the sole input. Decides "is this a fresh fragment set or a re-run on prior
+   output?"
+4. **Bump tier = MAX(fragments).** A hint only; the real tier is
+   `.instar/release-tier.json` (untouched).
+5. **pre-push gate active-guide selection:** assembled in-flight notes win; else fall
+   back to the versioned guide; else "no guide" error.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject?** A fragment with real prose but no
+`## ` heading is rejected — intentional, because the assembler can't place headless
+prose under a known section. An effectively-empty fragment (comments/whitespace only)
+is rejected — intentional, an empty fragment file is a mistake. A hand-authored legacy
+`upgrades/NEXT.md` is NOT rejected: it is folded in (backward compat). The
+no-fragments-and-no-NEXT.md case is NOT an error — it is a clean exit-0 no-op, so the
+existing "nothing to publish" skip is preserved exactly. **No legitimate current input
+is newly rejected:** today's flow ships a NEXT.md, which still validates and publishes
+unchanged.
+
+## 2. Under-block
+
+**What does this still miss?** The assembler does not deep-validate each fragment's
+section CONTENT (camelCase keys, inline code, missing Evidence) — that remains the job
+of `validateGuideContent`, which runs against the ASSEMBLED result in both the pre-push
+gate and (post-rename) `check-upgrade-guide.js`. So a defect in a fragment is caught at
+the assembled layer, not per-fragment; this is acceptable because the assembled doc is
+exactly what publishes. It does not detect two fragments making contradictory claims —
+out of scope (humans review notes). It does not garbage-collect stale fragments that
+were never released; the publish path deletes only the fragments it just consumed.
+
+## 3. Level-of-abstraction fit
+
+**Right layer?** Yes. The assembler is a pure string→string function with a thin CLI
+wrapper (same shape as `resolve-release-tier.mjs` / `resolve-publish-version.mjs`),
+unit-tested in isolation. The workflow change is one additive step plus one `rm` in the
+existing consumption path — it does not touch the tier gate, version resolution, rename,
+guide check, publish, or commit logic. The pre-push gate reuses the SAME assemble
+function (single source of truth), so pre-push and publish can never diverge on how
+fragments fold.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+No new blocking AUTHORITY over releases is added. The assembler is a transform, not a
+gate: its only failure mode is a malformation (exit non-zero), which is the same loud
+behavior the publish workflow already wants. The real publish AUTHORITY is unchanged —
+`.instar/release-tier.json` (Layer 2) and `validateGuideContent` (the section/content
+gate) still decide what ships. The emitted bump comment is explicitly a documentation
+SIGNAL, not authority (the code comment and the artifact both say so).
+
+## 5. Interactions
+
+- **UpgradeGuideProcessor**: scans `upgrades/` for files matching
+  `^(\d+\.\d+\.\d+)\.md$`. `readdirSync` returns the subdir name `next` (no `.md`
+  suffix) → not matched → ignored. Verified by reading `getAvailableGuides`. The
+  `upgrades/next/` directory is invisible to guide delivery.
+- **check-upgrade-guide.js**: iterates `upgrades/*.md` files (skips `NEXT.md`); the
+  `next/` subdir is not a `.md` file → skipped. By publish time fragments are already
+  deleted and NEXT.md renamed, so it validates the assembled+renamed guide. Verified
+  end-to-end in a scratch dir (assemble → rename → check → exit 0).
+- **pre-push-gate.js**: now imports the assembler; assembles in-memory; the side-effects
+  artifact check (§5 of the gate) reads the assembled "What Changed" instead of raw
+  NEXT.md. No NEXT.md is written during pre-push.
+- **Idempotency / re-runs**: the `GENERATED_MARKER` guard prevents a re-run from
+  double-folding prior output back over still-present fragments.
+- No interaction with SessionReaper, sentinels, recovery, or any runtime path — this is
+  build/CI tooling only.
+
+## 6. External surfaces
+
+- New directory `upgrades/next/` and new file convention `upgrades/next/<slug>.md`.
+- New script `scripts/assemble-next-md.mjs` (build-time only; never shipped to agent
+  runtime paths).
+- One new publish workflow step + one `rm` in the existing rename step.
+- New CLAUDE.md / build-skill guidance instructing fragment authoring; a
+  `PostUpdateMigrator` CLAUDE.md backfill for deployed agents.
+- No HTTP routes, no config keys, no Telegram, no agent runtime behavior change.
+
+## 7. Rollback cost
+
+**Low and clean.** Three independent revert points, each safe on its own:
+- Remove the "Assemble release-note fragments" workflow step + the `rm` line → publish
+  reverts to consuming NEXT.md directly (NEXT.md authoring still works).
+- Revert the pre-push gate to validating NEXT.md directly.
+- Delete `scripts/assemble-next-md.mjs` + its test.
+Because the no-fragments path is a byte-for-byte no-op, a half-rollback (e.g. removing
+only the workflow step while authors still write fragments) degrades gracefully: the
+release simply skips (no NEXT.md), which the release-readiness sentinel surfaces — it
+never ships a wrong or partial guide. No state, no schema, no irreversible op, no data
+migration. Fragments are plain markdown files.
+
+## Conclusion
+
+Additive, backward-compatible, pure-function-at-the-core change to build/CI tooling.
+The release-critical invariant — "the no-fragments path reproduces exact current
+behavior" — is enforced by code (clean exit-0 no-op) and covered by tests (CLI exits 0
+and writes nothing; pre-push accepts a fragment-only push and rejects a malformed one).
+Blast radius is contained to the assemble pre-step; the tier gate, version resolution,
+and content validation that actually authorize a release are untouched.
+
+## Second-pass review (if required)
+
+Required (release-pipeline). Reviewer focus: confirm the publish.yml diff is additive
+(the assemble step precedes the unchanged skip-check; the `rm` rides the existing
+`if:` guard and the existing `git add upgrades/`), and that the no-fragments path still
+skips cleanly. Pending.
+
+## Evidence pointers
+
+- `tests/unit/assemble-next-md.test.ts` — 25 tests: section merge, deterministic order,
+  max bump tier, single fragment, legacy fold, no-op/quiet, malformed→loud, idempotent
+  (in-memory + on-disk CLI), WTTYU backtick-free.
+- `tests/unit/pre-push-gate.test.ts` — fragment-aware integration: accepts fragment-only
+  push (writes no NEXT.md), rejects WTTYU inline code via assembled validation, rejects
+  malformed fragment loudly.
+- Manual end-to-end (scratch dir): fragment → `assemble-next-md.mjs` →
+  `mv NEXT.md <version>.md` + `rm next/*.md` → `check-upgrade-guide.js` exit 0.
+- `upgrades/next/release-note-fragments.md` — this PR's own release note (dogfoods the
+  mechanism; the PR does not touch `upgrades/NEXT.md`).