instar 1.3.967 → 1.3.969

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.967",
+  "version": "1.3.969",
   "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

@@ -22,7 +22,8 @@ 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;
+const HISTORY_HEADING_RE =
+  /^##\s+(?:\d+\.\s+)?(?:Round-\d+\b[^\n]*?(?:change log|hand-check|consistency sweep)|Review record\b|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;
@@ -53,11 +54,176 @@ export function stripInlineAnnotations(text) {
   return out.replace(/[ \t]{2,}/g, ' ').replace(/ +([.,;:])/g, '$1');
 }
 
+/**
+ * A blockquote block that exists to talk ABOUT the document — normative-boundary
+ * markers, "this file is rationale", scope-changed notices. They are meta, not
+ * contract, and they read as especially authoritative because of the `>` and the
+ * bold. Round-37 (codex) found several of them surviving into the generated
+ * contract, where a "NON-NORMATIVE FROM HERE" marker inside a file that claims to
+ * be normative-only is worse than no marker at all.
+ */
+const META_BLOCKQUOTE_RE =
+  /^>\s*(?:#{1,4}\s*)?\**\s*(?:NON-)?NORMATIVE\b|^>\s*\**\s*(?:It (?:is|began)|This file|Build from|The normative artifact|And the review)/i;
+
+/**
+ * A residual the generator CANNOT remove: narrative prose that states a rule and
+ * narrates its history in the same sentence ("round-36 found this paragraph
+ * stating only the p99"). Counting them is the honest alternative to pretending
+ * they are gone — the run reports the number so a reader knows what they are
+ * getting.
+ */
+const NARRATIVE_HISTORY_RE = /\b(?:round|rounds)[- ]\d+\b/gi;
+
+/**
+ * STRICT mode (`--strict`): an ALLOWLIST of contract-bearing headings, instead of
+ * the default denylist of history headings.
+ *
+ * The denylist answers "what is definitely history?" and keeps everything else.
+ * That is the wrong default for an implementation artifact: rationale, accepted
+ * residuals and self-correcting narrative are all "not definitely history", so
+ * they survive — and SEVEN consecutive review rounds (33-39) said the resulting
+ * contract still read as archaeology. An allowlist answers the question that
+ * actually matters, "what must be built?", and everything else is absent by
+ * default rather than by pattern-match.
+ *
+ * Kept deliberately narrow: the contract table, rollout/acceptance, honest
+ * limits, decision points, and the test plan. Rationale lives in the source spec,
+ * which is where a reader goes for judgment.
+ */
+const STRICT_CONTRACT_HEADING_RE =
+  /^#{2,3}\s+(?:\d+(?:\.\d+)*\.?\s+)?(?:Final contract|What an implementer builds|Current design overview|Design\b|Glossary|Normative outcome table|Rollout|Honest limits|Privacy posture|Decision points touched|Open questions|Frontloaded Decisions|Dependencies|Multi-machine posture|Test plan|Fail directions|What this does not do)/i;
+
+export function splitStrictContract(markdown) {
+  const lines = markdown.split('\n');
+  // Pre-pass: how big is each allowlisted section in the SOURCE (to the next
+  // heading of the same-or-higher level)?
+  const sourceSizes = new Map();
+  for (let i = 0; i < lines.length; i++) {
+    if (!STRICT_CONTRACT_HEADING_RE.test(lines[i])) continue;
+    const level = (lines[i].match(/^#+/) || ['##'])[0].length;
+    let bytes = 0;
+    for (let j = i + 1; j < lines.length; j++) {
+      const m = lines[j].match(/^(#+)\s/);
+      // The source measure must NOT use the capture's stopping rule, or it
+      // shrinks in lockstep with the truncation it is meant to detect (an
+      // interior non-allowlisted H3 would end both, and the guard sees nothing).
+      // Stop at the next ALLOWLISTED heading, the next H2, or a NUMBERED SIBLING
+      // at the same level.
+      //
+      // The sibling test is what separates the two shapes this guard cannot
+      // otherwise tell apart (both are "a same-level heading follows"):
+      //   "### 3.0 Final contract" → "### Normative checklist"  = meant as a CHILD;
+      //       its content belongs to 3.0 and capture losing it is a real defect.
+      //   "### 3.10 Test plan"     → "### 3.11 Judgeable-record" = a genuine SIBLING;
+      //       its content was never 3.10's and excluding it is correct.
+      // Without this, the guard fired permanently on every numbered spec — and a
+      // warning that always fires is one nobody reads (the lesson from its own
+      // second implementation).
+      const isNumberedSibling = m && m[1].length === level && /^#+\s+\d+(\.\d+)*[.\s]/.test(lines[j]);
+      if (m && (STRICT_CONTRACT_HEADING_RE.test(lines[j]) || m[1].length <= 2 || isNumberedSibling)) break;
+      // Content that belongs to a NESTED allowlisted subsection is captured
+      // under that subsection's own entry — it is not lost, so it must not
+      // count against this section (otherwise a container heading like
+      // "## 4. Honest limits" followed by an allowlisted "### 4.0 …" warns
+      // forever, and a guard that always warns is a guard nobody reads).
+      bytes += lines[j].length + 1;
+    }
+    sourceSizes.set(lines[i].trim(), bytes);
+  }
+  const kept = [];
+  let keeping = false;
+  let openLevel = 0;
+  let keptSections = 0;
+  const sectionSizes = [];
+  // Front matter always rides along — it carries the approval + convergence tags.
+  let inFrontMatter = lines[0] === '---';
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (inFrontMatter) {
+      kept.push(line);
+      if (i > 0 && line === '---') inFrontMatter = false;
+      continue;
+    }
+    if (/^#{1,3}\s/.test(line)) {
+      const level = (line.match(/^#+/) || ['##'])[0].length;
+      if (STRICT_CONTRACT_HEADING_RE.test(line)) {
+        keeping = true;
+        openLevel = level;
+        keptSections++;
+        sectionSizes.push({ heading: line.trim(), bytes: 0, sourceBytes: sourceSizes.get(line.trim()) || 0 });
+      } else if (keeping && level > openLevel) {
+        // A NON-allowlisted sub-heading DEEPER than the open section is that
+        // section's own child — "### 3.2 The credential arm" under "## 3.
+        // Design". Closing on it silently emptied the section while the section
+        // COUNT stayed the same, so the contract looked complete and was not:
+        // the outbound-gate design (86 KB) shipped as 14 bytes, and the reviews
+        // run against it produced four objections the missing text already
+        // answered. Children ride along; a sibling or an allowlisted heading
+        // still closes it.
+      } else {
+        keeping = false;
+      }
+      // An H1 (the title) is kept as an anchor but does not open a section.
+      if (/^#\s/.test(line)) {
+        kept.push(line);
+        keeping = false;
+        continue;
+      }
+    }
+    if (keeping) {
+      kept.push(line);
+      if (sectionSizes.length) sectionSizes[sectionSizes.length - 1].bytes += line.length + 1;
+    }
+  }
+  const body = stripInlineAnnotations(kept.join('\n')).replace(/\n{4,}/g, '\n\n\n');
+  const narrativeResidual = (body.match(NARRATIVE_HISTORY_RE) || []).length;
+  // Guard against the allowlist's own failure mode: SILENT OMISSION. If strict
+  // mode keeps only a small slice of a large spec, the likely cause is that the
+  // spec's headings do not match the allowlist — not that the spec is mostly
+  // rationale. Confirmed in practice on outbound-gate-advisory-override, where
+  // the normative outcome table lived under headings the list did not name, and
+  // the reviewer's first finding was "normative behavior is missing".
+  const sourceHeadings = (markdown.match(/^#{2,3}\s/gm) || []).length;
+  const keptRatio = sourceHeadings ? keptSections / sourceHeadings : 1;
+  // Section COUNT is not content coverage: an H3 inside an allowlisted section
+  // ends its capture, silently emptying it while the count stays identical.
+  // Observed live (2026-07-25) — a new "### Normative checklist" heading inside
+  // §3.0 dropped the entire contract table and the checklist itself from the
+  // output, and the capture-ratio guard below did not fire because 10 sections
+  // still "matched". So also guard on captured BYTES per kept section.
+  // A short section is only suspicious when the SOURCE section is long — a
+  // container heading (e.g. "## 4. Honest limits" immediately followed by an
+  // allowlisted "### 4.0 …") is legitimately near-empty and must not warn.
+  const truncated = sectionSizes.filter(
+    (x) => x.sourceBytes > 1000 && x.bytes < x.sourceBytes * 0.25,
+  );
+  const thinSectionWarning = truncated.length
+    ? `${truncated.length} allowlisted section(s) captured far less than the ` +
+      `source contains: ` +
+      truncated
+        .map((x) => `${x.heading} (${x.bytes}/${x.sourceBytes} bytes)`)
+        .join(' | ') +
+      ` — an H3 inside an allowlisted section ENDS its capture, emptying it while ` +
+      `the section count stays the same. Sub-headings inside a contract section ` +
+      `must be H4.`
+    : null;
+  const underCaptureWarning =
+    sourceHeadings >= 8 && keptRatio < 0.25
+      ? `only ${keptSections}/${sourceHeadings} sections matched the allowlist ` +
+        `(${Math.round(keptRatio * 100)}%) — the strict contract may be MISSING ` +
+        `normative sections whose headings are not on the list. Verify before ` +
+        `building from it.`
+      : null;
+  return { contract: body, keptSections, narrativeResidual, sourceHeadings, underCaptureWarning, thinSectionWarning };
+}
+
 export function splitContract(markdown) {
   const lines = markdown.split('\n');
   const kept = [];
   let inHistory = false;
+  let inMetaQuote = false;
   let droppedSections = 0;
+  let droppedMetaBlocks = 0;
   for (const line of lines) {
     if (/^##\s/.test(line)) {
       if (HISTORY_HEADING_RE.test(line) && !ALWAYS_CONTRACT_RE.test(line)) {
@@ -68,21 +234,56 @@ export function splitContract(markdown) {
       // A non-history H2 ends a history run (sections are not strictly ordered).
       inHistory = false;
     }
+    // Meta blockquotes run until the first non-blockquote, non-blank line.
+    if (!inHistory) {
+      if (!inMetaQuote && META_BLOCKQUOTE_RE.test(line)) {
+        inMetaQuote = true;
+        droppedMetaBlocks++;
+      } else if (inMetaQuote && !/^>/.test(line) && line.trim() !== '') {
+        inMetaQuote = false;
+      }
+      if (inMetaQuote) continue;
+    }
     if (!inHistory) kept.push(line);
   }
   const body = stripInlineAnnotations(kept.join('\n')).replace(/\n{4,}/g, '\n\n\n');
-  return { contract: body, droppedSections };
+  const narrativeResidual = (body.match(NARRATIVE_HISTORY_RE) || []).length;
+  return { contract: body, droppedSections, droppedMetaBlocks, narrativeResidual };
 }
 
 /** The banner that makes the generated file unmistakable and un-editable-by-hand. */
-function banner(specRel) {
+function banner(specRel, narrativeResidual, strict) {
+  if (strict) {
+    return [
+      '<!-- GENERATED FILE — DO NOT EDIT.',
+      `     Source: ${specRel}`,
+      '     Regenerate: node scripts/generate-spec-contract.mjs --spec ' + specRel + ' --strict',
+      '     STRICT IMPLEMENTATION CONTRACT: allowlisted contract sections only.',
+      '',
+      '     Everything not on the allowlist is ABSENT BY DEFAULT — including all',
+      '     rationale. This file says WHAT to build, never why. Read the source',
+      '     spec for the reasoning, the alternatives, and the accepted residuals',
+      '     in their full form.',
+      `     (${narrativeResidual} residual "round-N" reference(s) remain inline.)`,
+      '-->',
+      '',
+    ].join('\n');
+  }
   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.',
+    '     This is the IMPLEMENTATION CONTRACT.',
+    '',
+    '     REMOVED: history sections, delimited round-annotations, and blockquote',
+    '     meta-blocks that talk about the document rather than the design.',
+    '',
+    '     NOT REMOVED: narrative prose that states a rule and narrates its own',
+    '     history in the same sentence. A transform cannot separate those without',
+    '     judgment it deliberately does not have, so some review references remain',
+    `     below (${narrativeResidual} occurrence(s) of "round-N" in this file).`,
+    '     Where such a sentence describes what a design USED to be, the surrounding',
+    '     normative statement governs. Read the source spec for full context.',
     '-->',
     '',
   ].join('\n');
@@ -99,12 +300,34 @@ function main() {
   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 strict = args.includes('--strict');
+  if (!fs.existsSync(specPath)) {
+    console.error(`ERROR: spec not found: ${specRel}`);
+    process.exit(2);
+  }
+  let markdown;
+  try {
+    markdown = fs.readFileSync(specPath, 'utf8');
+  } catch (err) {
+    console.error(`ERROR: cannot read ${specRel}: ${err instanceof Error ? err.message : err}`);
+    process.exit(2);
+  }
+  const res = strict ? splitStrictContract(markdown) : splitContract(markdown);
+  const { contract, narrativeResidual } = res;
+  const droppedSections = res.droppedSections ?? 0;
+  const droppedMetaBlocks = res.droppedMetaBlocks ?? 0;
+  const keptSections = res.keptSections ?? 0;
+  const output = banner(specRel, narrativeResidual, strict) + contract;
+  if (res.underCaptureWarning) {
+    console.error(`WARNING (strict): ${res.underCaptureWarning}`);
+  }
+  if (res.thinSectionWarning) {
+    console.error(`WARNING (strict): ${res.thinSectionWarning}`);
+  }
 
   const slug = path.basename(specPath, '.md');
-  const outPath = path.join(path.dirname(specPath), 'generated', `${slug}.contract.md`);
+  const suffix = strict ? '.contract.strict.md' : '.contract.md';
+  const outPath = path.join(path.dirname(specPath), 'generated', `${slug}${suffix}`);
 
   if (check) {
     if (!fs.existsSync(outPath)) {
@@ -119,7 +342,14 @@ function main() {
       );
       process.exit(1);
     }
-    console.log(`OK: contract is current (${droppedSections} history sections excluded).`);
+    console.log(
+      strict
+        ? `OK: strict contract is current (${keptSections} allowlisted sections; ` +
+            `${narrativeResidual} narrative round-references remain).`
+        : `OK: contract is current (${droppedSections} history sections, ` +
+            `${droppedMetaBlocks} meta-blocks excluded; ${narrativeResidual} narrative ` +
+            `round-references remain).`,
+    );
     return;
   }
 
@@ -127,7 +357,14 @@ function main() {
   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.`,
+    strict
+    ? `wrote ${path.relative(process.cwd(), outPath)} — STRICT: ${keptSections} ` +
+        `allowlisted sections kept, ${pct}% smaller. RESIDUAL: ${narrativeResidual} ` +
+        `narrative round-reference(s).`
+    : `wrote ${path.relative(process.cwd(), outPath)} — ${droppedSections} history ` +
+      `sections + ${droppedMetaBlocks} meta-blocks excluded, ${pct}% smaller. ` +
+      `RESIDUAL: ${narrativeResidual} narrative round-reference(s) the transform ` +
+      `cannot remove.`,
   );
 }
 

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-25T18:25:42.434Z",
-  "instarVersion": "1.3.967",
+  "generatedAt": "2026-07-25T21:09:48.944Z",
+  "instarVersion": "1.3.969",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/src/scaffold/templates/jobs/instar/evolution-overdue-check.md

@@ -16,14 +16,18 @@ toolAllowlist: "*"
 unrestrictedTools: true
 mcpAccess: none
 ---
-Check for overdue commitments: curl -s http://localhost:${INSTAR_PORT:-4042}/evolution/actions/overdue
+AUTH="${INSTAR_AUTH_TOKEN:-$(python3 -c "import json; v=json.load(open('.instar/config.json')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)}"
+AGENT_ID="${INSTAR_AGENT_ID:-$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('projectName',''))" 2>/dev/null)}"
+PORT="${INSTAR_PORT:-4042}"
+
+Check for overdue commitments: curl -s -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:$PORT/evolution/actions/overdue
 
 For each overdue action:
 1. Assess: Can this be completed now? Is it still relevant?
 2. If actionable, attempt to complete it or advance it
-3. If no longer relevant, cancel it: curl -s -X PATCH http://localhost:${INSTAR_PORT:-4042}/evolution/actions/ACT-XXX -H 'Content-Type: application/json' -d '{"status":"cancelled","resolution":"No longer relevant because..."}'
+3. If no longer relevant, cancel it: curl -s -X PATCH -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:$PORT/evolution/actions/ACT-XXX -H 'Content-Type: application/json' -d '{"status":"cancelled","resolution":"No longer relevant because..."}'
 4. If blocked, escalate to the user via Telegram (if configured)
 
-Also check pending actions (curl -s http://localhost:${INSTAR_PORT:-4042}/evolution/actions?status=pending) for items that have been pending more than 48 hours without a due date — these are forgotten commitments.
+Also check pending actions (curl -s -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" "http://localhost:$PORT/evolution/actions?status=pending") for items that have been pending more than 48 hours without a due date — these are forgotten commitments.
 
 If no overdue or stale items, exit silently.

package/src/scaffold/templates/jobs/instar/evolution-proposal-evaluate.md

@@ -16,16 +16,20 @@ toolAllowlist: "*"
 unrestrictedTools: true
 mcpAccess: none
 ---
-Review pending evolution proposals: curl -s http://localhost:${INSTAR_PORT:-4042}/evolution/proposals?status=proposed
+AUTH="${INSTAR_AUTH_TOKEN:-$(python3 -c "import json; v=json.load(open('.instar/config.json')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)}"
+AGENT_ID="${INSTAR_AGENT_ID:-$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('projectName',''))" 2>/dev/null)}"
+PORT="${INSTAR_PORT:-4042}"
+
+Review pending evolution proposals: curl -s -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" "http://localhost:$PORT/evolution/proposals?status=proposed"
 
 For each proposal:
 1. Read the title, description, type, and source
 2. Evaluate: Is this a genuine improvement? Is the effort worth the impact? Does it align with our goals?
-3. If approved, update status: curl -s -X PATCH http://localhost:${INSTAR_PORT:-4042}/evolution/proposals/EVO-XXX -H 'Content-Type: application/json' -d '{"status":"approved"}'
+3. If approved, update status: curl -s -X PATCH -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:$PORT/evolution/proposals/EVO-XXX -H 'Content-Type: application/json' -d '{"status":"approved"}'
 4. If rejected or deferred, update with reason.
 
 Do NOT implement approved proposals — that's handled by the paired evolution-proposal-implement job.
 
-Also check the dashboard: curl -s http://localhost:${INSTAR_PORT:-4042}/evolution — report any highlights to the user if they seem important.
+Also check the dashboard: curl -s -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:$PORT/evolution — report any highlights to the user if they seem important.
 
 If no proposals need attention, exit silently.

package/src/scaffold/templates/jobs/instar/evolution-proposal-implement.md

@@ -15,11 +15,15 @@ gate: "curl -sf -H \"Authorization: Bearer $INSTAR_AUTH_TOKEN\" -H \"X-Instar-Ag
 toolAllowlist: "*"
 unrestrictedTools: true
 ---
-Implement approved evolution proposals: curl -s http://localhost:${INSTAR_PORT:-4042}/evolution/proposals?status=approved
+AUTH="${INSTAR_AUTH_TOKEN:-$(python3 -c "import json; v=json.load(open('.instar/config.json')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)}"
+AGENT_ID="${INSTAR_AGENT_ID:-$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('projectName',''))" 2>/dev/null)}"
+PORT="${INSTAR_PORT:-4042}"
+
+Implement approved evolution proposals: curl -s -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" "http://localhost:$PORT/evolution/proposals?status=approved"
 
 For each approved proposal:
 1. Read the full description and understand what needs to be built
 2. Implement it: create the skill/hook/job/config change described
-3. After implementation, mark complete: curl -s -X PATCH http://localhost:${INSTAR_PORT:-4042}/evolution/proposals/EVO-XXX -H 'Content-Type: application/json' -d '{"status":"implemented","resolution":"What was done"}'
+3. After implementation, mark complete: curl -s -X PATCH -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:$PORT/evolution/proposals/EVO-XXX -H 'Content-Type: application/json' -d '{"status":"implemented","resolution":"What was done"}'
 
 If no approved proposals exist, exit silently.

package/src/scaffold/templates/jobs/instar/identity-review.md

@@ -17,7 +17,7 @@ mcpAccess: none
 ---
 Identity review — check your identity coherence and growth.
 
-AUTH=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('authToken',''))" 2>/dev/null)
+AUTH="${INSTAR_AUTH_TOKEN:-$(python3 -c "import json; v=json.load(open('.instar/config.json')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)}"
 AGENT_ID="${INSTAR_AGENT_ID:-$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('projectName',''))" 2>/dev/null)}"
 
 1. **Check soul.md drift**: curl -s -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:${INSTAR_PORT:-4042}/identity/soul/drift

package/src/scaffold/templates/jobs/instar/insight-harvest.md

@@ -14,7 +14,11 @@ toolAllowlist: "*"
 unrestrictedTools: true
 mcpAccess: none
 ---
-Harvest and synthesize learnings: curl -s http://localhost:${INSTAR_PORT:-4042}/evolution/learnings?applied=false
+AUTH="${INSTAR_AUTH_TOKEN:-$(python3 -c "import json; v=json.load(open('.instar/config.json')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)}"
+AGENT_ID="${INSTAR_AGENT_ID:-$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('projectName',''))" 2>/dev/null)}"
+PORT="${INSTAR_PORT:-4042}"
+
+Harvest and synthesize learnings: curl -s -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" "http://localhost:$PORT/evolution/learnings?applied=false"
 
 Review unapplied learnings and look for:
 1. **Patterns**: Multiple learnings pointing to the same conclusion
@@ -22,10 +26,10 @@ Review unapplied learnings and look for:
 3. **Cross-domain connections**: Insights from one area that apply to another
 
 For each actionable pattern found, create an evolution proposal:
-curl -s -X POST http://localhost:${INSTAR_PORT:-4042}/evolution/proposals -H 'Content-Type: application/json' -d '{"title":"...","source":"insight-harvest from LRN-XXX","description":"...","type":"...","impact":"...","effort":"..."}'
+curl -s -X POST -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:$PORT/evolution/proposals -H 'Content-Type: application/json' -d '{"title":"...","source":"insight-harvest from LRN-XXX","description":"...","type":"...","impact":"...","effort":"..."}'
 
 Then mark the relevant learnings as applied:
-curl -s -X PATCH http://localhost:${INSTAR_PORT:-4042}/evolution/learnings/LRN-XXX/apply -H 'Content-Type: application/json' -d '{"appliedTo":"EVO-XXX"}'
+curl -s -X PATCH -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:$PORT/evolution/learnings/LRN-XXX/apply -H 'Content-Type: application/json' -d '{"appliedTo":"EVO-XXX"}'
 
 Also update MEMORY.md with any patterns worth preserving long-term.
 

package/src/scaffold/templates/jobs/instar/reflection-trigger.md

@@ -36,6 +36,6 @@ echo ""
 echo "If you find genuine learnings:"
 echo "1. Update .instar/MEMORY.md with the insight (append to the file)"
 echo "2. Be specific: include what was learned, why it matters, and how it should guide future work"
-echo "3. Signal completion: curl -s -X POST http://localhost:${INSTAR_PORT:-4042}/reflection/record -H 'Content-Type: application/json' -d '{"type":"quick"}'"
+echo "3. Signal completion: curl -s -X POST -H \"Authorization: Bearer \$INSTAR_AUTH_TOKEN\" -H \"X-Instar-AgentId: \$INSTAR_AGENT_ID\" http://localhost:${INSTAR_PORT:-4042}/reflection/record -H 'Content-Type: application/json' -d '{\"type\":\"quick\"}'"
 echo ""
 echo "If nothing significant, do nothing. Silence means continuity is working as expected."

package/upgrades/1.3.968.md

@@ -0,0 +1,121 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Widened the history-heading pattern in `scripts/generate-spec-contract.mjs` by
+one alternative (`Review record`), so a spec that consolidates its review history
+into a single section is stripped like one that uses per-round `change log`
+sections.
+
+**Why it needed changing.** Exercising the generator on a second spec surfaced
+the gap the first spec could not: it matched nothing, stripped nothing, reported
+`0 history sections excluded` and **exited 0**. That is indistinguishable from a
+document with no history to strip — a silent no-op presenting as success, in a
+tool built to prevent exactly that class of problem.
+
+The ELI16 and the side-effects review now both carry the warning: read what the
+tool says it *did*, not just whether it succeeded.
+
+Two fixes to `scripts/generate-spec-contract.mjs`, both found by reviewing the
+tool's own output as a build artifact for the first time:
+
+1. **Meta-blockquotes are stripped.** Blocks that talk *about* the document —
+   normative-boundary markers, "this file is rationale", scope-change notices —
+   are now removed alongside history sections, and counted separately.
+
+2. **The banner stopped overclaiming.** It previously said review history "is
+   deliberately absent." That was false: narrative prose that states a rule and
+   narrates its own history in the same sentence cannot be separated by a
+   transform, and such sentences remained. The banner now states what is removed,
+   what is not, and prints the **count of `round-N` references still present**.
+
+**Why it matters.** The first version produced a file claiming to be
+normative-only that contained a `NON-NORMATIVE FROM HERE` marker — a boundary
+marker inside a document denying it had boundaries. An implementer trusting the
+banner would have been trusting a false statement. A tool that lies in its own
+header is worse than one with a stated limit, and this tool exists specifically
+to stop retired designs from being implemented.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- Before: `inbound-message-recording-gap` generated 5% smaller with **0 sections
+  excluded**. After: 12% smaller with **1 section excluded**.
+- The large spec is unaffected — still 37 sections excluded, 37% smaller —
+  confirming the widening did not over-match.
+- `--check` passes for both specs after regeneration.
+- Side-effects review updated with the finding under "under-block" rather than
+  only fixing the code.
+
+- Before: `inbound-message-recording-gap` generated with **3 meta-blocks
+  surviving**, banner claiming history absent, `NON-NORMATIVE` marker present in
+  the output.
+- After: 1 history section + **3 meta-blocks** excluded, 13% smaller, zero
+  `NON-NORMATIVE` occurrences, banner reporting **14 narrative round-references
+  remain**.
+- Regression check on the large spec: unchanged behaviour — still **37 history
+  sections, 0 meta-blocks, 37% smaller** — confirming the new pattern does not
+  over-match on a document that has none.
+- `--check` passes for both specs after regeneration and reports the new counts.
+
+## Second change in the same push: `--strict` (allowlist mode)
+
+The default transform is a **denylist** — "remove what is definitely history,
+keep everything else." For an implementation artifact that is the wrong default:
+rationale, accepted residuals and self-correcting narrative are all "not
+definitely history", so they survive. Seven consecutive review rounds (33-39)
+said the generated contract still read as archaeology.
+
+`--strict` inverts it to an **allowlist** of contract-bearing headings (final
+contract, rollout, honest limits, decision points, test plan, dependencies).
+Everything else is absent by default rather than by pattern-match, and the output
+lands at `<slug>.contract.strict.md`.
+
+**Evidence:** `inbound-message-recording-gap` 1487 → 874 lines (42% smaller, 11
+allowlisted sections). `outbound-gate-advisory-override` 2765 → 270 lines (**90%
+smaller**, 8 sections) — a spec that never converged in 33 rounds, and whose
+history-stripped denylist version was still large enough to time a reviewer out,
+now has a contract short enough to actually review.
+
+Additive: the default mode and its output path are unchanged.
+
+## And the predicted failure happened immediately
+
+The over-block risk documented for `--strict` — dropping a normative section whose
+heading is not on the allowlist — occurred on the first spec with a different
+heading scheme. `outbound-gate-advisory-override` captured 8 of 66 sections and
+lost its normative outcome table; the reviewer's first finding was "normative
+behavior is missing from the strict contract."
+
+A `WARNING (strict)` now fires when a spec with >=8 headings matches under 25% of
+them, naming the ratio. It flags that spec at 12% and stays silent on the one that
+captures correctly. It warns rather than refuses, because the ratio is a heuristic
+and a rationale-heavy spec can legitimately capture low — a refusal on a heuristic
+blocks correct output, a warning that names the number hands the judgment to a
+human.
+
+## A content-loss guard for `--strict`
+
+The capture-ratio warning catches *too few sections matching*. It cannot see a
+section that matched and captured **nothing** — which happened live: a
+sub-heading added inside an allowlisted section ended that section's capture and
+dropped the entire contract table from the output, while the section count stayed
+identical and the guard stayed silent.
+
+A second warning now compares captured bytes to source bytes per section. Three
+implementations were needed: averaging hid the empty section behind healthy ones;
+an absolute threshold false-positived permanently on legitimate container
+headings; and the working version required the source measurement to stop using
+the capture's own rule, which had made it shrink in lockstep with the truncation.
+
+Each version was verified against the real regression and the correct file.

package/upgrades/1.3.969.md

@@ -0,0 +1,35 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Five built-in job templates authenticated their `gate:` line but not their prompt bodies, so all 12 body calls to authenticated endpoints returned `401 Missing or invalid Authorization header` at runtime. The affected jobs — `evolution-proposal-evaluate`, `evolution-proposal-implement`, `evolution-overdue-check`, `insight-harvest`, `reflection-trigger` — woke on schedule, passed their gate, read nothing, and exited "silently". A silently-failing job and a healthy quiet job are indistinguishable, which is why this survived.
+
+Each body now resolves the canonical env-first `AUTH` / `AGENT_ID` / `PORT` block and passes `Authorization: Bearer $AUTH` + `X-Instar-AgentId: $AGENT_ID` on every non-public call.
+
+Two same-class defects found while in the files were fixed in the same change:
+
+- `identity-review.md` defined `AUTH` by reading `.instar/config.json` only. On an agent whose stored token has drifted from the live server token, that read is rejected — confirmed on the dev agent, where the 16-char config value returns `Invalid auth token` and the 36-char `$INSTAR_AUTH_TOKEN` succeeds. It now prefers the environment value.
+- `reflection-trigger.md` emitted its instruction through a double-quoted `echo` whose inner double quotes were consumed by the shell, rendering `-d '{type:quick}'` — invalid JSON — in addition to carrying no auth. Both fixed; the token name is left unexpanded so no secret enters the transcript.
+
+A new CI lint (`tests/unit/job-template-auth-lint.test.ts`) scans every shipped template for curl calls to non-public endpoints missing an `Authorization` header, and for templates that use `$AUTH` without defining it. Its public-endpoint exemptions mirror `authMiddleware()` and a drift guard asserts each exempted path still appears there.
+
+The fix is applied to the **source** templates, not deployed copies: `installBuiltinJobs()` unconditionally overwrites every deployed template on each update run (`InstallBuiltinJobs.ts:127`, reached from `PostUpdateMigrator.ts:4046`), so a hand-patched deployed copy would have been silently reverted at the next update. No separate migration is required — existing agents receive the fix through the normal update path.
+
+## What to Tell Your User
+
+Some scheduled jobs that have always been silent will start producing output — that is the repair working, not a new fault. If a user asks why their proposal-review or insight-harvest job has suddenly become active after months of quiet, the honest answer is that it was never running its body successfully; it was being refused at the door and exiting without saying so.
+
+## Summary of New Capabilities
+
+No new user-facing capability. Five existing scheduled jobs go from silently non-functional to functional, and a build-time lint prevents the class from returning.
+
+## Evidence
+
+- Run against the six pre-fix files extracted from `HEAD`, the lint reports exactly 12 unauthenticated calls — `evolution-overdue-check` 3, `evolution-proposal-evaluate` 3, `evolution-proposal-implement` 2, `insight-harvest` 3, `reflection-trigger` 1 — matching an independently-derived census. Against the fixed files: 0.
+- Live: an unauthenticated call to `/evolution/proposals?status=approved` returns `{"error":"Missing or invalid Authorization header"}`; the fixed template's resolved command returns the real proposal list. Same confirmed for `/evolution/learnings?applied=false` and `/evolution/actions/overdue`.
+- Executing the original `reflection-trigger.md` echo renders `-d '{type:quick}'`; the fixed line renders `-d '{"type":"quick"}'`.
+- The lint's first draft falsely flagged three healthy templates (`initiative-digest-review`, `mentor-onboarding`, `org-intent-drift-audit`) that define `AUTH` inside backticks; the detector was corrected and the false positive pinned by a regression test.
+- `tests/unit/job-template-auth-lint.test.ts` (9 tests) green; template-family tests (`refresh-jobs`, `default-jobs-valid`, `PostUpdateMigrator-templateResolution`) green.

package/upgrades/side-effects/evo007-job-template-auth.eli16.md

@@ -0,0 +1,51 @@
+# Built-in job templates must authenticate their API calls — Plain-English Overview
+
+> The one-line version: five of your scheduled background jobs have been quietly doing nothing for their entire existence, because their instructions told them to knock on a locked door without the key.
+
+## The problem in one breath
+
+Your agent runs scheduled background jobs — small recurring tasks like "review new improvement proposals" or "harvest lessons learned". Each job has a **doorman check** (does this job have anything to do right now?) and a **body** (the actual instructions). The doorman checks were carrying the agent's key. The instructions were not. So every one of those jobs woke up, correctly decided "yes, there's work here", walked to the door, got refused, and exited — reporting nothing wrong.
+
+The reason nobody noticed for so long is the cruel part: these jobs are *designed* to be silent when there's nothing to do. A job that fails silently and a job that succeeds with nothing to report look **exactly the same** from the outside.
+
+## What already exists
+
+- **The scheduled jobs themselves** — small recurring tasks your agent runs on a timer. They already work as a system; the scheduler, the timing, and the reporting are all fine.
+- **The lock on the agent's own API** — nearly every internal endpoint requires a key (a "bearer token"). A handful of endpoints are deliberately public, like the basic health check.
+- **The key itself** — handed to every job through its environment. It was there the whole time. The instructions just never picked it up.
+- **The update pipeline** — whenever your agent updates, it rewrites its job instruction files from the shipped originals. This matters enormously, and it's covered below.
+
+## What this adds
+
+**The instructions now pick up the key.** Each of the affected job bodies now starts by resolving the agent's key, its identity, and its port, and every call it makes carries them. That's the whole fix — about thirty lines of text across six files.
+
+Alongside the fix, a **build-time check** now scans every shipped job instruction file and fails the build if any of them calls a locked endpoint without the key. Secondary changes:
+
+- One more job (`identity-review`) was reading the key from a **stale source**. On this very agent, that stored copy has drifted out of date and is rejected by the server, while the live one works. It now prefers the live one.
+- One job (`reflection-trigger`) had a **second, unrelated bug on the same line**: a quoting mistake that mangled the data it sends into invalid gibberish. Fixed too, since the line was being rewritten anyway.
+
+## The new pieces
+
+- **The build-time check** — reads every shipped job instruction file, finds every call it makes, and asks two questions: is this endpoint locked, and if so, is the key present? It also refuses instructions that *use* a key they never *fetch*. What it is explicitly **not** allowed to do: anything at runtime. It cannot block your agent, delay a message, or stop a job. It is a test. Its only power is to fail a build before broken instructions ever reach you. That line matters — a check this simple must never be given authority over a live agent.
+
+## The safeguards
+
+**Prevents the same bug from shipping again.** The check was proven honest before being trusted: run against the *old* files, it reports exactly the twelve broken calls that actually shipped — not eleven, not thirteen. Run against the fixed files, zero. A check that has never been shown to catch the real bug is just decoration.
+
+**Prevents the check from crying wolf.** The first draft of the check falsely accused three perfectly healthy job files, because they fetch their key in a slightly different but entirely valid style. That was caught, fixed, and locked down with its own test so it can't come back. A check that fails on healthy files gets switched off by the next frustrated person, which is worse than having no check.
+
+**Prevents a fix that only looks like a fix.** This is the trap this change deliberately avoided. Your agent rewrites its job files from the shipped originals on **every update**. So "fixing" the copies sitting on this machine would have worked perfectly — until the next update silently wiped them. That's a fix indistinguishable from a real one, which is exactly the kind of illusion this family of bugs keeps producing. The change is made to the shipped originals, so it reaches every agent through the normal update path and stays fixed.
+
+**Prevents guessing about which doors are locked.** The check doesn't keep its own private list of public endpoints — that would drift out of date. It mirrors the real list and asserts the real one still contains those entries, so if a public endpoint ever becomes locked, the check fails loudly instead of quietly waving it through.
+
+## What ships when
+
+All of it ships together, in one change — the six corrected instruction files and the check that keeps them correct. There's no phased rollout because there's nothing to roll out gradually: the files are either right or wrong, and they're currently wrong.
+
+## What you'll actually notice
+
+Some jobs that have always been silent will **start producing output**. That's the repair working, not a new problem — but it's worth knowing in advance so a suddenly-chatty proposal-review job doesn't read as a malfunction.
+
+## If it goes wrong
+
+Undo the six files and ship the patch; agents pick up the reversal on their next update. Nothing is stored, nothing is migrated, nothing needs repairing. The worst case is a return to exactly today's behaviour — quiet jobs that don't do anything. That asymmetry is the honest argument for making this change: there's almost nothing to lose, and five broken jobs to gain back.

package/upgrades/side-effects/evo007-job-template-auth.md

@@ -0,0 +1,160 @@
+# Side-Effects Review — Built-in job templates must authenticate their API calls
+
+**Version / slug:** `evo007-job-template-auth`
+**Date:** `2026-07-25`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Five shipped built-in job templates carried a `gate:` line that authenticates correctly, but **prompt bodies** that called authenticated endpoints with a bare `curl -s http://localhost:.../evolution/...`. All 12 of those calls return `401 Missing or invalid Authorization header` at runtime. The gate passing is precisely what hid the failure: the job would wake up, correctly conclude "there is work to do", then read nothing and exit "silently" — indistinguishable from a healthy no-op. A sixth template (`identity-review.md`) defined `AUTH` by reading `.instar/config.json` only, which is broken on any agent whose config token has drifted from the live server token (observed first-hand on this agent: the 16-char config value is rejected, the 36-char `$INSTAR_AUTH_TOKEN` is accepted).
+
+Files touched: six templates under `src/scaffold/templates/jobs/instar/` (`evolution-overdue-check`, `evolution-proposal-implement`, `evolution-proposal-evaluate`, `insight-harvest`, `reflection-trigger`, `identity-review`), plus a new CI lint at `tests/unit/job-template-auth-lint.test.ts`. Each fixed body now resolves the canonical `AUTH` / `AGENT_ID` / `PORT` block (env-first, config fallback) and passes `Authorization: Bearer $AUTH` + `X-Instar-AgentId: $AGENT_ID` on every non-public call.
+
+Two additional defects were found and fixed while in the file, both on the same `reflection-trigger.md` line: the echoed instruction rendered `-d '{type:quick}'` (unescaped inner double quotes were eaten by the enclosing double-quoted `echo`, producing invalid JSON), and it carried no auth. Both are fixed with escaped quoting, verified by executing the echo.
+
+## Decision-point inventory
+
+- `tests/unit/job-template-auth-lint.test.ts` — **add** — a CI lint (build-time signal). It has no runtime surface and cannot gate, delay, or block any agent action.
+- Job template bodies — **modify** — these are LLM instructions, not code. They do not make block/allow decisions; they instruct the reading agent which HTTP calls to make.
+- `src/server/middleware.ts` `authMiddleware()` — **pass-through** — not modified. The lint mirrors its public-path exemptions and asserts (drift guard) that each exempted path still appears there.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The only rejecting surface is the CI lint, and its over-block risk is a false CI failure on a healthy template. This risk **materialized during development and was fixed**: the first draft anchored the `AUTH=` definition check to line-start (`/^\s*AUTH=/m`) and falsely accused three healthy templates (`initiative-digest-review.md`, `mentor-onboarding.md`, `org-intent-drift-audit.md`) that legitimately define `AUTH` inside backticks as a prose step (`0. **Set auth context:** \`AUTH="..."\``). The detector now matches `AUTH=` not preceded by `$` or a word character, and a regression test (`accepts an AUTH definition presented as a prose step in backticks`) pins the fix.
+
+Residual over-block risk: a future template that intentionally calls a non-public endpoint *without* auth (e.g. to demonstrate a 401 in documentation prose) would be flagged. No such template exists today; the fix would be to exempt it explicitly rather than weaken the rule.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+Concrete and acknowledged:
+
+- **Multi-line curl continuations.** The detector scopes a curl invocation to its line. A template using `curl \` + newline + `-H "Authorization: ..."` would have its header on the next line and be flagged (over-block) — or, if the URL is on a later line, the call would not be seen at all (under-block). No shipped template uses continuations; all are single-line.
+- **Non-curl HTTP clients.** A template instructing `wget`, `httpie`, or a `node -e` fetch is not scanned at all.
+- **Correct header, wrong token.** The lint verifies an `Authorization: Bearer` header is *present*; it cannot verify the token *resolves*. That is exactly the `identity-review.md` failure mode (header present, value stale) — caught here by a separate assertion requiring the env-first `${INSTAR_AUTH_TOKEN:-` form in the six known templates, not by the generic rule.
+- **Runtime drift.** A template can be correct at CI time and still 401 at runtime if `$INSTAR_AUTH_TOKEN` is absent from the job environment *and* config.json is stale. The lint cannot see runtime env.
+- **Endpoints that become non-public later.** If a currently-public path (say `/ping`) later requires auth, the lint would keep exempting it. The drift guard only catches *removal* of the path from middleware.ts, not a change in its auth posture.
+
+---
+
+## 3. Level-of-abstraction fit
+
+This is a **build-time lint** — the correct layer. The defect is static text in a shipped artifact, fully determinable from source, so it belongs in CI rather than at runtime.
+
+Considered and rejected: a runtime check that inspects job bodies before dispatch. That would be the wrong layer — it would pay a cost on every job run to detect a fault that cannot change after the template ships, and it would need blocking authority to be useful, which the signal-vs-authority principle forbids for logic this brittle.
+
+The lint extends the existing template-validation family (`default-jobs-valid.test.ts`, `PostUpdateMigrator-templateResolution.test.ts`) rather than running parallel to it. It reads its exemption set *from* the real authority (`middleware.ts`) rather than re-deriving one.
+
+---
+
+## 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?**
+
+- [x] No — this change has no block/allow surface.
+
+The lint is a test. Its only power is failing a build. It holds no authority over any agent at runtime: it cannot block a message, gate a job, delay a session, or constrain a decision. The template edits are instructions to an LLM, not control flow. Nothing in this change can refuse an agent action.
+
+---
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+**No new static heuristic at a competing-signals decision point.** The question "does this curl carry an Authorization header, and is its endpoint public?" is fully enumerable from source: the public-path set is a finite list read from `authMiddleware()`, and header presence is a textual fact. There are no competing live signals to weigh — no work evidence, liveness, recency, or ownership inputs. This is an invariant check, not a judgment point.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** None. The lint is an independent test file; vitest runs it alongside the existing template tests with no ordering dependency. It does not shadow `default-jobs-valid.test.ts` (which validates job *structure* from `init.ts`, not template *body content*) — the two cover disjoint surfaces.
+- **Double-fire:** None. No runtime component acts on this.
+- **Races:** None. The lint only reads files at test time.
+- **Feedback loops:** One worth naming explicitly. `evolution-proposal-implement.md` is the template that runs the job that produced this change — the fix is self-referential. It is *not* a loop: the template is data read by a scheduled job, and repairing it changes which HTTP calls a future run makes, not whether this change is correct. Verified by executing the fixed commands directly against the live server rather than trusting the job's own behavior.
+- **Migration parity:** `installBuiltinJobs()` (`src/scheduler/InstallBuiltinJobs.ts:127`) unconditionally `writeFileSync`-es every shipped template over the deployed copy, and is called from `PostUpdateMigrator.ts:4046` on every update run. Verified first-hand by reading both call sites. **No separate `PostUpdateMigrator` entry is needed** — and, critically, patching the deployed copies by hand would have been *reverted* at the next update, producing a transient fix indistinguishable from a real one. The durable fix is the source templates, which is what this change edits.
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** No change. Templates are per-agent state; each agent receives the fixed copy at its next install/update.
+- **Other users of the install base:** Yes, positively — five scheduled jobs that have been silently no-op-ing on every install will begin functioning. Anyone who had these jobs enabled gets working evolution/insight/reflection/identity jobs. Worth calling out in release notes: behavior that appeared "quiet and healthy" will start producing real output.
+- **External systems:** None. All calls are to `localhost`.
+- **Persistent state:** None added. The jobs will now successfully write to existing stores (evolution proposals/actions/learnings, reflection records) that they were previously failing to reach — that is the intended repair, not a new surface.
+- **Timing / runtime conditions:** The fix depends on `$INSTAR_AUTH_TOKEN` being present in the job environment (verified present, 36 chars) with config.json as fallback.
+- **Operator surface (Mobile-Complete Operator Actions):** No operator-facing actions added or touched. This change adds no route, form, approval, or grant.
+
+---
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+**No operator surface — not applicable.** No dashboard renderer, markup file, approval page, or grant/revoke/secret-drop form is touched. The change is confined to shipped job-template markdown and a test file.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN**, with reason: job templates are installed onto each machine's own `.instar/jobs/instar/` by that machine's own `installBuiltinJobs()` run, and the auth token they resolve (`$INSTAR_AUTH_TOKEN` / that machine's `config.json`) is **necessarily** machine-local — each install holds its own `authToken`, and a shared token cannot work cross-machine. Replicating template content or tokens across machines would be actively wrong.
+
+Every machine converges on the same fixed template content through the same update path, so there is no divergence risk: this is not "machine-local state that should have been replicated", it is identical shipped content resolved against per-machine credentials.
+
+- **User-facing notices:** None emitted by this change. (The *jobs* may now emit notices they previously failed to produce, but each job's own one-voice/topic-routing behavior is unchanged by this fix.)
+- **Durable state on topic transfer:** None held. Nothing strands on a topic move.
+- **Generated URLs:** None generated. All URLs are `localhost` calls made by the job on its own machine, which is correct — they are never shared or sent to a user.
+
+---
+
+## 8. Rollback cost
+
+- **Hot-fix release:** Revert the six template files and the test; ship as a patch. Existing agents pick up the reverted content at their next update via the same `installBuiltinJobs()` overwrite path.
+- **Data migration:** None. No schema, column, or persistent state introduced.
+- **Agent state repair:** None required.
+- **User visibility during rollback:** Reverting restores the *previous broken behavior* (jobs silently no-op again). No error state, no crash, no data loss — the pre-fix behavior was quiet failure, so a rollback is quiet too. That asymmetry is itself the argument for why this class of bug survived so long.
+
+Rollback risk is minimal: worst case is a return to the status quo ante.
+
+---
+
+## Conclusion
+
+This review produced two changes to the work in progress. First, the lint's `AUTH=` detector was rewritten after it falsely accused three healthy templates — a real over-block caught before commit, now pinned by a regression test. Second, the scope grew by two genuine same-class defects found by reading rather than assuming: `identity-review.md`'s config-only token read (broken on this very agent, proven by executing both tokens against the live server) and `reflection-trigger.md`'s quote-mangled JSON body.
+
+The change is clear to ship. It has no runtime authority, no persistent state, no operator surface, and a trivial rollback. The verification is first-hand rather than proxy: the lint was proven to report **exactly** the 12 pre-fix violations when run against the original content from `HEAD` and zero after, and the fixed commands were executed against the live server returning real data instead of 401.
+
+One honest limitation, stated rather than buried: the lint verifies an auth header is *present*, not that its token *resolves*. Token-resolution correctness is covered for the six known templates by the env-first assertion, but a future template could pass the lint and still 401 with a stale token. Closing that would require a runtime check, which is the wrong layer for the reasons in §3.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required.
+
+Phase 5 triggers on changes touching block/allow decisions on messaging or dispatch, session lifecycle, context/compaction, coherence gates, trust levels, or any sentinel/guard/gate/watchdog. This change touches none of them: it is shipped instruction text plus a CI lint with no runtime surface. The word "gate" appears in the templates' `gate:` frontmatter field, but those lines are **not modified** by this change.
+
+---
+
+## Evidence pointers
+
+- **Lint bites (pre-fix):** running the detector against the six original files extracted from `HEAD` reported exactly 12 unauthenticated calls — `evolution-overdue-check` 3, `evolution-proposal-evaluate` 3, `evolution-proposal-implement` 2, `insight-harvest` 3, `reflection-trigger` 1 — matching the independently-derived census. Post-fix: 0.
+- **Live 401 → 200:** `curl` to `/evolution/proposals?status=approved` with no header returns `{"error":"Missing or invalid Authorization header"}`; the fixed template's resolved command returns the real proposal list. Same confirmed for `/evolution/learnings?applied=false` and `/evolution/actions/overdue`.
+- **Stale-config proof:** the 16-char `config.json` token returns `{"error":"Invalid auth token"}`; the 36-char `$INSTAR_AUTH_TOKEN` succeeds — the concrete reason `identity-review.md` needed the env-first form.
+- **Quoting proof:** executing the original `reflection-trigger.md` echo renders `-d '{type:quick}'` (invalid JSON); the fixed line renders `-d '{"type":"quick"}'` with the token name left unexpanded so no secret enters the transcript.
+- **Migration parity:** `InstallBuiltinJobs.ts:127` unconditional overwrite, reached from `PostUpdateMigrator.ts:4046`.
+- **Tests:** `tests/unit/job-template-auth-lint.test.ts` (9 tests) green; template-family tests (`refresh-jobs`, `default-jobs-valid`, `PostUpdateMigrator-templateResolution`) green.
+
+---
+
+## Class-Closure Declaration (display-only mirror)
+
+- **`defectClass`** — `novel` is *not* claimed. This is an instance of the existing **unverified-claim / proxy-signal** family already tracked by EVO-004 (ACT-930), EVO-005, and EVO-006 (ACT-985): a signal adjacent to the real terminal state (the `gate:` passing, "the job ran quietly") was treated as evidence of the terminal state (the job actually did its work). Recorded here as `defectClass: proxy-signal-substitution`.
+- **`closure`** — `guard`.
+- **`guardEvidence`** — `{enforcementType: lint, citation: tests/unit/job-template-auth-lint.test.ts#"every shipped template authenticates its non-public API calls", howCaught: the lint scans every shipped template body for curl calls to non-public endpoints lacking an Authorization header and fails the build; run against the pre-fix content it reports exactly the 12 violations that shipped, so this defect could not have reached main with the guard in place}`.
+- **`gap`** — none for the template-text class. The broader "a job that silently no-ops looks identical to a healthy quiet job" class is **not** closed by this change and remains tracked under the EVO-005/EVO-006 family; this fix closes only the specific mechanism (missing auth header in shipped template text).

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

@@ -33,6 +33,38 @@ silent.
 
 ## 2. Under-block — what does it still miss?
 
+**Found in practice, not in review:** the first version recognised only per-round
+`## Round-N … change log` headings. Pointed at a second spec that consolidates its
+history into a single `## Review record` section, it matched nothing, stripped
+nothing, reported `0 history sections excluded` and **exited 0**. A silent no-op
+that presents as success — the same species as a check that cannot run.
+
+Widened by one alternative (`Review record`). The residual is unchanged and now
+explicit: the pattern is a closed list of heading shapes, so a document using a
+convention not on the list is silently unstripped. The mitigation is the output
+line itself — it always reports how many sections it excluded, so *reading* it
+catches this. The ELI16 now says so directly.
+
+
+**Found again, worse, by pointing the tool at its own output (round-37, codex).**
+The generated contract was reviewed as the build artifact for the first time, and
+it was **not contract-only**: blockquote meta-blocks survived, including a
+"NON-NORMATIVE FROM HERE" marker sitting inside a file whose banner claimed
+review history was "deliberately absent." A boundary marker inside a document
+that denies having boundaries is worse than no marker — and the banner was
+straightforwardly false.
+
+Two fixes, one mechanical and one honest:
+
+1. **Meta-blockquotes are now stripped** — blocks that talk *about* the document
+   (normative-boundary markers, "this file is rationale", scope notices) rather
+   than about the design. Counted and reported separately from history sections.
+2. **The banner no longer overclaims.** It now states what is removed, what is
+   *not* removed, and prints the **count of narrative round-references remaining**
+   in the file. The previous wording promised absence it could not deliver, which
+   is exactly the class of overclaim the spec under review kept being corrected
+   for. A tool that lies in its own header is worse than one with a stated limit.
+
 - **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
@@ -44,6 +76,121 @@ silent.
   contradictory. The separate spec lint (required by the outbound spec) is what
   addresses that; this is not it.
 
+### `--strict` (allowlist mode) — over/under-block
+
+**Over-block risk, and it is real:** an allowlist drops a genuinely normative
+section whose heading is not on the list. That is a *silent* omission — the
+opposite failure from the denylist's silent retention. Mitigated by the run
+reporting `N allowlisted sections kept`: a spec that should yield 10 sections and
+reports 2 is visibly wrong, which is exactly how the missing-trailing-period bug
+in the heading pattern was caught (§4 "Honest limits" and §5 "Test plan" were
+silently dropped until the count was read).
+
+That mitigation is a human reading a number, which is weaker than a check. The
+honest position: **`--strict` trades a silent-retention failure for a
+silent-omission failure**, and the omission is the one that could cause a missing
+requirement rather than a confusing one. It is therefore additive and opt-in —
+the default denylist mode and its output path are unchanged, and no build gate
+requires strict mode.
+
+**The over-block risk was confirmed within an hour of shipping it.** Pointed at
+`outbound-gate-advisory-override`, strict mode kept 8 of 66 sections and dropped
+the normative outcome table, whose headings are not on the allowlist. The
+reviewer's *first* finding was "normative behavior is missing from the strict
+contract" — the exact silent-omission failure predicted above, on the first spec
+with a different heading scheme.
+
+**Guard added:** strict mode now computes the kept-section ratio and prints a
+`WARNING (strict)` when a spec with >=8 headings matches under 25% of them,
+naming the ratio and saying the output may be missing normative sections. It
+fires on `outbound-gate-advisory-override` (8/66, 12%) and stays silent on
+`inbound-message-recording-gap` (11 sections, 41% capture) — a real signal on the
+real failure, no noise on the working case.
+
+The guard is a warning, not a refusal, and deliberately: the ratio is a heuristic,
+and a genuinely rationale-heavy spec can legitimately capture low. A refusal on a
+heuristic would block correct output; a warning that names the number lets a human
+apply the judgment the tool does not have.
+
+### A third failure mode, found by shipping it (2026-07-25)
+
+The capture-ratio warning guards against *too few sections matching*. It does not
+see **a matched section that captured nothing** — and that happened live: adding a
+`### Normative checklist` heading inside the allowlisted `### 3.0 Final contract`
+ended that section's capture, dropping the entire contract table **and the new
+checklist** from the output. The section count stayed at 10, so the existing guard
+was silent, and the emptied contract would have shipped.
+
+A second guard now compares **captured bytes against source bytes per section**
+and warns when a section captures under 25% of a source section over 1 KB.
+
+**Getting it right took three attempts, each verified against the real regression
+rather than assumed:**
+
+1. *Average bytes per section* — nine healthy sections masked one empty one.
+2. *Absolute per-section threshold* — permanently false-positived on legitimate
+   container headings (`## 4. Honest limits` immediately followed by an allowlisted
+   `### 4.0 …`). **A guard that always warns is a guard nobody reads.**
+3. *Captured vs source, per section* — worked only after the source measurement
+   stopped using the capture's own stopping rule, which had made it shrink in
+   lockstep with the truncation it was meant to detect.
+
+Verified in both directions each time: fires on the regression, silent on the
+correct file, large-spec behaviour unchanged.
+
+### The guard's own false-positive mode (found before merge)
+
+The captured-vs-source guard fired permanently on every **numbered** spec. Cause:
+the source measure deliberately does not use the capture's stopping rule (or it
+would shrink in lockstep with the truncation it detects), so it ran past the next
+*sibling* section and counted that sibling's bytes as "missing".
+
+Both shapes look identical structurally — a same-level heading follows an
+allowlisted one:
+
+- `### 3.0 Final contract` → `### Normative checklist` — meant as a **child**;
+  its content belongs to 3.0 and losing it is a real defect.
+- `### 3.10 Test plan` → `### 3.11 Judgeable-record` — a genuine **sibling**;
+  its content was never 3.10's and excluding it is correct.
+
+Separated by a numbered-sibling test. Verified in both directions: silent on the
+numbered spec, still warning on the child-heading regression.
+
+**This is the third time this guard needed correcting, and the second time the
+failure was "it warns constantly".** That mode is worth naming as its own defect
+class: a permanently-firing warning is not a conservative guard, it is a disabled
+one, because the reader stops looking.
+
+**Also fixed before merge:** a nonexistent `--spec` path threw a raw Node stack
+trace; it now exits 2 with a one-line error.
+
+### The allowlist was too narrow to be useful on a second spec
+
+Pointed at `outbound-gate-advisory-override`, strict mode produced a contract
+**that began at the test plan** — no design section, no schema, no outcome table.
+That is why an external reviewer reading it said *"normative behavior is missing
+from the strict contract"*: it genuinely was. The capture-ratio warning fired
+(8/66 sections, 12%) and was noted at the time **and not acted on**, so a
+contract that could not be built from sat in the repo for three hours looking
+like an artifact.
+
+Cause: the allowlist held one spec's section names. The other spec's
+contract-bearing sections are called `0.0 What an implementer builds`,
+`0.2 Current design overview`, `0. Glossary` and `3.8.1 Normative outcome table`
+— all genuinely normative, none matched.
+
+Widened by those four plus `Fail directions`, and the numbering pattern relaxed
+to multi-level (`3.8.1`). Capture went 8→13 sections and the contract now opens
+with what an implementer builds. Verified no change to the other spec (10
+sections, byte-identical behaviour) and the child-heading regression still warns.
+
+**The warning was working and I treated it as information rather than a defect.**
+A guard that fires and gets noted is only half a guard; the other half is
+someone acting on it.
+
+**Under-block:** unchanged. A rule narrated inside an allowlisted section still
+carries its own history; strict mode reduces the surface, it does not clean prose.
+
 ## 3. Level-of-abstraction fit
 
 Correct layer: it is a build-time document transform, alongside the other
@@ -124,3 +271,43 @@ without the generator).
 **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.
+
+---
+
+## Addendum (2026-07-25 15:5xZ) — hierarchical capture for sub-headings
+
+**What changed.** `splitStrictContract` reset `keeping` on *every* H1–H3, so an
+allowlisted `## 3. Design` was closed by its own first child `### 3.1`. Capture
+is now hierarchical: a NON-allowlisted heading DEEPER than the open section
+rides along; a sibling or an allowlisted heading still closes it. `Design` was
+also added to the heading allowlist (`## 3. Design` previously matched nothing).
+
+**Why it matters.** Measured on the outbound-gate spec: the design section
+shipped as **14 bytes of 86,314**. The section COUNT was correct, so the
+contract looked complete. Reviews run against it produced four objections the
+missing text already answered, and I relayed them to the operator as reasons to
+withhold approval; all four were later withdrawn.
+
+1. **Over-block** — none. The change only ADDS content that was being dropped.
+   Verified: outbound-gate +1212 lines / −1; inbound +2 / −0. No section lost.
+2. **Under-block** — a spec whose normative heading is neither allowlisted nor a
+   child of an allowlisted section is still dropped. The existing ratio warning
+   plus the under-capture guard remain the detection for that.
+3. **Level-of-abstraction fit** — right layer. The defect was in the capture
+   loop; nothing downstream could have recovered the missing bytes.
+4. **Signal vs authority** — unchanged. The generator emits an artifact and
+   warnings; it blocks nothing.
+5. **Interactions** — the pre-pass source-sizing loop is untouched, so the
+   under-capture guard still measures against the same baseline and correctly
+   went quiet for §3 once the capture was fixed.
+6. **External surfaces** — regenerated contracts are committed alongside, so no
+   consumer sees a stale artifact.
+7. **Multi-machine posture** — machine-local BY DESIGN: a build-time script over
+   files in the repo checkout. No runtime state, no replication surface.
+8. **Rollback cost** — revert the commit and regenerate; contracts return to
+   their prior bytes. No migration, no persisted state.
+
+**Tests.** `tests/unit/generate-spec-contract-nesting.test.ts` — the first
+coverage this tool has had. Verified failing against the pre-fix code (2 of 3)
+and passing after, so it is a real regression guard rather than a restatement
+of current behaviour.