instar 1.3.475 → 1.3.477

package/dist/core/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAq3CH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA8C;IAC3E,cAAc,EAAE,UAAU;IAC1B,gBAAgB,EAAE,eAAe;IACjC,mBAAmB,EAAE,UAAU;IAC/B,aAAa,EAAE,eAAe;IAC9B,aAAa,EAAE,eAAe;IAC9B,aAAa,EAAE,eAAe;CAC/B,CAAC;AAmxGF,gFAAgF;AAChF,MAAM,CAAC,MAAM,+BAA+B,GAAG,EAAE,CAAC;AAClD,mDAAmD;AACnD,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAC/C,sCAAsC;AACtC,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAC3C,kEAAkE;AAClE,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAq3CH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA8C;IAC3E,cAAc,EAAE,UAAU;IAC1B,gBAAgB,EAAE,eAAe;IACjC,mBAAmB,EAAE,UAAU;IAC/B,aAAa,EAAE,eAAe;IAC9B,aAAa,EAAE,eAAe;IAC9B,aAAa,EAAE,eAAe;CAC/B,CAAC;AA6xGF,gFAAgF;AAChF,MAAM,CAAC,MAAM,+BAA+B,GAAG,EAAE,CAAC;AAClD,mDAAmD;AACnD,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAC/C,sCAAsC;AACtC,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAC3C,kEAAkE;AAClE,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.475",
+  "version": "1.3.477",
   "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/instar-dev-precommit.js

@@ -31,6 +31,15 @@ import { fileURLToPath } from 'node:url';
 import { checkEli16Overview, MIN_ELI16_CHARS } from './eli16-overview-check.mjs';
 import { verifyProposalDerivedRunbooks } from '../skills/instar-dev/scripts/verify-proposal-derived-runbook.mjs';
 import { classifyTier, decideRequirementSet } from './lib/classify-tier.mjs';
+import { recognizeConvergence } from './lib/convergence-recognition.mjs';
+
+// Report-Backed Converging Audit (docs/specs/CONVERGING-AUDIT-DEFAULT.md, Part B).
+// The precommit reads NO config file and runs pre-compile, so it cannot import
+// the TS config loader. The flag specReview.requireConvergenceReport is threaded
+// in as an ENV VAR by the .husky/pre-commit hook, mirroring the existing in-file
+// INSTAR_DEV_ALLOW_ORPHAN_DEFERRALS pattern. When unset, the new report-backing
+// branch never runs → byte-identical to today's precommit behavior.
+const REQUIRE_CONVERGENCE_REPORT = process.env.INSTAR_DEV_REQUIRE_CONVERGENCE_REPORT === '1';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -521,10 +530,34 @@ if (!specFmMatch) {
   );
 }
 const specFm = specFmMatch[1];
