instar 1.3.258 → 1.3.259

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.258",
+  "version": "1.3.259",
   "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/eli16-pr-description-check.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * ELI16-on-every-PR gate (team standard, 2026-06-05).
+ *
+ * Every PR's DESCRIPTION must carry a plain-English ELI16 overview — because the
+ * PR description is what a reviewer reads and approves when they open the link.
+ * The ELI16 *file* (docs/specs/<slug>.eli16.md) remains the durable companion;
+ * this gate enforces that the OVERVIEW is also in the PR BODY so it is front and
+ * centre at review time. (Justin, 2026-06-05: "when I click on the link, that's
+ * what I'm going to see and read and approve.")
+ *
+ * Pure check — `checkPrDescriptionEli16({ body, title, authorType })` — plus a
+ * CLI wrapper that reads PR_BODY / PR_TITLE / PR_AUTHOR_TYPE from env (set by the
+ * workflow) and exits 0 when an ELI16 overview is present (or the PR is exempt),
+ * 1 with actionable guidance when it is missing.
+ */
+
+/** Minimum plain-English content under the ELI16 heading — a real overview, not a one-liner. */
+export const MIN_ELI16_DESCRIPTION_CHARS = 200;
+
+/** A markdown heading (any level) whose text contains "ELI16" / "ELI-16" / "ELI 16". */
+const ELI16_HEADING = /^[ \t]*#{1,6}[ \t]+.*ELI[ \t-]?16/im;
+
+/**
+ * @param {{ body?: string|null, title?: string|null, authorType?: string|null }} pr
+ * @returns {{ ok: boolean, exempt?: string, reason?: string, chars?: number, min?: number }}
+ */
+export function checkPrDescriptionEli16(pr) {
+  const title = String(pr?.title ?? '');
+  // Exempt the genuinely-automated PRs: bot authors + the release-cut commit.
+  if (String(pr?.authorType ?? '') === 'Bot') return { ok: true, exempt: 'bot-author' };
+  if (/^chore:\s*release\b/i.test(title)) return { ok: true, exempt: 'release-cut' };
+
+  const body = String(pr?.body ?? '');
+  const m = ELI16_HEADING.exec(body);
+  if (!m) return { ok: false, reason: 'no-eli16-heading' };
+
+  // Content under the ELI16 heading, up to the next heading.
+  const after = body.slice(m.index + m[0].length);
+  const section = after.split(/\n[ \t]*#{1,6}[ \t]/)[0];
+  const content = section.replace(/<!--[\s\S]*?-->/g, '').trim();
+  if (content.length < MIN_ELI16_DESCRIPTION_CHARS) {
+    return { ok: false, reason: 'eli16-too-short', chars: content.length, min: MIN_ELI16_DESCRIPTION_CHARS };
+  }
+  return { ok: true };
+}
+
+// ── CLI (used by .github/workflows/eli16-pr-gate.yml) ─────────────────
+const invokedDirectly =
+  process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href;
+if (invokedDirectly) {
+  const res = checkPrDescriptionEli16({
+    body: process.env.PR_BODY,
+    title: process.env.PR_TITLE,
+    authorType: process.env.PR_AUTHOR_TYPE,
+  });
+  if (res.ok) {
+    console.log(
+      res.exempt
+        ? `ELI16 gate: exempt (${res.exempt}).`
+        : 'ELI16 gate: OK — the PR description includes an ELI16 overview.',
+    );
+    process.exit(0);
+  }
+  const detail =
+    res.reason === 'eli16-too-short'
+      ? ` (found an ELI16 heading but only ${res.chars} chars of content; need >= ${res.min}).`
+      : '.';
+  console.error(
+    `ELI16 gate FAILED: this PR's description has no plain-English ELI16 overview${detail}\n\n` +
+      `Team standard (2026-06-05): every PR description must include an "## ELI16 — <one line>" section ` +
+      `that explains the change for a non-expert — because the PR description is what the reviewer reads ` +
+      `and approves when they open the link. Add it to the PR body (copy from your ` +
+      `docs/specs/<slug>.eli16.md companion). Edit the PR description and this check will re-run.`,
+  );
+  process.exit(1);
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-05T00:43:50.058Z",
-  "instarVersion": "1.3.258",
+  "generatedAt": "2026-06-05T00:47:15.893Z",
+  "instarVersion": "1.3.259",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.259.md

@@ -0,0 +1,32 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added a CI gate (`.github/workflows/eli16-pr-gate.yml` + the pure check
+`scripts/eli16-pr-description-check.mjs`) that requires every PR's DESCRIPTION to carry a
+plain-English ELI16 overview, and FAILS the PR when it is missing. Per Justin's standard
+(2026-06-05): the PR description is what a reviewer reads and approves on the link, and the PRs "had
+different formats." The ELI16 *file* (docs/specs/<slug>.eli16.md) is unchanged and still enforced at
+commit time; this closes the PR-body half. Re-runs on `edited` (self-clears on a description fix);
+exempts bot authors + the automated release-cut PR.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- The decision is a PURE function (`checkPrDescriptionEli16`) with 10 unit tests covering both
+  sides (has-overview → pass; missing / too-short / next-heading-boundary / comment-stripped → fail)
+  and every exemption (bot, release-cut, title-mentions-release non-exemption, null inputs).
+- `node --check scripts/eli16-pr-description-check.mjs` clean. New additive workflow — cannot affect
+  existing checks/builds/releases; a failing PR is visible + self-clears on a description edit.
+- This PR's own description carries an ELI16 overview (dogfoods the gate). scripts + workflow + test
+  only, no `src/` (internal-only lane).

package/upgrades/side-effects/eli16-pr-description-gate.md

@@ -0,0 +1,48 @@
+# Side-Effects Review — ELI16-on-every-PR gate (PR description)
+
+**Version / slug:** `eli16-pr-description-gate`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `required (a new gate that blocks EVERY PR)`
+
+## Summary
+
+Justin's standard (2026-06-05): every PR's DESCRIPTION must carry a plain-English ELI16 overview,
+because the description is what a reviewer reads and approves when they open the PR link — and the
+current PRs "have different formats." This adds a CI gate (`.github/workflows/eli16-pr-gate.yml`)
+that runs a pure check (`scripts/eli16-pr-description-check.mjs`) on every PR body and FAILS the PR
+when no ELI16 overview is present. The ELI16 *file* (`docs/specs/<slug>.eli16.md`) is unchanged and
+still enforced at commit time by the instar-dev gate; this is the missing PR-body half.
+
+## Decision-point inventory
+
+One decision: does the PR body contain an ELI16 overview? PASS when (a) the author is a Bot, or
+(b) the title is a `chore: release` cut, or (c) the body has a heading whose text contains
+`ELI16`/`ELI-16`/`ELI 16` followed by >= 200 chars of (comment-stripped) content. Otherwise FAIL.
+
+## 1. Over-block (what it blocks)
+
+A human/agent PR whose description lacks a real ELI16 overview is blocked — that's the point. The
+check re-runs on `edited`, so adding the overview to the description clears it WITHOUT a new push.
+The failure message is actionable (tells you exactly what to add + that the file is a good source).
+
+## 2. Under-block (what it lets through)
+
+Bot PRs and the automated `chore: release` PR (which has no human reviewer reading an ELI16). A PR
+that has a real ELI16 heading + >= 200 chars passes. The check measures content only up to the next
+heading, so a one-line ELI16 followed by a long "What Changed" does NOT slip through (tested).
+
+## 3. Blast radius — CRITICAL
+
+This gate blocks EVERY non-exempt PR, so a false-fail would block the whole fleet's PRs. Mitigations:
+the decision is a PURE function with 10 unit tests covering both sides AND every exemption (bot,
+release-cut, the "title mentions release" non-exemption, null/empty inputs, the next-heading
+boundary, comment-stripping). The gate is a NEW, additive workflow — it cannot affect existing
+checks, builds, or releases; a failing PR is VISIBLE and self-clears on a description edit (not a
+silent jam like the manifest/publish class). No `src/` runtime change.
+
+## 4. Reversibility
+
+Fully reversible: delete the workflow + script + test. No state, no migration. Verified: the check
+script parses (`node --check`); 10/10 unit tests pass. This PR's own description carries an ELI16
+overview (dogfoods the gate).