instar 1.3.897 → 1.3.898

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.897",
+  "version": "1.3.898",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",
@@ -93,6 +93,7 @@
     "src/templates",
     "src/data",
     "src/threadline/data",
+    "src/core/FeatureMaturationPlanGate.mjs",
     "skills",
     "playbook-scripts",
     "scripts",

package/scripts/feature-maturation-plan-gate.mjs

@@ -0,0 +1 @@
+export * from '../src/core/FeatureMaturationPlanGate.mjs';

package/skills/spec-converge/scripts/write-convergence-tag.mjs

@@ -48,6 +48,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { checkEli16Overview } from '../../../scripts/eli16-overview-check.mjs';
+import { findMaturationPlanGaps } from '../../../scripts/feature-maturation-plan-gate.mjs';
 
 function parseArgs() {
   const args = process.argv.slice(2);
@@ -282,6 +283,18 @@ if (!dpGate.ok) {
   process.exit(1);
 }
 
+// Feature Maturation Discipline v1: SIGNAL only. Missing/partial structure is
+// visible during convergence but MUST NOT change the stamp's exit status.
+const maturationGate = findMaturationPlanGaps(content);
+if (!maturationGate.ok) {
+  const details = [
+    maturationGate.reason,
+    maturationGate.missing?.length ? `missing=${maturationGate.missing.join(',')}` : '',
+    maturationGate.duplicates?.length ? `duplicates=${maturationGate.duplicates.join(',')}` : '',
+  ].filter(Boolean).join(' ');
+  console.error(`MATURATION_PLAN_WARN ${specArg}: ${details}`);
+}
+
 // Parse YAML frontmatter manually (no dependency).
 // Expect: /^---\n<body>\n---\n<rest>/
 const FM_RE = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;

package/src/core/FeatureMaturationPlanGate.mjs

@@ -0,0 +1,58 @@
+/**
+ * Pure WARN-stage structural detector for `## Maturation plan`.
+ * Semantic adequacy belongs to spec-converge's lessons-aware reviewer.
+ */
+
+const REQUIRED_FIELDS = [
+  'test-agent-live',
+  'dev-agent-live',
+  'fleet',
+  'graduation criterion',
+  'dark-window',
+];
+
+function reviewableMarkdown(input) {
+  let body = String(input).replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
+  body = body.replace(/<!--[^]*?-->/g, '');
+  const lines = body.split(/\r?\n/);
+  let fence = null;
+  return lines.map((line) => {
+    const marker = line.match(/^\s*(`{3,}|~{3,})/);
+    if (marker) {
+      const token = marker[1][0];
+      if (fence === null) fence = token;
+      else if (fence === token) fence = null;
+      return '';
+    }
+    if (fence !== null || /^\s*>/.test(line)) return '';
+    return line;
+  }).join('\n');
+}
+
+export function findMaturationPlanGaps(specBody) {
+  const body = reviewableMarkdown(specBody);
+  const headings = [...body.matchAll(/^##[ \t]+Maturation plan[ \t]*$/gim)];
+  if (headings.length === 0) return { ok: false, reason: 'missing-section' };
+  if (headings.length > 1) return { ok: false, reason: 'duplicate-section' };
+
+  const start = headings[0].index + headings[0][0].length;
+  const rest = body.slice(start);
+  const nextH2 = rest.search(/^##[ \t]+/m);
+  const section = nextH2 === -1 ? rest : rest.slice(0, nextH2);
+  const found = new Map();
+  for (const line of section.split('\n')) {
+    const match = line.match(/^\s*[-*+]\s+\*\*([^*]+):\*\*\s+(.+?)\s*$/);
+    if (!match) continue;
+    const label = match[1].trim().toLowerCase();
+    if (!REQUIRED_FIELDS.includes(label)) continue;
+    found.set(label, [...(found.get(label) ?? []), match[2].trim()]);
+  }
+  const missing = REQUIRED_FIELDS.filter((field) => !found.has(field));
+  const duplicates = REQUIRED_FIELDS.filter((field) => (found.get(field)?.length ?? 0) > 1);
+  if (missing.length || duplicates.length) {
+    return { ok: false, reason: 'invalid-fields', missing, duplicates };
+  }
+  return { ok: true };
+}
+
+export { REQUIRED_FIELDS };

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-21T14:20:41.746Z",
-  "instarVersion": "1.3.897",
+  "generatedAt": "2026-07-21T19:01:03.327Z",
+  "instarVersion": "1.3.898",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1562,7 +1562,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "605aa7a479ae72d567965411e8e51a56e13a701cd3c74857463eb346103d1b48",
+      "contentHash": "450f643c7131816527081601898528e6e46263d8a0bc87127dbd28136b0e1471",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.3.898.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- Strengthened the existing Maturation Path standard around the fixed test-agent → development-agent → fleet ladder.
+- Added a WARN-only structural check for `## Maturation plan`; convergence still succeeds while missing or partial plans emit `MATURATION_PLAN_WARN`.
+- Added durable, customization-safe update delivery for existing agent installations.
+
+## What to Tell Your User
+
+New staged-feature specs now make their graduation plan visible during review. This first increment warns without blocking so the format can mature safely before enforcement becomes hard.
+
+## Summary of New Capabilities
+
+- Detect missing or incomplete three-rung maturation plans during spec convergence.
+- Preserve customized installed tooling while safely updating recognized stock files.
+
+## Evidence
+
+- 44 targeted tests pass across the new parser, convergence wiring, migration failures, existing decision-point parsing, and standards enforcement audit.
+- Full TypeScript and repository lint pass.

package/upgrades/side-effects/feature-maturation-plan-visibility.md

@@ -0,0 +1,84 @@
+# Side-Effects Review — Feature maturation plan visibility
+
+**Version / slug:** `feature-maturation-plan-visibility`
+**Date:** `2026-07-21`
+**Author:** `Instar-codey`
+**Second-pass reviewer:** `maturation_second_pass`
+
+## Summary of the change
+
+This strengthens the existing Maturation Path registry article, adds a pure Markdown structure detector, emits a WARN-only diagnostic from the existing convergence tag writer, and delivers both files through PostUpdateMigrator with hash-based customization detection and durable replacement.
+
+## Decision-point inventory
+
+- `findMaturationPlanGaps` — add — pure structural signal with no blocking authority.
+- convergence tag writer — modify — reports the signal but retains exit status and stamping behavior.
+- migration stock/custom classification — add — deterministic closed-world content-hash invariant protecting user customizations.
+
+## 1. Over-block
+
+No runtime block exists. A valid non-canonical plan can warn, but v1 still stamps convergence. The canonical accepted form is documented and tested.
+
+## 2. Under-block
+
+A syntactically complete but poor plan is not rejected. This is intentional: structural parsing is a cheap signal; the lessons-aware reviewer holds semantic authority.
+
+## 3. Level-of-abstraction fit
+
+The validator sits beside the existing `findDecisionPointGaps` convergence seam. The standard is updated in place. Runtime graduation remains owned by FeatureRolloutReconciler and InitiativeTracker; no parallel engine exists.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change produces a signal consumed by an existing smart gate.
+
+The Markdown parser only reports missing deterministic structure. It cannot veto convergence or judge plan quality.
+
+## 4b. Judgment-point check
+
+No new heuristic at a competing-signals decision point. Stock-file hash membership and structural field presence are closed-world invariants. Semantic maturation quality remains a reviewer judgment.
+
+## 5. Interactions
+
+- **Shadowing:** the warning runs after existing open-question and decision-point hard gates, and before tag writing. It cannot shadow either gate.
+- **Double-fire:** one invocation emits at most one stable warning line.
+- **Races:** migration writes use unique sibling temps, exclusive create, file and directory sync, and same-filesystem rename.
+- **Feedback loops:** none in v1; no scheduler or initiative cadence is added.
+
+## 6. External surfaces
+
+Developers may see a new stderr warning during spec convergence. No messages, routes, external APIs, persistent runtime records, or operator actions are added.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable.
+
+## 7. Multi-machine posture
+
+Unified: the detector, tag writer, and standard are git/package artifacts delivered identically to each machine. V1 emits no notice, durable rollout state, or URL. Existing customized targets remain local by user choice and are reported untouched.
+
+## 8. Rollback cost
+
+Revert and ship a patch. The warning creates no data. Installed stock files retain durable pre-migration backups; customized files are never modified.
+
+## Conclusion
+
+The change is bounded to warning visibility, extends the correct existing owners, and preserves semantic authority. The main risks—parser false positives and migration corruption—are non-blocking or covered by adversarial and injected-failure tests.
+
+## Second-pass review (if required)
+
+**Reviewer:** maturation_second_pass
+**Independent read of the artifact:** concur
+
+Concur with the review — the implementation now preserves WARN-only signal authority, exact gate classification, customization-safe durable migration parity, and the v1-only boundary with all 26 targeted tests passing.
+
+## Evidence pointers
+
+- `tests/unit/feature-maturation-plan-gate.test.ts`
+- `tests/unit/write-convergence-tag-maturation-plan.test.ts`
+- `tests/unit/PostUpdateMigrator-feature-maturation.test.ts`
+
+## Class-Closure Declaration (display-only mirror)
+
+No agent-authored-artifact defect — not applicable. This is a new WARN-stage guard, not a defect repair or self-triggered controller.