-const convergenceMatch = specFm.match(/^\s*review-convergence\s*:\s*["']?([^"'\n]+)/m);
-const approvedMatch = specFm.match(/^\s*approved\s*:\s*(true|"true"|'true')/m);
 
-if (!convergenceMatch) {
+// Convergence / approval / report recognition is factored into a pure,
+// dependency-free module (scripts/lib/convergence-recognition.mjs) that a unit
+// test cross-checks against the TS validator's `isConvergenceTagPresent` —
+// keeping the two gates in agreement (CONVERGING-AUDIT-DEFAULT.md, Part C). The
+// report-existence input depends on the spec's slug + the env flag, computed
+// just below; the recognizer does no I/O of its own.
+
+// Slug → report path, matching StageTransitionValidator's derivation exactly.
+const specSlugMatch = specFm.match(/^\s*slug\s*:\s*["']?([a-z0-9][a-z0-9-]{0,63})["']?\s*$/m);
+const specSlug = specSlugMatch ? specSlugMatch[1] : '';
+const convergenceReportRel = specSlug
+  ? path.join('docs/specs/reports', `${specSlug}-convergence.md`)
+  : '';
+// Only probe the filesystem when the report requirement is actually on. With
+// the flag unset, reportExists stays false but is never consulted (the
+// recognizer's reportBacked is vacuously true), so this branch is byte-inert.
+const convergenceReportExists =
+  REQUIRE_CONVERGENCE_REPORT && convergenceReportRel
+    ? fs.existsSync(path.resolve(ROOT, convergenceReportRel))
+    : false;
+
+const recognition = recognizeConvergence(specFm, {
+  requireReport: REQUIRE_CONVERGENCE_REPORT,
+  reportExists: convergenceReportExists,
+});
+
+if (!recognition.converged) {
   blockCommit(
     inScopeFiles,
     [
@@ -534,7 +567,7 @@ if (!convergenceMatch) {
   );
 }
 
-if (!approvedMatch) {
+if (!recognition.approved) {
   blockCommit(
     inScopeFiles,
     [
@@ -545,6 +578,35 @@ if (!approvedMatch) {
   );
 }
 
+// ── Report-backing (Part B — dark, env-gated) ──
+// When INSTAR_DEV_REQUIRE_CONVERGENCE_REPORT=1, a converged + approved spec must
+// ALSO have its converging-audit report on disk (proving the audit RAN, not just
+// that a tag was added). This brings the precommit UP to the formal validator's
+// strictness (which requires the report unconditionally). With the env unset,
+// recognition.reportBacked is always true and this branch never blocks.
+if (!recognition.reportBacked) {
+  blockCommit(
+    inScopeFiles,
+    [
+      `Spec ${spec} is tagged review-convergence + approved, but its converging-audit`,
+      `report is missing: ${convergenceReportRel || '(spec has no valid slug to locate a report)'}`,
+      '',
+      'INSTAR_DEV_REQUIRE_CONVERGENCE_REPORT is on (specReview.requireConvergenceReport:',
+      'true) — a convergence tag without its report can fake convergence. The report is',
+      'the audit\'s proof-of-work; run /spec-converge to produce it (Phase 5 writes',
+      `docs/specs/reports/<slug>-convergence.md), then commit. To turn this requirement`,
+      'off, set specReview.requireConvergenceReport: false in your instar config.',
+    ].join('\n'),
+  );
+}
+
+// ── Part D: surface cross-model-review depth (observe-only, never blocks) ──
+// The converging audit records how much external (cross-model) review actually
+// ran. Surfacing it here makes the audit's depth visible to the operator/agent
+// reading the gate output, without ever gating on it (Signal vs. Authority).
+const crossModelMatch = specFm.match(/^\s*cross-model-review\s*:\s*["']?([^"'\n]+)/m);
+const crossModelReview = crossModelMatch ? crossModelMatch[1].trim() : 'not-recorded';
+
 // ─── Step 7: ELI16 overview verification ─────────────────────────────────
 // Every approved spec must ship with a plain-English ELI16 overview. The
 // overview is the entry point for any reader who has to make a real decision
@@ -824,7 +886,9 @@ if (!promotionGateResult.ok) {
 assertFrameworkGenerality(inScopeFiles, validTrace.trace);
 
 console.error(
-  `[instar-dev-precommit] OK — trace ${path.basename(validTrace.entry.file)} covers ${inScopeFiles.length} in-scope file(s), artifact ${validTrace.trace.artifactPath} verified, spec ${spec} is converged + approved, ELI16 overview ${eli16Rel} present (${eli16Result.charCount} chars), promotion-gate: ${promotionGateResult.reason}.`,
+  `[instar-dev-precommit] OK — trace ${path.basename(validTrace.entry.file)} covers ${inScopeFiles.length} in-scope file(s), artifact ${validTrace.trace.artifactPath} verified, spec ${spec} is converged + approved` +
+    `${REQUIRE_CONVERGENCE_REPORT ? ` + report-backed (${convergenceReportRel})` : ''}` +
+    ` [cross-model: ${crossModelReview}], ELI16 overview ${eli16Rel} present (${eli16Result.charCount} chars), promotion-gate: ${promotionGateResult.reason}.`,
 );
 process.exit(0);
 

package/scripts/lib/convergence-recognition.mjs

@@ -0,0 +1,126 @@
+/**
+ * convergence-recognition.mjs — the PRECOMMIT gate's pure recognizer for a
+ * spec's convergence / approval / report-backing state.
+ *
+ * Spec: docs/specs/CONVERGING-AUDIT-DEFAULT.md (Part C — gate consistency).
+ *
+ * WHY a separate pure module: the precommit (scripts/instar-dev-precommit.js)
+ * runs PRE-COMPILE and CANNOT import the TS StageTransitionValidator across the
+ * compile boundary, so the two gates cannot share a single source of truth in
+ * code. Instead, the precommit's recognition logic is factored HERE, into a
+ * tiny dependency-free function, and a unit test
+ * (tests/unit/convergence-gate-consistency.test.ts) feeds the SAME fixture
+ * table to both this recognizer and the validator's `isConvergenceTagPresent`
+ * + report logic, asserting they agree. A drift between the two gates fails CI.
+ *
+ * This module does NO I/O: callers pass the frontmatter text and the
+ * report-existence boolean. It is the precommit-side mirror of the validator's
+ * pure predicate — same convergence-tag rule (non-empty string OR boolean
+ * true), same report-backing rule (report must exist when required).
+ */
+
+/**
+ * Recognize the convergence tag in a `review-convergence` frontmatter VALUE.
+ *
+ * Mirror of StageTransitionValidator.isConvergenceTagPresent: a non-empty
+ * string (the ISO timestamp the converging-audit tooling writes) OR boolean
+ * `true` (the legacy/hand-added form) counts as present. Empty string, false,
+ * null/undefined, and any other type do NOT.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isConvergenceTagPresent(value) {
+  if (value === true) return true;
+  if (typeof value === 'string' && value.trim().length > 0) return true;
+  return false;
+}
+
+/**
+ * Parse the raw `review-convergence` value out of a YAML frontmatter BLOCK
+ * (the text between the `---` fences, NOT including the fences). Mirrors the
+ * precommit's existing lenient regex exactly so recognition stays identical.
+ *
+ * Returns the matched string value (quotes stripped, trimmed) when the line is
+ * present, or `undefined` when the key is absent. Note: this returns a STRING
+ * for both `review-convergence: true` and `review-convergence: "<ts>"` — the
+ * precommit's regex captures the literal token; `isConvergenceTagPresent`
+ * treats any non-empty captured token as present, which matches the validator's
+ * acceptance of both the boolean-true and timestamp-string forms.
+ *
+ * @param {string} frontmatterText
+ * @returns {string | undefined}
+ */
+export function parseConvergenceValue(frontmatterText) {
+  const m = String(frontmatterText).match(
+    /^\s*review-convergence\s*:\s*["']?([^"'\n]+)/m,
+  );
+  if (!m) return undefined;
+  return m[1].trim();
+}
+
+/**
+ * Parse whether the spec carries an `approved: true` tag (precommit's regex).
+ *
+ * @param {string} frontmatterText
+ * @returns {boolean}
+ */
+export function isApprovedTagPresent(frontmatterText) {
+  return /^\s*approved\s*:\s*(true|"true"|'true')/m.test(String(frontmatterText));
+}
+
+/**
+ * The precommit's verdict for "is this spec converged + approved (+ report-backed
+ * when required)?" — the same question the formal validator answers, expressed
+ * over frontmatter text + a report-existence boolean.
+ *
+ * @param {string} frontmatterText — the YAML frontmatter block (between the `---` fences).
+ * @param {{ requireReport?: boolean, reportExists?: boolean }} [opts]
+ *   requireReport — true when INSTAR_DEV_REQUIRE_CONVERGENCE_REPORT=1.
+ *   reportExists  — whether docs/specs/reports/<slug>-convergence.md exists.
+ * @returns {{ converged: boolean, approved: boolean, reportBacked: boolean,
+ *             accepted: boolean, reason: string }}
+ *   - converged:    the convergence tag is present.
+ *   - approved:     the approved tag is present.
+ *   - reportBacked: the report requirement is satisfied (vacuously true when
+ *                   requireReport is false).
+ *   - accepted:     converged AND approved AND reportBacked — the precommit's
+ *                   Step-6 verdict for a tier-2/3 spec.
+ *   - reason:       a short machine-stable reason for the verdict.
+ */
+export function recognizeConvergence(frontmatterText, opts = {}) {
+  const requireReport = opts.requireReport === true;
+  const reportExists = opts.reportExists === true;
+
+  const convergenceValue = parseConvergenceValue(frontmatterText);
+  const converged = isConvergenceTagPresent(convergenceValue);
+  const approved = isApprovedTagPresent(frontmatterText);
+  const reportBacked = !requireReport || reportExists;
+
+  let reason;
+  if (!converged) reason = 'convergence-tag-missing';
+  else if (!approved) reason = 'approved-tag-missing';
+  else if (!reportBacked) reason = 'convergence-report-missing';
+  else reason = 'accepted';
+
+  const accepted = converged && approved && reportBacked;
+  return { converged, approved, reportBacked, accepted, reason };
+}
+
+/**
+ * Convenience: the precommit-side answer to "is this spec CONVERGED?" in the
+ * exact sense the consistency test compares against the validator's converged
+ * verdict (convergence tag present AND report-backed when required). Approval
+ * is a separate downstream gate in BOTH paths, so it is NOT folded in here.
+ *
+ * @param {string} frontmatterText
+ * @param {{ requireReport?: boolean, reportExists?: boolean }} [opts]
+ * @returns {boolean}
+ */
+export function isSpecConverged(frontmatterText, opts = {}) {
+  const requireReport = opts.requireReport === true;
+  const reportExists = opts.reportExists === true;
+  const converged = isConvergenceTagPresent(parseConvergenceValue(frontmatterText));
+  const reportBacked = !requireReport || reportExists;
+  return converged && reportBacked;
+}

package/scripts/lib/throwaway-identity.mjs

@@ -0,0 +1,150 @@
+/**
+ * throwaway-identity.mjs — mint genuinely-distinct, readable throwaway email
+ * identities for live-integration test harnesses (Slack, Discord, …).
+ *
+ * Backed by the mail.tm public disposable-mailbox API. Each minted inbox is a
+ * real, distinct, readable address — so a live test can use N of them as N
+ * GENUINELY DISTINCT principals (distinct addresses → distinct provider user
+ * IDs) with ZERO real accounts. This is the autonomous half of the
+ * test-identity provisioning the Live Integration Security-Test Harness needs;
+ * the only step it does NOT cover is an anti-bot signup CAPTCHA at workspace/
+ * account creation, which is a deliberate human-verification control (see
+ * docs/specs/JUDGMENT-PERMISSION-LIVE-RUN-RUNBOOK.md).
+ *
+ * Pure helpers (extractCode/extractLink/matchMessage) and HTTP helpers with an
+ * injectable `fetchImpl` so the unit test runs fully hermetic (no network).
+ *
+ * CLI: scripts/throwaway-identity.mjs (mint | wait). This file is the importable
+ * library; the CLI is a thin wrapper.
+ */
+
+const DEFAULT_API_BASE = 'https://api.mail.tm';
+
+/** Extract the first verification code (default: a 6-digit run) from a message body. */
+export function extractCode(text, { pattern = /\b(\d{6})\b/ } = {}) {
+  if (typeof text !== 'string') return null;
+  const m = text.match(pattern);
+  return m ? (m[1] ?? m[0]) : null;
+}
+
+/** Extract the first URL (optionally matching a substring/regex) from a message body. */
+export function extractLink(text, { match } = {}) {
+  if (typeof text !== 'string') return null;
+  const urls = text.match(/https?:\/\/[^\s"'<>)\]]+/g) || [];
+  if (!match) return urls[0] ?? null;
+  const test = match instanceof RegExp ? (u) => match.test(u) : (u) => u.includes(match);
+  return urls.find(test) ?? null;
+}
+
+/** Does a mail.tm message summary match the caller's filter (subject/from substring or regex)? */
+export function matchMessage(msg, { subject, from } = {}) {
+  if (!msg) return false;
+  const subjOk = matchField(msg.subject, subject);
+  const fromAddr = (msg.from && (msg.from.address || msg.from.name)) || '';
+  const fromOk = matchField(fromAddr, from);
+  return subjOk && fromOk;
+}
+
+function matchField(value, filter) {
+  if (filter === undefined || filter === null) return true;
+  const v = String(value ?? '');
+  return filter instanceof RegExp ? filter.test(v) : v.toLowerCase().includes(String(filter).toLowerCase());
+}
+
+function memberArray(json) {
+  // mail.tm is a Hydra/JSON-LD API: collections live under "hydra:member".
+  if (Array.isArray(json)) return json;
+  if (json && Array.isArray(json['hydra:member'])) return json['hydra:member'];
+  return [];
+}
+
+async function jsonFetch(fetchImpl, url, opts) {
+  const res = await fetchImpl(url, opts);
+  const text = await res.text();
+  let body = null;
+  try { body = text ? JSON.parse(text) : null; } catch { body = null; }
+  if (!res.ok) {
+    const detail = (body && (body['hydra:description'] || body.message || body.detail)) || text.slice(0, 200);
+    throw new Error(`mail.tm ${opts?.method || 'GET'} ${url} → ${res.status}: ${detail}`);
+  }
+  return body;
+}
+
+/**
+ * Mint a fresh throwaway inbox: pick a domain, create the account, get a token.
+ * Returns { address, password, token, accountId }. `rand` is injectable so the
+ * test is deterministic and the script never calls Math.random in a workflow.
+ */
+export async function createInbox({
+  fetchImpl = fetch,
+  apiBase = DEFAULT_API_BASE,
+  localPart,
+  rand = () => Math.floor(Math.random() * 1e10).toString(36),
+} = {}) {
+  const domains = memberArray(await jsonFetch(fetchImpl, `${apiBase}/domains`));
+  const domain = domains.find((d) => d.isActive !== false)?.domain || domains[0]?.domain;
+  if (!domain) throw new Error('mail.tm: no available domain');
+  const local = localPart || `echo-${rand()}`;
+  const address = `${local}@${domain}`;
+  const password = `Echo!${rand()}A9`;
+  const account = await jsonFetch(fetchImpl, `${apiBase}/accounts`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ address, password }),
+  });
+  const tokenResp = await jsonFetch(fetchImpl, `${apiBase}/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ address, password }),
+  });
+  if (!tokenResp?.token) throw new Error('mail.tm: token request returned no token');
+  return { address, password, token: tokenResp.token, accountId: account?.id ?? null };
+}
+
+/** List message summaries in the inbox (most-recent first, per mail.tm). */
+export async function listMessages(token, { fetchImpl = fetch, apiBase = DEFAULT_API_BASE } = {}) {
+  const body = await jsonFetch(fetchImpl, `${apiBase}/messages`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  return memberArray(body);
+}
+
+/** Fetch one message's full body (text + html). */
+export async function getMessage(token, id, { fetchImpl = fetch, apiBase = DEFAULT_API_BASE } = {}) {
+  return jsonFetch(fetchImpl, `${apiBase}/messages/${id}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+}
+
+/**
+ * Poll the inbox until a message matches the filter, then return its full body.
+ * `sleep` and `now` are injectable so the test runs without real timers/clock.
+ * Throws on timeout. Returns the full message (with .text / .html / .subject).
+ */
+export async function waitForMessage(token, {
+  subject,
+  from,
+  timeoutMs = 120_000,
+  intervalMs = 3_000,
+  fetchImpl = fetch,
+  apiBase = DEFAULT_API_BASE,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  now = () => Date.now(),
+} = {}) {
+  const deadline = now() + timeoutMs;
+  // First iteration runs immediately (no upfront sleep).
+  for (let first = true; ; first = false) {
+    if (!first) {
+      if (now() >= deadline) {
+        throw new Error(`waitForMessage: timed out after ${timeoutMs}ms (subject=${subject ?? '*'} from=${from ?? '*'})`);
+      }
+      await sleep(intervalMs);
+    }
+    const summaries = await listMessages(token, { fetchImpl, apiBase });
+    const hit = summaries.find((m) => matchMessage(m, { subject, from }));
+    if (hit) return getMessage(token, hit.id, { fetchImpl, apiBase });
+    if (first && now() >= deadline) {
+      throw new Error(`waitForMessage: timed out after ${timeoutMs}ms (subject=${subject ?? '*'} from=${from ?? '*'})`);
+    }
+  }
+}

package/scripts/throwaway-identity.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * throwaway-identity.mjs — CLI for the disposable-identity helper (lib/throwaway-identity.mjs).
+ *
+ *   node scripts/throwaway-identity.mjs mint
+ *       → mints a fresh inbox; prints JSON { address, password, token, accountId }.
+ *
+ *   node scripts/throwaway-identity.mjs wait <token> [--subject S] [--from F]
+ *                                       [--code | --link [MATCH]] [--timeout MS]
+ *       → polls the inbox until a matching message arrives, then prints either
+ *         the full message JSON, or (with --code/--link) just the extracted value.
+ *
+ * Use for live-integration test-identity provisioning (the autonomous half — an
+ * anti-bot signup CAPTCHA at account creation is the human handoff).
+ */
+import {
+  createInbox,
+  waitForMessage,
+  extractCode,
+  extractLink,
+} from './lib/throwaway-identity.mjs';
+
+function parseFlags(args) {
+  const out = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--code') out.code = true;
+    else if (a === '--link') { out.link = true; if (args[i + 1] && !args[i + 1].startsWith('--')) out.linkMatch = args[++i]; }
+    else if (a === '--subject') out.subject = args[++i];
+    else if (a === '--from') out.from = args[++i];
+    else if (a === '--timeout') out.timeout = parseInt(args[++i], 10);
+    else out._.push(a);
+  }
+  return out;
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const flags = parseFlags(rest);
+
+  if (cmd === 'mint') {
+    const inbox = await createInbox();
+    process.stdout.write(JSON.stringify(inbox) + '\n');
+    return;
+  }
+
+  if (cmd === 'wait') {
+    const token = flags._[0];
+    if (!token) { console.error('usage: throwaway-identity.mjs wait <token> [--subject S] [--from F] [--code|--link [MATCH]] [--timeout MS]'); process.exit(1); }
+    const msg = await waitForMessage(token, {
+      subject: flags.subject,
+      from: flags.from,
+      timeoutMs: flags.timeout ?? 120_000,
+    });
+    const text = msg.text || msg.html?.join?.('\n') || (Array.isArray(msg.html) ? msg.html.join('\n') : msg.html) || '';
+    if (flags.code) {
+      const code = extractCode(text);
+      if (!code) { console.error('no verification code found in message'); process.exit(1); }
+      process.stdout.write(code + '\n');
+    } else if (flags.link) {
+      const link = extractLink(text, flags.linkMatch ? { match: flags.linkMatch } : {});
+      if (!link) { console.error('no link found in message'); process.exit(1); }
+      process.stdout.write(link + '\n');
+    } else {
+      process.stdout.write(JSON.stringify({ subject: msg.subject, from: msg.from, text }) + '\n');
+    }
+    return;
+  }
+
+  console.error('usage: throwaway-identity.mjs <mint | wait>');
+  process.exit(1);
+}
+
+import { pathToFileURL } from 'node:url';
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((err) => { console.error(err instanceof Error ? err.message : String(err)); process.exit(1); });
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-10T18:44:18.495Z",
-  "instarVersion": "1.3.475",
+  "generatedAt": "2026-06-10T19:33:00.272Z",
+  "instarVersion": "1.3.477",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.476.md

@@ -0,0 +1,33 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added a standalone test utility — `scripts/throwaway-identity.mjs` (+ `scripts/lib/`) — that
+mints genuinely-distinct, readable throwaway email inboxes via the mail.tm public
+disposable-mailbox API and extracts verification codes/links from them. It's the autonomous
+half of provisioning distinct test identities for the Live Integration Security-Test Harness
+(Slack today, any integration later): N distinct inboxes → N genuinely-distinct principals,
+zero real accounts. No runtime code, gate, or config is touched.
+
+## What to Tell Your User
+
+Nothing changes in how the agent runs. This is a developer/test tool. It lets the agent set
+up several genuinely-different throwaway test users (and read their email) on its own, so a
+live integration test can use real distinct identities without anyone hand-creating email
+accounts. The only step it intentionally leaves to a human is passing an anti-bot CAPTCHA at
+workspace creation.
+
+## Summary of New Capabilities
+
+- `scripts/throwaway-identity.mjs mint` — create a fresh readable throwaway inbox.
+- `scripts/throwaway-identity.mjs wait <token>` — await an email and extract its code/link.
+- `scripts/lib/throwaway-identity.mjs` — importable helper (HTTP injectable for hermetic tests).
+
+## Evidence
+
+- 15 hermetic unit tests (`tests/unit/throwaway-identity.test.ts`) — pure extractors + the
+  mint / poll-until-match / timeout flow, with fetch + clock injected (no network).
+- Live CLI smoke minted a real inbox + token. `tsc --noEmit` clean.

package/upgrades/1.3.477.md

@@ -0,0 +1,63 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Spec #4 of the cartographer-conformance project — **fixes a real defect in the
+convergence gate and makes the report-backed converging audit the structural
+default** (dark, off by default).
+
+The defect: the formal initiative gate (`StageTransitionValidator`) required the
+`review-convergence` frontmatter tag to equal the boolean `true`, but the actual
+converging-audit tooling writes an ISO **timestamp string**. A timestamp is not the
+boolean `true`, so the formal gate **rejected every properly-converged spec** at the
+`spec-drafted → spec-converged` transition — quietly broken. This change adds a pure
+`isConvergenceTagPresent` predicate that accepts the canonical timestamp (and still
+the legacy boolean), used as the single definition of "the tag is present."
+
+On top of the defect repair, a new default-off flag `specReview.requireConvergenceReport`
+makes the converging audit's **report** (the proof it actually ran) a requirement of
+the commit-time gate when enabled — so "converged" can mean "the audit ran and left a
+report," not just "a tag was added." The commit-time gate reads the flag via an
+environment variable (it runs before compilation and reads no config), exported from
+config by the husky hook; when unset, the commit-time gate behaves exactly as before.
+The formal gate's existing report requirement is left unconditional, so enabling the
+flag brings the two gates into agreement — and a cross-gate consistency test makes it
+impossible for them to drift apart. Whether an outside model also reviewed a spec is
+surfaced in the gate's diagnostics, never required.
+
+## What to Tell Your User
+
+- **The review gate was quietly broken — now it's fixed and means something**: "The
+  check that confirms a design was properly reviewed before it ships had a bug — it was
+  looking for the wrong marker, so it actually rejected every correctly-reviewed
+  design. I repaired it, and added an opt-in setting that makes 'reviewed' require the
+  review's report to actually exist, not just a tag. It's off by default, so nothing in
+  your current workflow changes until you turn it on."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Report-backed convergence gate | `specReview.requireConvergenceReport: true` in config (opt-in; off by default) |
+| Correct convergence-tag recognition | automatic — the formal gate now accepts the canonical timestamp tag |
+
+## Evidence
+
+- **Before:** a spec converged via the real tooling carries
+  `review-convergence: "2026-06-10T…"`. Feeding it to the formal gate returned
+  `CONVERGENCE_TAG_MISSING` because `"2026-06-10T…" !== true` — the `spec-drafted →
+  spec-converged` transition could not advance any real spec. (The existing tests only
+  ever fed the boolean `true`, which is why the defect shipped unnoticed.)
+- **After:** the same timestamp-tagged + reported spec advances through the real
+  `POST /projects/:id/advance` route (new integration test); a timestamp-tagged spec
+  with a MISSING report still returns `CONVERGENCE_REPORT_MISSING` (the existing,
+  unchanged check); and a new predicate test covers timestamp / boolean / empty /
+  missing.
+- **Back-compat verified end-to-end:** a test runs the real commit-time gate script —
+  with the flag unset, a timestamp-tagged + approved spec with no report commits
+  cleanly (identical to today); with the flag on and no report, it is blocked; with
+  the report present, it commits. This PR's own commit passes through the modified gate
+  with the flag off.