instar 0.28.104 → 0.28.105

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.28.104",
+  "version": "0.28.105",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/scripts/pre-push-gate.js

@@ -13,6 +13,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { validateGuideContent } from './upgrade-guide-validator.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
@@ -21,14 +22,15 @@ 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;
 
+// Section list kept here only for the "no upgrade guide found" error
+// message. The full per-section validation now flows through
+// validateGuideContent (which has its own canonical REQUIRED_SECTIONS).
 const REQUIRED_SECTIONS = [
   '## What Changed',
   '## What to Tell Your User',
   '## Summary of New Capabilities',
 ];
 
-const MIN_LENGTH = 200;
-
 let errors = [];
 let warnings = [];
 
@@ -38,39 +40,28 @@ const versionedGuidePath = path.join(upgradesDir, `${version}.md`);
 const versionedGuideExists = fs.existsSync(versionedGuidePath);
 const nextExists = fs.existsSync(nextPath);
 
-if (versionedGuideExists) {
-  // Already finalized — validate the versioned guide instead
-  const content = fs.readFileSync(versionedGuidePath, 'utf-8');
-  for (const section of REQUIRED_SECTIONS) {
-    if (!content.includes(section)) {
-      errors.push(`${version}.md missing "${section}" section`);
-    }
-  }
-  if (content.length < MIN_LENGTH) {
-    errors.push(`${version}.md is too short (${content.length} chars, need ${MIN_LENGTH}+)`);
-  }
-} else if (nextExists) {
-  const content = fs.readFileSync(nextPath, 'utf-8');
-
-  for (const section of REQUIRED_SECTIONS) {
-    if (!content.includes(section)) {
-      errors.push(`NEXT.md missing "${section}" section`);
-    }
-  }
-
-  if (content.length < MIN_LENGTH) {
-    errors.push(`NEXT.md is too short (${content.length} chars, need ${MIN_LENGTH}+)`);
-  }
-
-  // Check for unfilled template placeholders
-  if (content.includes('<!-- Describe what changed')) {
-    errors.push(`NEXT.md "What Changed" still has template placeholder`);
-  }
-  if (content.includes('[Feature name]') || content.includes('[Brief, friendly description')) {
-    errors.push(`NEXT.md "What to Tell Your User" still has template placeholder`);
-  }
-  if (content.includes('[Capability]') && content.includes('[Endpoint, command')) {
-    errors.push(`NEXT.md "Summary of New Capabilities" still has template placeholder`);
+// 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');
+
+  // 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);
+  for (const issue of validatorIssues) {
+    errors.push(`${activeGuideLabel}: ${issue}`);
   }
 } else {
   errors.push(

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-15T19:51:52.508Z",
-  "instarVersion": "0.28.104",
+  "generatedAt": "2026-05-15T20:09:47.987Z",
+  "instarVersion": "0.28.105",
   "entryCount": 188,
   "entries": {
     "hook:session-start": {

package/upgrades/0.28.105.md

@@ -0,0 +1,70 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+### fix(release): pre-push gate now validates upgrade-guide well-formedness
+
+`scripts/pre-push-gate.js` now imports `validateGuideContent` from
+`scripts/upgrade-guide-validator.mjs` and runs it on the active upgrade
+guide (NEXT.md or the versioned fallback). Same authority as the
+publish-time `check-upgrade-guide.js`, just enforced one step earlier.
+
+Before this fix, malformed release notes (inline code or camelCase
+config keys in "What to Tell Your User", missing "## Evidence" when
+fixes are claimed) passed pre-push, merged on main, and only failed at
+publish-time — silently. Between 2026-05-13 and 2026-05-15 that pattern
+stranded four PRs on main without reaching npm: the token-ledger Phase
+1 (#112), the PromptGate token-burn fix (#226), and the entire
+remediation track for over a day.
+
+Test coverage: 4 new integration tests in `tests/unit/pre-push-gate.test.ts`
+spawn the actual gate script against handcrafted malformed-NEXT.md fixtures
+in a scratch directory and assert the right exit code + error text for
+each shape, plus a well-formed control case that the gate must accept.
+
+Spec: `docs/specs/pre-push-upgrade-guide-validation.md`. Side-effects
+review: `upgrades/side-effects/pre-push-upgrade-guide-validation.md`.
+
+## What to Tell Your User
+
+**Releases stop failing silently.** Before today, a small wording issue
+in a release notes file could quietly stop your agent from getting any
+new code at all — the release just wouldn't ship to the package registry,
+and nothing would alert anyone. This release moves the same check the
+release pipeline already runs into the developer's push step, so the
+issue is caught the moment the change is made instead of two days later
+when someone notices the silence. Nothing changes from your side; this
+is about how the developer running instar catches their own mistakes
+before they reach you.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Pre-push upgrade-guide validation | automatic at git push time |
+
+## Evidence
+
+Four consecutive publish workflow runs failed silently between
+2026-05-14 05:00 and 2026-05-15 16:00 against the following commits on
+main: 529e0726, 97f90e4e, 79a2c0e8, 656360b5. All four were merged
+through pre-push with malformed NEXT.md, then dropped by the publish
+workflow's check-upgrade-guide.js step. No alert; the agent that needed
+to react never did.
+
+After this fix, the same malformed shapes are rejected at push time
+with the same error message the publish workflow would have produced.
+Verified by running the new integration tests:
+
+```
+npx vitest run tests/unit/pre-push-gate.test.ts
+✓ tests/unit/pre-push-gate.test.ts (10 tests) 2798ms
+  Test Files  1 passed (1)
+       Tests  10 passed (10)
+```
+
+The three known publish-blocker shapes (inline code in WTTYU, camelCase
+config in WTTYU, missing Evidence with fix-claim) are pinned by
+dedicated integration tests that spawn the actual gate script.

package/upgrades/side-effects/pre-push-upgrade-guide-validation.md

@@ -0,0 +1,126 @@
+# Side-Effects Review — Pre-Push Upgrade-Guide Validation
+
+**Version / slug:** `pre-push-upgrade-guide-validation`
+**Date:** `2026-05-15`
+**Author:** Echo (instar developer agent)
+**Second-pass reviewer:** required (touches a release-gate decision point)
+
+## Summary of the change
+
+Imports `validateGuideContent` from `scripts/upgrade-guide-validator.mjs` (the canonical validator already used by the publish-time `check-upgrade-guide.js`) and runs it inside `scripts/pre-push-gate.js`. Pre-push now rejects the same malformed upgrade-guide shapes that publish rejects, instead of letting them pass push and silently fail publish.
+
+Files touched:
+- `scripts/pre-push-gate.js` — adds import, runs `validateGuideContent` on the active guide, surfaces returned issues as errors. Removes the local section-presence + template-placeholder checks (now covered by the validator).
+- `tests/unit/pre-push-gate.test.ts` — adjusts the existing scaffolding tests (one shallow content-pattern check replaced with a check that the validator is imported). Adds 4 new integration tests that spawn the actual gate script against fixture NEXT.md files in a scratch directory and assert the right exit code + error message for each of the three publish-blocker shapes plus a well-formed control.
+
+Decision points the change interacts with: only one — the pre-push upgrade-guide gate. The validator is unchanged; this PR just makes pre-push consume it.
+
+## Decision-point inventory
+
+- `scripts/pre-push-gate.js` (push-time deterministic gate over upgrade-guide well-formedness) — **modify** — replaces narrow local rules with a call into the canonical shared validator. Same rules, same authority, now consistently enforced.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+None that wouldn't ALSO be rejected at publish time. The validator's rules are the same ones publishing already enforces — a release notes file that passes pre-push today but is well-formed enough for publish would NOT be newly rejected. A release notes file that is currently passing pre-push but would fail publish IS now rejected at push time. That's the intended over-block fix.
+
+Concrete check: I ran the gate against the live `upgrades/0.28.103.md` (which we cleaned and re-validated earlier today). Local gate reports zero validator-related errors. Other errors surface (e.g., missing side-effects artifact for v0.28.103, a pre-existing issue not introduced by this PR), but those are unrelated to the validator change.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Validator coverage gaps.** Only the rules currently in `validateGuideContent` are enforced — if new publish-blocker patterns emerge that aren't yet in the validator, neither gate catches them. Out of scope for this PR; surfaced as a follow-up to extend the validator rule set together with the next publish-blocker class.
+- **Manual side-effects artifact rename at release-cut time.** The existing `## 5 — Side-effects review artifact` block of the gate looks for an artifact filename matching `${version}.md` when the versioned guide is what's being validated. If NEXT.md is renamed to `${version}.md` but the artifact is not renamed to match, the gate rejects. This pre-existing behavior is unchanged by my PR; surfacing it here so a future PR can address.
+
+Neither is a regression introduced by this PR.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. `scripts/pre-push-gate.js` is the canonical home for push-time deterministic gates. `validateGuideContent` is the canonical authority over upgrade-guide well-formedness, shared with `check-upgrade-guide.js` at publish time. This PR is the smallest possible edge that makes the two gates consistent. No new layer; no relocation of existing logic.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [ ] No — this change has no block/allow surface.
+- [x] No — this change produces a signal consumed by an existing smart gate.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [ ] ⚠️ Yes, with brittle logic.
+
+The validator IS the authority — a deterministic ruleset over a constrained domain (markdown release notes). The pre-push gate is a consumer of that authority. The PR is a refactor that points the consumer at the canonical authority instead of a stale local copy. No new authority introduced; no brittle logic gains blocking power.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing**: the pre-push gate runs validate after section-presence (now collapsed into the same call) and before version-increment, side-effects-artifact, lint-no-direct-destructive, URL.pathname. All other checks unchanged.
+- **Double-fire**: the validator runs once at pre-push and once at publish. Pre-push catches malformed guides earlier; publish remains the authoritative final check. Double-fire is the intended design — push-time is a strict subset enforcer of publish-time.
+- **Races**: pre-push is single-process synchronous. No race surface.
+- **Adjacent cleanups**: existing scaffold tests in `pre-push-gate.test.ts` are adjusted, not removed. The integration tests use temp dirs cleaned up via `SafeFsExecutor.safeRmSync` per the lint-no-direct-destructive rule.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Other agents on the same machine** — no, this is a pre-push gate for the instar source repo. Agents don't push to instar; they only consume releases.
+- **Other users of the install base** — no, see above.
+- **External systems** — none.
+- **Persistent state** — none.
+- **Timing / runtime conditions** — the gate now runs validator code at push time. Validator runs synchronously in ~10ms; adds no perceptible latency.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+- **Hot-fix release**: revert `scripts/pre-push-gate.js` and `tests/unit/pre-push-gate.test.ts`, ship a patch. ~5 minutes.
+- **Data migration**: none.
+- **Agent state repair**: none.
+- **User visibility**: zero. The gate is a developer-facing pre-push check; users see nothing.
+
+---
+
+## Conclusion
+
+Pure scope-tightening of a pre-existing push-time gate to consume a pre-existing publish-time authority. No new decision logic, no new blocking surface, no new persistent state. The motivating incident (yesterday and this morning, multiple PRs stranded on main without reaching npm) is the explicit driver. Worst-case rollback is a two-file revert at ~5 minutes. Clear to ship pending second-pass concurrence.
+
+---
+
+## Second-pass review
+
+**Reviewer:** general-purpose subagent (Echo's review subagent)
+**Independent read of the artifact: concur**
+
+The validator-based check is structurally clean: both `pre-push-gate.js` and `check-upgrade-guide.js` import `validateGuideContent` from the same module and feed it `fs.readFileSync(activeGuide, 'utf-8')` — identical input shape, so push-time cannot over-reject relative to publish-time. The validator's REQUIRED_SECTIONS / template-placeholder rules subsume the removed local checks one-for-one; the only other consumer of the old "[Feature name]" / "[Capability]" / section-presence patterns in the gate source was this test file itself, and `tests/unit/upgrade-guide-finalization.test.ts` exercises those strings against the template (unrelated to the gate). Symlink-vs-copy analysis is correct: `lint-no-direct-destructive.js` resolves `ROOT` via `path.resolve(fileURLToPath(import.meta.url), '..', '..')` and Node's ESM loader collapses symlinks before module resolution, so a symlinked copy would scan the production worktree; `fs.copyFileSync` produces a sibling at `scratch/scripts/...` and ROOT correctly resolves to the scratch dir. `SafeFsExecutor.safeRmSync` is called with the correct `{recursive, force, operation}` shape (operation is the required label); scratch lives under `os.tmpdir()` so SourceTreeGuard won't intervene. Integration with the unmodified "Side-effects review artifact" step (gate §5) is consistent — both checks accumulate into the same `errors[]` and fire together. Signal-vs-authority: the validator remains the deterministic authority over a constrained domain (release-notes well-formedness, which falls under the "structural validators at the boundary" carve-out in `docs/signal-vs-authority.md`); the gate is a pure consumer surfacing existing decisions earlier in the workflow.
+
+Minor non-blocking notes (none block the ship):
+- `execSync` is imported at line 16 of the test file but no longer used (it was replaced by `spawnSync` on line 33). Dead import; cleanup-only.
+- The integration test for the third malformed case ("Fix the misbehavior...") triggers BOTH the missing-Evidence error AND the missing-side-effects-artifact error simultaneously; the assertion on "has no \"## Evidence\" section" still passes because both errors are appended to stdout, but if a future regression flipped the order or the artifact check moved earlier and short-circuited, the assertion might survive without exercising the validator path. Consider an additional fixture that has the side-effects artifact present but the Evidence section missing, to lock in the validator path independently.
+- The "ACCEPTS a well-formed NEXT.md" test uses "A small improvement" which doesn't trigger any FIX_PATTERNS — but the test still creates a `test-artifact.md` defensively. Comment in the test claims the gate requires the artifact for "add/new/feature/fix words", but "improvement" matches none of those. The artifact creation is unnecessary belt-and-suspenders, not load-bearing. Not a bug.
+
+---
+
+## Evidence pointers
+
+- Original failed publish runs visible in `gh run list -L 5 --workflow=publish.yml --status=failure` — four consecutive `failure` runs between 2026-05-14 05:00 and 2026-05-15 16:00 before the cleanup PR #228 unblocked publish.
+- Test verification: `npx vitest run tests/unit/pre-push-gate.test.ts` → 10/10 passed (4 new integration tests; one scaffold test re-shaped).
+- Manual verification: against three handcrafted malformed NEXT.md fixtures, the gate exits non-zero with the right error message; against a well-formed fixture, the gate exits zero.