instar 1.3.1018 → 1.3.1019

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1018",
+  "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/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:55:15.925Z",
-  "instarVersion": "1.3.1018",
+  "generatedAt": "2026-07-27T22:23:55.031Z",
+  "instarVersion": "1.3.1019",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

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.