instar 1.3.152 → 1.3.154

package/upgrades/1.3.154.md

@@ -0,0 +1,91 @@
+# 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
+
+If you run a Codex-based agent, it can now run in autonomous mode and keep itself going across
+many turns until the goal is met — the same way a Claude agent does. Before, a Codex agent in
+autonomous mode would quietly stop after a single turn. Nothing to configure; it applies on the
+next update, and Claude agents are unaffected.
+
+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
+
+- `setup-autonomous.sh` now enables native /goal delegation for Codex agents (detected via config
+  `enabledFrameworks` containing `codex-cli`), not just Claude Code >= 2.1.139. Codex autonomous
+  mode auto-delegates to native /goal; the stop-hook's existing `goal_mode:native` branch defers.
+- `PostUpdateMigrator` marker bump (`native-goal/set` → `IS_CODEX_AGENT`) re-deploys the fixed
+  setup script to existing agents.
+
+| 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 |
+
+## Evidence
+
+- Root cause traced by reading setup-autonomous.sh: the native /goal hand-off existed but was
+  gated on `claude --version >= 2.1.139` (empty for a codex agent → codex fell to the dark
+  Phase-1 no-op). Proven live in round 2 that codex /goal sustains 1→2→3 across turns.
+- Unit: `tests/unit/autonomous-codex-native-goal-detection.test.ts` — both sides of the
+  decision boundary (codex enables, Claude/absent skips, multi-framework enables, missing config
+  best-effort skips).
+- Unit: `tests/unit/PostUpdateMigrator-autonomousStopHook.test.ts` — a prior native-/goal setup
+  is re-deployed by the marker bump; all existing cases stay green (8 tests).
+- `tsc --noEmit` + `npm run lint` clean.
+- Spec: `docs/specs/codex-autonomy-native-goal-autowire.md` (+ `.eli16.md`).
+- Side-effects: `upgrades/side-effects/codex-autonomy-native-goal-autowire.md`.
+- Final proof is the live drive: Codey running the real /autonomous skill and sustaining multi-turn.
+
+## What Changed — Codex agents now run autonomous mode on their own (Claude parity)
+
+When you put an agent in autonomous mode, it should keep working across many turns until the job
+is done. Claude agents already did this (via the stop hook). Codex agents did NOT — they would
+quietly stop after one turn. Codex actually has its own way to sustain a multi-turn run (its
+built-in /goal loop), and instar already handed the goal off to it automatically — but only
+behind a check for "Claude command-line version 2.1.139+", which is empty for a Codex agent. So
+Codex agents fell through that Claude-shaped gate and never got the hand-off.
+
+This adds a small framework-aware fallback: if the Claude check doesn't apply, instar detects a
+Codex agent (from its own config) and hands the goal to Codex's native /goal loop. Now a Codex
+agent in autonomous mode sustains multi-turn work automatically, the same as a Claude agent. The
+Claude path is unchanged, and the sensitive stop hook is untouched.

package/upgrades/side-effects/codex-autonomy-native-goal-autowire.md

@@ -0,0 +1,43 @@
+# Side-effects — Codex autonomous native /goal auto-wire
+
+## 1. What files/state does this touch at runtime?
+`.claude/skills/autonomous/scripts/setup-autonomous.sh` (skill content). At autonomous-mode
+activation on a CODEX agent, it now additionally POSTs `/autonomous/native-goal/set` (which the
+script already did for Claude>=2.1.139) — injecting `/goal <completion_condition>` into the
+session and marking the job `goal_mode:native` in `<topic>.local.md`. No new files, no config
+keys, no schema. The PostUpdateMigrator re-deploys the script to existing agents (marker bump).
+
+## 2. Does it change any functional behavior?
+- **Claude agents:** none. The Claude version gate is untouched; the codex check only runs when
+  the Claude gate already failed.
+- **Codex agents:** a codex autonomous job now auto-delegates to native `/goal` (previously it
+  fell through to the dark Phase-1 codexLoopDriver no-op and silently never sustained multi-turn).
+  The stop-hook's existing `goal_mode:native` branch then defers to native `/goal`.
+
+## 3. What happens on failure / weird config?
+Best-effort: the detection one-liner is `... 2>/dev/null || echo "0"`, so a missing/malformed
+config.json or absent python → `0` → not-codex → exactly the prior behavior (no regression). A
+codex agent whose native `/goal` POST fails → the script prints "Native /goal: unavailable" and
+instar's own completion evaluator drives (the existing fallback).
+
+## 4. Migration parity — do existing agents get it?
+Yes. `migrateAutonomousStopHookTopicKeyed` marker bumped `native-goal/set` → `IS_CODEX_AGENT`,
+so prior native-/goal installs are re-deployed; customized scripts (no stock fingerprint) are
+left untouched; already-updated agents skip (idempotent). New agents get it via installAutonomousSkill.
+
+## 5. Could it spam / flood / burn resources?
+No. It adds at most one extra `python3` config read + (for codex) one `native-goal/set` POST,
+once, at autonomous-mode activation — the same POST the script already made for Claude.
+
+## 6. Rollback / off-switch?
+Revert the PR. The marker would revert too; a reverted-version agent retains `native-goal/set`
+(still functional for Claude). No residual state, no flag.
+
+## 7. Concurrency / ordering?
+None new. Runs inline in the single setup-autonomous.sh activation flow, after the Claude gate.
+
+## Blast radius
+Small + additive, codex-only. One ~5-line fallback in setup-autonomous.sh + one migration marker
+bump in PostUpdateMigrator. No change to the sensitive stop-hook (the goal_mode:native defer
+already existed), no change to the Claude path. Mirrors the #604/#609 codex framework-additive
+pattern. The codexLoopDriver:true config footgun is a separate low-pri follow-up (#40 notes).

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`).