instar 1.3.476 → 1.3.478

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.476",
+  "version": "1.3.478",
   "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;
+}