instar 1.3.956 → 1.3.957

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.956",
+  "version": "1.3.957",
   "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/generate-spec-contract.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * Generate a spec's IMPLEMENTATION CONTRACT — the normative sections only,
+ * with the review history stripped out.
+ *
+ * Why this exists (outbound-gate-advisory-override rounds 22/23/24): a spec that
+ * records its own review honestly accumulates change logs describing designs that
+ * were REVERSED. Both external reviewers independently named the same risk — an
+ * implementer cargo-culting a retired term out of a change log — and the same
+ * fix: publish the contract separately from the history.
+ *
+ * The rule is deliberately dumb and mechanical: everything up to the first
+ * history heading is the contract; everything from there on is history. A
+ * generator that had to understand the document would drift like the document.
+ *
+ * Usage:
+ *   node scripts/generate-spec-contract.mjs --spec docs/specs/<slug>.md
+ *   node scripts/generate-spec-contract.mjs --spec <path> --check   # CI: fail if stale
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** A heading that begins the review-history half. Matched case-insensitively. */
+const HISTORY_HEADING_RE = /^##\s+(?:\d+\.\s+)?(?:Round-\d+\b[^\n]*?(?:change log|hand-check|consistency sweep)|Appendix\b)/i;
+
+/** Headings that are contract even though they sort after a history heading. */
+const ALWAYS_CONTRACT_RE = /^##\s+(?:\d+\.\s+)?(?:Decision points touched|Open questions|Frontloaded Decisions|Dependencies|Honest limits|Multi-machine posture|What this does not do)/i;
+
+/**
+ * Inline review annotations inside NORMATIVE prose — "(round-12, codex — ...)",
+ * "*(Round-25, codex: ...)*". They are provenance, not contract. Both external
+ * reviewers named them as the reason §§0-11 still read as history (rounds 24/25).
+ * Stripped from the generated contract; untouched in the source spec, where they
+ * are the record of why a decision is what it is.
+ *
+ * Deliberately conservative: only fully-delimited groups are removed, so a
+ * malformed annotation is left visible rather than silently eating prose.
+ */
+const INLINE_ANNOTATION_RES = [
+  // *( Round-N ... )* — a complete italic aside
+  /\*\((?:round|rounds)[- ]\d+[^()*]*\)\*/gi,
+  // ( round-N, reviewer — ... ) — a complete parenthetical with no nesting
+  /\s*\((?:round|rounds)[- ]\d+[^()]*\)/gi,
+  // — round-N, codex …  (an em-dash aside running to the end of a sentence)
+  /\s+—\s+(?:round|rounds)[- ]\d+,[^.;]*(?=[.;])/gi,
+];
+
+export function stripInlineAnnotations(text) {
+  let out = text;
+  for (const re of INLINE_ANNOTATION_RES) out = out.replace(re, '');
+  // Collapse the double spaces a removal can leave mid-sentence.
+  return out.replace(/[ \t]{2,}/g, ' ').replace(/ +([.,;:])/g, '$1');
+}
+
+export function splitContract(markdown) {
+  const lines = markdown.split('\n');
+  const kept = [];
+  let inHistory = false;
+  let droppedSections = 0;
+  for (const line of lines) {
+    if (/^##\s/.test(line)) {
+      if (HISTORY_HEADING_RE.test(line) && !ALWAYS_CONTRACT_RE.test(line)) {
+        if (!inHistory) inHistory = true;
+        droppedSections++;
+        continue;
+      }
+      // A non-history H2 ends a history run (sections are not strictly ordered).
+      inHistory = false;
+    }
+    if (!inHistory) kept.push(line);
+  }
+  const body = stripInlineAnnotations(kept.join('\n')).replace(/\n{4,}/g, '\n\n\n');
+  return { contract: body, droppedSections };
+}
+
+/** The banner that makes the generated file unmistakable and un-editable-by-hand. */
+function banner(specRel) {
+  return [
+    '<!-- GENERATED FILE — DO NOT EDIT.',
+    `     Source: ${specRel}`,
+    '     Regenerate: node scripts/generate-spec-contract.mjs --spec ' + specRel,
+    '     This is the IMPLEMENTATION CONTRACT: the normative design only.',
+    '     Review history (change logs, retired designs, reversed decisions) is',
+    '     deliberately absent — read the source spec for how the design got here.',
+    '-->',
+    '',
+  ].join('\n');
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const specIdx = args.indexOf('--spec');
+  if (specIdx === -1 || !args[specIdx + 1]) {
+    console.error('usage: generate-spec-contract.mjs --spec <path> [--check]');
+    process.exit(2);
+  }
+  const specPath = path.resolve(args[specIdx + 1]);
+  const check = args.includes('--check');
+  const specRel = path.relative(process.cwd(), specPath);
+
+  const markdown = fs.readFileSync(specPath, 'utf8');
+  const { contract, droppedSections } = splitContract(markdown);
+  const output = banner(specRel) + contract;
+
+  const slug = path.basename(specPath, '.md');
+  const outPath = path.join(path.dirname(specPath), 'generated', `${slug}.contract.md`);
+
+  if (check) {
+    if (!fs.existsSync(outPath)) {
+      console.error(`STALE: ${path.relative(process.cwd(), outPath)} does not exist. Run without --check.`);
+      process.exit(1);
+    }
+    const existing = fs.readFileSync(outPath, 'utf8');
+    if (existing !== output) {
+      console.error(
+        `STALE: ${path.relative(process.cwd(), outPath)} does not match ${specRel}.\n` +
+          'The contract is generated — regenerate it rather than editing it.',
+      );
+      process.exit(1);
+    }
+    console.log(`OK: contract is current (${droppedSections} history sections excluded).`);
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, output, 'utf8');
+  const pct = Math.round((1 - output.length / markdown.length) * 100);
+  console.log(
+    `wrote ${path.relative(process.cwd(), outPath)} — ${droppedSections} history sections excluded, ${pct}% smaller.`,
+  );
+}
+
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('generate-spec-contract.mjs')) {
+  main();
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-25T08:37:37.023Z",
-  "instarVersion": "1.3.956",
+  "generatedAt": "2026-07-25T09:37:20.372Z",
+  "instarVersion": "1.3.957",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.957.md

@@ -0,0 +1,54 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added `scripts/generate-spec-contract.mjs` — a build-time generator that emits
+`docs/specs/generated/<slug>.contract.md` from a spec: the normative sections
+only, with review-history sections and inline round-annotations stripped.
+
+**Why.** A spec that honestly records its review accumulates change logs
+describing designs that were later *reversed*. On
+`outbound-gate-advisory-override` (33 review rounds), both external reviewers —
+`codex-cli:gpt-5.5` and `gemini-cli:gemini-3.1-pro-preview` — independently
+identified the same risk and proposed the same fix: an implementer reading the
+document top-to-bottom can follow a retired design, so publish the contract
+separately from the history.
+
+`--check` fails the build when the committed contract does not match a fresh
+generation, so the history cannot drift back into the contract over time.
+
+The transform is deliberately mechanical — heading shapes mark history,
+everything else is contract. A generator that had to *understand* the document
+would drift out of step with it exactly as the document drifted out of step with
+itself.
+
+No runtime surface: no `src/` change, nothing installed to agent homes, no hook,
+job or template references it. Nothing at runtime reads a spec.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- Generated against the real 2,700-line spec: **36 history sections excluded,
+  37% smaller output**.
+- `--check` verified in both directions: exits 0 on a current contract, exits 1
+  with a regenerate message on a stale one.
+- A regex leak was found and fixed during verification — `## 24. Round-11
+  external change log` was initially retained, because the heading text between
+  `Round-11` and `change log` was not matched. Caught by inspecting the generated
+  headings rather than trusting the run.
+- Determinism confirmed by construction: no timestamps, no randomness, no
+  environment reads beyond the input path — which is what makes `--check` usable
+  in CI at all.
+- Side-effects review: `upgrades/side-effects/spec-contract-generator.md`
+  (Tier 1; no decision point, no blocking authority, rollback is deleting two
+  files).

package/upgrades/side-effects/spec-contract-generator.md

@@ -0,0 +1,126 @@
+# Side-effects review — spec contract generator
+
+**Change:** adds `scripts/generate-spec-contract.mjs`, a build-time generator that
+produces `docs/specs/generated/<slug>.contract.md` from a spec: the normative
+sections only, with review history and inline round-annotations stripped.
+
+**Tier:** 1 (declared). New standalone dev-tooling script; no runtime surface, no
+`src/` change, no decision point. Signal-only in the strongest sense — it emits a
+derived document and can refuse a stale check; it gates no agent behavior.
+
+**Why it exists:** on the `outbound-gate-advisory-override` spec, both external
+reviewers (codex-cli, gemini-cli) independently identified the same risk across
+several rounds — a spec that honestly records 33 rounds of review accumulates
+change logs describing designs that were later **reversed**, and an implementer
+reading top-to-bottom can follow a retired design. Both proposed the same fix:
+publish the contract separately from the history.
+
+---
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+
+The generator's only refusal is `--check` failing when the committed contract does
+not byte-match a fresh generation. That is the intended behavior (CI staleness
+gate), and it is refusable-by-regeneration, not by argument.
+
+**Real over-block risk identified:** the history-heading regex could classify a
+*normative* section as history if someone titles one `## Round-trip validation` or
+similar. Mitigated by requiring both a `Round-N` prefix **and** one of
+`change log` / `hand-check` / `consistency sweep`, plus an `ALWAYS_CONTRACT_RE`
+allowlist for the known normative section names. A false positive drops a section
+from the generated contract — visible immediately as a missing section, not
+silent.
+
+## 2. Under-block — what does it still miss?
+
+- **Narrative history inside normative prose.** The generator strips history
+  *sections* and *inline annotations*; it cannot strip a paragraph of normative
+  prose that happens to narrate how a decision evolved. Those remain in the
+  contract. Partially addressed by the spec's own §0.2 "current design overview";
+  fully addressing it would require judgment the generator deliberately does not
+  have.
+- **It does not verify the contract is CORRECT** — only that it is current. A
+  spec that is internally contradictory generates a contract that is equally
+  contradictory. The separate spec lint (required by the outbound spec) is what
+  addresses that; this is not it.
+
+## 3. Level-of-abstraction fit
+
+Correct layer: it is a build-time document transform, alongside the other
+`scripts/*.mjs` spec tooling (`write-convergence-tag.mjs`,
+`eli16-overview-check.mjs`, `publish-spec-review.mjs`). It does not belong in
+`src/` — nothing at runtime reads a spec.
+
+**Should a higher layer own it?** `/spec-converge` could invoke it automatically
+on convergence. Deliberately not wired that way in this change: the generator
+should prove itself as a standalone tool first, and auto-invocation is a change to
+the skill's contract, not to this script. Not deferred-and-forgotten — it is
+simply not part of this change's scope, and the script is useful without it.
+
+## 4. Signal vs authority compliance
+
+**Compliant, trivially.** The script holds no authority over agent behavior. Its
+one enforcement surface (`--check` exiting non-zero) is a build-time staleness
+assertion on a *derived artifact*, with a deterministic remedy (regenerate). It
+makes no judgment, consults no model, and gates no message, session, or action.
+
+## 5. Interactions
+
+- **Shadows nothing.** No existing script generates or validates a spec contract.
+- **Shadowed by nothing.** It reads a spec and writes a derived file under
+  `docs/specs/generated/`, a path nothing else writes.
+- **No double-fire, no race.** Single-shot CLI; no daemon, no watcher, no
+  scheduling.
+- **Adjacent tooling unaffected:** `write-convergence-tag.mjs` and
+  `eli16-overview-check.mjs` read the *source* spec; this writes only the
+  generated copy. `hashSpecReviewableBody` (used for cross-model delta-gating)
+  also reads the source, so generated files never affect review gating.
+
+## 6. External surfaces
+
+- **Other agents / users:** none. Dev tooling in the instar repo; not installed to
+  agent homes, not referenced by any hook, job, or template.
+- **Timing / runtime conditions:** none — pure file in, file out.
+- **New file paths introduced:** `docs/specs/generated/`. Additive; no existing
+  path changes meaning.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN, and trivially so:** the script runs in a developer's
+checkout and writes a file into that checkout, which is then committed and
+distributed by git like any other source file. There is no runtime state, no
+per-machine store, no notice, and no generated URL. Running it on two machines
+against the same spec produces byte-identical output (the transform is pure and
+deterministic — no timestamps, no randomness, no environment reads beyond the
+input path).
+
+That determinism is what makes the `--check` mode usable in CI at all, and it is
+asserted by the mode's existence: if the transform were machine-sensitive, CI
+would fail against a contract generated on a developer's machine.
+
+## 8. Rollback cost
+
+**Near zero.** Delete the script and the generated directory; nothing depends on
+either. No release, no migration, no agent-state repair. If the `--check` mode
+turns out to be a nuisance in CI, it can be dropped independently of the
+generator (the generator is useful without the check; the check is not useful
+without the generator).
+
+---
+
+## Verification performed
+
+- Generated against the real 2,700-line spec: 36 history sections excluded, 37%
+  smaller output.
+- `--check` verified in both directions: passes on a current contract, fails with
+  a clear message on a stale one.
+- Regex leak found and fixed during verification (`## 24. Round-11 external
+  change log` was initially retained because the heading text between `Round-11`
+  and `change log` was not matched) — caught by inspecting the generated
+  headings rather than trusting the run.
+
+## Second pass
+
+**Not required.** The change touches no block/allow decision, no session
+lifecycle, no coherence gate, and nothing named sentinel/guard/gate/watchdog. It
+is a standalone document transform.