instar 1.3.1017 → 1.3.1019

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1017",
+  "version": "1.3.1019",
   "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/lint-rollout-evidence-resolvable.js

@@ -115,18 +115,39 @@ for (const file of specFiles()) {
   try { text = fs.readFileSync(file, 'utf8'); } catch { continue; }
   const fm = frontmatter(text);
   if (!fm) continue;
-  if (field(fm, 'rollout-disposition') !== 'active') continue;
+  // GUARDED DISPOSITIONS — 'active' AND 'composed'.
+  //
+  // 'composed' does NOT mean exempt. It names WHO owns graduation (the rollout rides
+  // an owner feature via rollout-owner-feature) rather than WHETHER the evidence
+  // matters. A composed spec still carries a real rollout-criteria naming a
+  // measurement, and often rollout-metrics-json thresholds against it. If its ref
+  // 404s the criterion is exactly as unevaluable as an active one's, and the feature
+  // parks for exactly the same reason.
+  //
+  // Widening is safe BECAUSE of assertion C rather than in spite of it: a composed
+  // spec whose owner feature was genuinely abandoned may legitimately carry a stale
+  // ref, and the shrink-only baseline is where that goes — with a stated reason,
+  // deleted automatically the moment the ref starts resolving. So this does not force
+  // anyone to FIX anything; it forces them to DECLARE. Entry needs evidence.
+  //
+  // EARNED (2026-07-27): this lint shipped guarding 'active' only, and its own header
+  // said "a sweep of all 5 rollout-active specs" — accurate for its scope, and the
+  // scope was narrower than the class it names. A single-pass sweep is incomplete by
+  // definition (Iterative Audit to Convergence); this is that standard applied to the
+  // guard itself, one pass later.
+  const disposition = field(fm, 'rollout-disposition');
+  if (disposition !== 'active' && disposition !== 'composed') continue;
   if (field(fm, 'rollout-evidence-type') !== 'endpoint') continue;
   const ref = field(fm, 'rollout-evidence-ref');
   if (!ref || !ref.startsWith('/')) continue; // unparseable ⇒ skip, not fail
   const slug = field(fm, 'slug') || path.basename(file, '.md');
   const resolves = srcContains(ref);
-  seenActive.push({ slug, ref, resolves });
+  seenActive.push({ slug, ref, resolves, disposition });
 
   // A — every active endpoint ref resolves, unless explicitly accepted.
   if (!resolves && !allowed.has(slug)) {
     errors.push(
-      `${path.relative(ROOT, file)}: rollout-disposition:active names ` +
+      `${path.relative(ROOT, file)}: rollout-disposition:${disposition} names ` +
       `rollout-evidence-ref "${ref}" but no route with that path exists in src/. ` +
       `The graduation criterion can never be evaluated, so this rollout is parked ` +
       `indefinitely. Build the endpoint, correct the ref, or add an explicit ` +
@@ -157,6 +178,8 @@ if (errors.length) {
   process.exit(1);
 }
 console.log(
-  `lint-rollout-evidence-resolvable: clean — ${seenActive.length} rollout-active endpoint spec(s), ` +
+  `lint-rollout-evidence-resolvable: clean — ${seenActive.length} guarded endpoint spec(s) ` +
+  `(${seenActive.filter((s) => s.disposition === 'active').length} active, ` +
+  `${seenActive.filter((s) => s.disposition === 'composed').length} composed), ` +
   `${seenActive.filter((s) => s.resolves).length} resolving, ${allowed.size} accepted-unresolved.`,
 );

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

@@ -102,12 +102,44 @@ function parseArgs() {
  * Anything else with content (e.g. a `- **Q1:** …` bullet or a paragraph posing
  * a question) is an unresolved entry.
  */
+/**
+ * Builds the H2 matcher for a named gate section.
+ *
+ * ONE builder, used by BOTH gate sections, deliberately: the numbered-heading
+ * hole below existed because the two matchers were written separately and only
+ * one of them ever got a heading-variance fix. A shared builder means the next
+ * variance fix cannot land on one gate and miss its sibling.
+ *
+ * Tolerated shapes:
+ *   - `## Open questions`                    (canonical)
+ *   - `## 9. Open questions`                 (numbered — the hole this closes)
+ *   - `## 8b. Open questions` / `## 3) …`    (lettered / paren'd)
+ *   - `## 1.2 Open questions`                (dotted)
+ *   - `## Open questions (round 2)`          (suffix variant — already worked)
+ *
+ * Why this was load-bearing: `findOpenQuestions` returns `[]` when the heading
+ * does not match, and `[]` means "nothing parked on the user". So a NUMBERED
+ * heading made a LIVE, unresolved user-decision invisible to the gate the skill
+ * calls structural ("cannot be skipped by prose"). Verified with a control
+ * before the fix: numbered heading + a live question → `[]`; the identical
+ * question under a plain heading → caught. Its sibling `findDecisionPointGaps`
+ * failed CLOSED on the very same input — two defaults for one quantity.
+ */
+const SECTION_LABEL = String.raw`(?:\d+(?:\.\d+)*[a-z]?[.)]?\s+)?`;
+function gateSectionHeadingRe(name) {
+  return new RegExp(String.raw`^##\s+${SECTION_LABEL}${name}\b[^\n]*$`, 'im');
+}
+
 export function findOpenQuestions(specBody) {
   // \b…[^\n]*$ (not \s*$) so heading variants like "## Open questions (round 2)"
   // or "## Open Questions & Decisions" are still recognized — a variant heading
   // must not make the section invisible to the gate (reviewer finding, PR 2).
-  const m = specBody.match(/^##\s+Open questions\b[^\n]*$/im);
-  if (!m) return []; // no section → nothing parked on the user
+  // SECTION_LABEL additionally tolerates a numbered prefix (see the builder).
+  const m = specBody.match(gateSectionHeadingRe('Open questions'));
+  // A genuinely ABSENT section still means nothing is parked on the user; that
+  // semantic is unchanged and separately tested. What changed is that a present
+  // section can no longer hide behind its own section number.
+  if (!m) return [];
   const start = m.index + m[0].length;
   const restAfter = specBody.slice(start);
   const nextHeading = restAfter.search(/^##\s+/m);
@@ -144,7 +176,11 @@ export const GRANDFATHERED_SLUGS = [
 
 export function findDecisionPointGaps(specBody, slug) {
   if (slug && GRANDFATHERED_SLUGS.includes(slug)) return { ok: true };
-  const m = specBody.match(/^##\s+Decision points touched\b[^\n]*$/im);
+  // Same shared builder as findOpenQuestions — this gate already failed CLOSED
+  // on a numbered heading (correct direction), but it was refusing specs whose
+  // section was PRESENT and merely numbered, which is a false refusal rather
+  // than a safety property. Both gates now recognise the same heading shapes.
+  const m = specBody.match(gateSectionHeadingRe('Decision points touched'));
   if (!m) return { ok: false, reason: 'missing-section' };
   const start = m.index + m[0].length;
   const restAfter = specBody.slice(start);

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-27T21:51:05.954Z",
-  "instarVersion": "1.3.1017",
+  "generatedAt": "2026-07-27T22:23:55.031Z",
+  "instarVersion": "1.3.1019",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.1018.md

@@ -0,0 +1,66 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+A correction made earlier today to how design reviews decide they are finished now actually reaches
+agents that are already running. It previously did not.
+
+Tools like that review process exist both in what ships and as a copy on each running agent's disk.
+The install step deliberately never overwrites an existing copy, in case an operator has customised
+it, so an update reaches running agents only through a small dedicated delivery step. One already
+existed for this file — but its "have I done this already?" check was keyed to an older change, so
+once an agent had taken that one it quietly stopped delivering anything further to the same file.
+
+The build guard that stops a switched-off feature from claiming a graduation condition it can
+never check now covers a second kind of feature document it previously skipped.
+
+Some features graduate alongside a bigger parent feature rather than on their own. The guard
+treated those as out of scope. They are not: such a feature still states its own condition and
+still names an address to read it from, so a missing address parks it for exactly the same
+reason. Three feature documents sat outside the guard; all three are now covered.
+
+## What to Tell Your User
+
+Nothing changes in how your agent behaves day to day. A fix that had been shipped but could not
+reach already-running agents now reaches them.
+
+Nothing changes in how your agent behaves. A safety check that runs when the project is built
+now looks at a few more files than it used to.
+
+## Summary of New Capabilities
+
+None. No endpoint, config key, or behaviour is added. This is a delivery step so an existing fix
+arrives where it was always meant to go.
+
+Agents that have customised the file keep their version untouched, agents that already have the
+correction are unaffected, and a fresh install is unchanged.
+
+None. No endpoint, config key, or behaviour is added. This widens the scope of an existing
+build-time check and reports its two counts separately, so a future narrowing shows up as a
+number dropping rather than as silence.
+
+Widening it forces no new work on anyone. The guard already carries an escape hatch — a list
+of accepted exceptions, each requiring a written reason, each deleted automatically once its
+address starts working. A feature whose parent was genuinely abandoned needs a declaration,
+not a fix.
+
+## Evidence
+
+The gap was confirmed on a real running agent rather than reasoned about: its copy carried the older
+change's marker and did not carry the correction, so the update could never have arrived.
+
+The delivery step was proved to work by simulating exactly that agent — one that already took the
+earlier change — and then deliberately breaking the fix in the way that would reintroduce the
+problem, which made precisely that test fail and no other.
+
+Nothing was broken when this was written: all eight covered addresses currently work, and the
+accepted-exception list is empty. This closes a hole in the guard rather than repairing a
+fault.
+
+The guard was proved to actually bite by breaking one of the newly-covered documents on
+purpose — the check refused, and named which kind of document had failed — then restoring it
+byte-for-byte and confirming it passed again. The tests were proved the same way, by narrowing
+the check back and watching exactly the two new tests fail.

package/upgrades/1.3.1019.md

@@ -0,0 +1,49 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The convergence tag writer refuses to mark a design document "converged" while it
+still has an unanswered question parked on a person. That check only recognised a
+section titled exactly `Open questions`. Many documents number their sections —
+`9. Open questions` — and for those the check found nothing, concluded there was
+nothing to find, and let the document through.
+
+The two halves of the same gate also disagreed with each other on identical input:
+the sibling check covering decision points refused a numbered heading outright,
+while the open-questions check waved it past. Both now recognise the same set of
+heading shapes (plain, numbered, lettered, dotted, parenthesised, and with a
+trailing variant such as `(round 2)`), and they share one matcher so a future fix
+to one cannot silently miss the other.
+
+What deliberately did NOT change: a document with genuinely no such section is
+still treated as having nothing outstanding. Whether that should instead refuse is
+a separate decision worth arguing on its own rather than folding in here.
+
+## What to Tell Your User
+
+Nothing you need to do. A safety check that decides whether a design document is
+finished had a blind spot: if the document numbered its sections, an unanswered
+question could slip past unnoticed. It now sees those documents too.
+
+## Summary of New Capabilities
+
+No new capability. This repairs a check that already existed and was quietly not
+looking at part of what it was meant to cover.
+
+## Evidence
+
+The defect was reproduced with a control before any fix was written: a live,
+unanswered question under a numbered heading returned "nothing outstanding", while
+the identical question under a plain heading was caught.
+
+Seven tests now cover the numbered, lettered, dotted, parenthesised and
+variant-suffix headings plus the cross-check that both halves of the gate agree.
+Reverting the fix makes exactly those seven fail; restoring it returns 50 passing
+tests across all four suites that touch the changed file, with type-checking clean.
+
+## Title
+
+A section number could hide an unanswered question from the convergence gate

package/upgrades/side-effects/openq-gate-numbered-headings.md

@@ -0,0 +1,47 @@
+# Side effects — open-questions gate: numbered-heading recognition
+
+## What this change can affect
+
+`write-convergence-tag.mjs` is the structural gate for `/spec-converge`. Widening
+heading recognition changes which specs the gate can SEE, so both directions were
+checked rather than only the one being fixed.
+
+## Newly-visible sections (the intended effect)
+
+A spec whose `Open questions` section is numbered was previously invisible to the
+gate; it is now parsed. **Consequence to state plainly: a spec that would have been
+stamped before may now be REFUSED — correctly — because it carries a live
+unresolved question that the gate could not previously see.** That is the point of
+the fix, and it is a behaviour change for any such spec mid-flight.
+
+## Not changed, deliberately
+
+- A genuinely ABSENT `Open questions` section still yields "nothing parked on the
+  user". Whether an absent section should instead fail closed is a separate argued
+  decision; smuggling it in here would be a semantic change hiding inside a
+  matcher fix. Tracked, not silently taken.
+- Resolution semantics are untouched: `*(none)*`, `(none)`, `None`, `N/A`,
+  blockquote commentary and horizontal rules still count as resolved, including
+  under a numbered heading (explicitly tested, so the fix cannot become
+  "refuse every numbered spec").
+- `GRANDFATHERED_SLUGS` is untouched and remains empty.
+
+## The decision-points gate
+
+That sibling previously refused a numbered heading with `missing-section`. That is
+a FALSE refusal — the section was present, merely numbered — so it now recognises
+the same shapes. This makes the gate less likely to block a conforming spec; it
+does not weaken it, because an actually-missing section still refuses.
+
+## Blast radius and rollback
+
+Two files: one script, one test file. No route, no config key, no persisted state,
+no migration. Rollback is a revert.
+
+## Honest limit
+
+The matcher tolerates a bounded set of section-label shapes. An exotic heading
+(e.g. a roman numeral, or an emoji prefix) would still be invisible, and the
+underlying design remains "match a heading by name". A structurally stronger
+answer — a declared anchor rather than a heading regex — was NOT attempted here
+and is a larger change than this repair.

package/upgrades/side-effects/rollout-evidence-ratchet-composed.md

@@ -0,0 +1,54 @@
+# Side-effects review — rollout-evidence ratchet widened to `composed`
+
+## What this changes
+
+`scripts/lint-rollout-evidence-resolvable.js` guarded `rollout-disposition: active` only.
+It now guards `active` AND `composed`. Guarded endpoint specs go from 5 to 8.
+
+## Blast radius
+
+The lint runs in the `npm run lint` chain, so it gates every commit and every CI run.
+Widening it can, in principle, fail a build that previously passed.
+
+**Measured, not assumed: it cannot do so today.** All eight guarded refs resolve; the lint
+exits 0 with an EMPTY accepted-baseline. The three newly-covered specs are
+`self-heal-gate.md` (`/feedback-factory/drain/status`), `context-wedge-detection-completeness.md`
+(`/health`), and `slack-considered-acknowledgment-v1.md` (`/permissions/ambient-stats`).
+Two were already transitively covered — one shares its ref with an active spec, one names a
+path that trivially exists. Exactly one was genuinely unguarded.
+
+## The failure mode this could introduce, and why it does not
+
+The obvious risk of widening a guard is forcing unrelated work on whoever trips it next: a
+`composed` spec whose owner feature was abandoned may legitimately carry a stale ref, and
+such a person should not be conscripted into building a route they do not want.
+
+They are not. Assertion C's shrink-only baseline is the escape hatch, and it was designed
+before this change: an accepted entry requires a written reason and is auto-deleted the
+moment its ref starts resolving. So the widened guard forces a DECLARATION, never a fix.
+Entry needs evidence; exit happens by itself.
+
+## What is NOT weakened
+
+Assertions A (every guarded ref resolves unless accepted), B (baseline reasons must be
+substantive), and C (baseline shrinks only) are unchanged. No threshold moved. The
+refusal message now names which disposition fired, which is strictly more information.
+
+## Verification
+
+- Live run: `clean — 8 guarded endpoint spec(s) (5 active, 3 composed), 8 resolving, 0 accepted-unresolved`, exit 0.
+- Falsified against the real subject: breaking the COMPOSED spec's ref → exit 1 with a
+  refusal naming `rollout-disposition:composed`. Spec restored byte-identical; exit 0 again.
+- Falsified against the tests: narrowing the filter back to active-only → `2 failed | 7 passed`.
+  Restored → `9 passed`.
+- Two pre-existing tests asserted the OLD summary wording and correctly broke. Their
+  PROPERTY — that the guard must report its denominator, since "clean" alone cannot be told
+  from "scanned nothing" — is preserved, with the pattern updated rather than the assertion
+  dropped.
+
+## Reviewer's note
+
+This is a correction to my own work from earlier the same day. The lint's header claimed a
+sweep of "all 5 rollout-active specs" — accurate for its scope, and the scope was narrower
+than the class it names. Recorded in the source comment rather than quietly widened, because
+a guard that silently grew is indistinguishable from one that was always right.

package/upgrades/1.3.1017.md

@@ -1,37 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- assembled-by: assemble-next-md -->
-<!-- bump: patch -->
-
-## What Changed
-
-A correction made earlier today to how design reviews decide they are finished now actually reaches
-agents that are already running. It previously did not.
-
-Tools like that review process exist both in what ships and as a copy on each running agent's disk.
-The install step deliberately never overwrites an existing copy, in case an operator has customised
-it, so an update reaches running agents only through a small dedicated delivery step. One already
-existed for this file — but its "have I done this already?" check was keyed to an older change, so
-once an agent had taken that one it quietly stopped delivering anything further to the same file.
-
-## What to Tell Your User
-
-Nothing changes in how your agent behaves day to day. A fix that had been shipped but could not
-reach already-running agents now reaches them.
-
-## Summary of New Capabilities
-
-None. No endpoint, config key, or behaviour is added. This is a delivery step so an existing fix
-arrives where it was always meant to go.
-
-Agents that have customised the file keep their version untouched, agents that already have the
-correction are unaffected, and a fresh install is unchanged.
-
-## Evidence
-
-The gap was confirmed on a real running agent rather than reasoned about: its copy carried the older
-change's marker and did not carry the correction, so the update could never have arrived.
-
-The delivery step was proved to work by simulating exactly that agent — one that already took the
-earlier change — and then deliberately breaking the fix in the way that would reintroduce the
-problem, which made precisely that test fail and no other.