instar 1.3.1002 → 1.3.1003

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1002",
+  "version": "1.3.1003",
   "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/SKILL.md

@@ -168,10 +168,54 @@ The external passes are **NON-SKIPPABLE** whenever a non-Claude framework was **
 
 Convergence criteria (BOTH must hold — additive, per Autonomy Principle 2):
 
-1. **The new round produces no material new issues.** "Material" means any finding that would require a spec change if unaddressed. Cosmetic findings, repeats of already-addressed concerns, and minor phrasing quibbles are non-material. (A cheap-to-change-after tag the Decision-Completeness reviewer contested and rejected IS a material finding.)
+1. **No DESIGN-class findings for TWO consecutive rounds.**
+
+   **Why this replaced "no material new issues" (2026-07-27).** "Material" was defined as *any finding
+   that would require a spec change if unaddressed* — and a contract-precision or naming finding DOES
+   require a spec edit, so it counted. **On a spec that appends its own review history, the reviewable
+   surface grows every round, and a diligent reviewer will always find precision to add on a larger
+   surface. So the loop could not terminate BY CONSTRUCTION for that document shape**, and the 10-round
+   cap fired for a reason unrelated to whether the design was sound.
+   That is not a hypothesis. `standards-registry-ships-with-code` recorded 4–5 findings under a column
+   headed "Material findings" in *every one* of its ten rounds, while its own report observed that
+   rounds 5–10 *"produced no design defects at all — they produced contract precision, naming, and
+   scope-bound findings."* A second spec on the same problem hit the cap identically. A verdict that
+   does not measure its subject is this project's signature failure; here it lived in the stop
+   criterion itself.
+
+   **Each reviewer CLASSIFIES every finding it raises — the class is declared, never inferred by the
+   comparator from wording:**
+
+   - **DESIGN-class** — changes what would be BUILT or how it would BEHAVE. Architecture; a safety,
+     security, scalability, or integration property; a decision point's classification or floor; a
+     multi-machine posture; a missing failure mode; **or a statement in the spec that is factually
+     WRONG about the system** (round 10 of that spec caught a false rollback claim — that is
+     design-class, not precision, and must keep resetting the counter).
+   - **PRECISION-class** — improves the DOCUMENT without changing what would be built: contract
+     wording, naming, scope-bound phrasing, an added caveat, a clarified example.
+
+   **Precision findings are still addressed** — they are genuinely valuable and several changed
+   production code — but they do not reset the counter. Only a DESIGN-class finding does.
+
+   **Two consecutive rounds, not one**, because a single quiet round is weak evidence on a spec whose
+   surface keeps growing; requiring two makes the terminating condition harder to reach by luck while
+   still reachable at all. Under this rule the spec above converges at round 7 on its merits.
+
+   (A cheap-to-change-after tag the Decision-Completeness reviewer contested and rejected is
+   DESIGN-class — it asserts reversibility the reviewer denies, which is a claim about behaviour.)
+
+   **Honest limit:** the classification is made by a reviewer, so this trades one judgment for a
+   better-specified one rather than removing judgment. A reviewer that mislabels a design defect as
+   precision can end the loop early — which is why the taxonomy names the wrong-about-the-system case
+   explicitly, and why the report must record each round's class counts so a suspiciously quiet
+   round is visible rather than merely accepted.
 2. **Zero unresolved user-decisions remain in `## Open questions`.** A spec cannot converge while a live decision is still parked on the user — every open question must be resolved into a `## Frontloaded Decisions` entry (or a contested-and-surviving cheap-to-change-after tag) before convergence. This is enforced STRUCTURALLY: `write-convergence-tag.mjs` refuses to stamp the tag while `## Open questions` contains unresolved entries, so the criterion cannot be skipped by prose (Structure > Willpower).
 
-A lightweight LLM (Haiku-class) compares the new round's findings to the prior round's findings and emits a boolean `converged: true|false` with reasoning. Human-readable comparison log is retained.
+A lightweight LLM (Haiku-class) compares the new round's findings to the prior round's findings and emits a
+boolean `converged: true|false` with reasoning. It consumes each finding's DECLARED class — it must not
+re-classify from wording, because the reviewer that raised a finding is the one that knows whether it changes
+what would be built. It also emits `designFindings` and `precisionFindings` counts per round so the
+consecutive-quiet-round count is auditable rather than asserted. Human-readable comparison log is retained.
 
 **Not converged** → back to Phase 2.
 **Converged** → Phase 4.

package/skills/spec-converge/templates/report.md

@@ -49,8 +49,8 @@ The user reads this section to understand what convergence changed.
 
 ## Iteration Summary
 
-| Iteration | Reviewers who flagged material issues | Material findings | Spec sections changed |
-|-----------|---------------------------------------|-------------------|-----------------------|
+| Iteration | Reviewers who flagged design issues | Design findings | Precision findings | Spec sections changed |
+|-----------|-------------------------------------|-----------------|---------------------|-----------------------|
 {{ITERATION_TABLE}}
 
 ## Full Findings Catalog

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-27T11:55:16.447Z",
-  "instarVersion": "1.3.1002",
+  "generatedAt": "2026-07-27T12:32:20.149Z",
+  "instarVersion": "1.3.1003",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.1003.md

@@ -0,0 +1,50 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`/spec-converge`'s first convergence criterion terminated on "no MATERIAL new issues", where material
+was defined as *any finding that would require a spec change if unaddressed*. A contract-precision or
+naming finding DOES require a spec edit, so it counted — and because a spec appends its own review
+history each round, its reviewable surface grows every round and a diligent reviewer always finds
+precision to add on a larger surface.
+
+The loop was therefore unterminating BY CONSTRUCTION for that document shape, and the 10-round cap
+fired for reasons unrelated to design soundness.
+
+The criterion is now "no DESIGN-class findings for TWO consecutive rounds", with an explicit
+taxonomy each reviewer DECLARES per finding: design-class changes what would be built or how it
+behaves (including a statement that is factually wrong about the system); precision-class improves the
+document without changing what would be built. Precision findings are still raised and still
+addressed — they do not reset the counter. The comparator consumes the declared class rather than
+re-deriving it, and emits per-round design/precision counts; the report template records both.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+`standards-registry-ships-with-code` recorded 4–5 findings under a column headed "Material findings"
+in every one of its ten rounds, while its own report observed that rounds 5–10 "produced no design
+defects at all — they produced contract precision, naming, and scope-bound findings". A second spec on
+the same problem hit the cap identically. Under the new rule that spec converges at round 7 on its
+merits.
+
+Criterion 2 (zero unresolved `## Open questions`) is untouched and still enforced structurally in
+`write-convergence-tag.mjs`, so the structural half of convergence cannot be weakened by this change.
+
+## Known limits
+
+This relocates judgment rather than removing it: a reviewer that misfiles a design defect as precision
+can end the loop early. Three bounds — the taxonomy names the factually-wrong case explicitly as
+design-class, two consecutive quiet rounds are required rather than one, and the class is declared by
+the raising reviewer and recorded per round so a suspiciously quiet round is visible. None of these is
+a guarantee, and no code enforces the classification; this is an instruction change and binds only as
+well as the reviewers follow it.

package/upgrades/side-effects/converge-design-class-criterion.md

@@ -0,0 +1,74 @@
+# Side-effects review — spec-converge terminates on design-class findings
+
+**Change:** `/spec-converge`'s first convergence criterion changes from "no MATERIAL new issues"
+(material = anything requiring a spec change) to "no DESIGN-class findings for TWO consecutive
+rounds", with an explicit design/precision taxonomy that reviewers DECLARE per finding. The report
+template records both counts per round.
+
+**Decision point touched?** Yes, and it is the whole review: this is the stop criterion of the gate
+that decides whether a spec may claim convergence — the tag `/instar-dev` requires before touching
+instar source.
+
+---
+
+## 1. Over-block
+
+Reduced, deliberately, and that is the point. The prior criterion over-blocked absolutely: on a spec
+that appends its own review history the surface grows each round, a reviewer always finds precision
+to add, and every such finding counted as material — so the loop could not terminate BY CONSTRUCTION.
+Two specs hit the 10-round cap for reasons unrelated to design soundness.
+
+## 2. Under-block
+
+The real risk, stated plainly: **loosening what counts as terminating could let a spec converge with
+an unaddressed design defect misfiled as precision.**
+
+Three things bound it, none of which is "the reviewer will be careful":
+- The taxonomy names the dangerous case EXPLICITLY — a statement that is factually WRONG about the
+  system is design-class, never precision. That case is not hypothetical: round 10 of
+  `standards-registry-ships-with-code` caught a false rollback claim, and under a careless taxonomy
+  that would have been filed as wording.
+- TWO consecutive quiet rounds, not one. A single quiet round is weak evidence on a growing surface.
+- The class is DECLARED by the reviewer that raised the finding and the comparator consumes the
+  declaration rather than re-deriving it from wording — so a misclassification is an explicit act
+  recorded in the report, not an inference nobody can see.
+
+Residual and unfixed: a reviewer that systematically under-classifies still ends the loop early. This
+trades one judgment for a better-specified one; it does not eliminate judgment. Per-round counts in
+the report are the detection surface, not a guarantee.
+
+## 3. Level-of-abstraction fit
+
+Correct. The defect is in the stop criterion's DEFINITION, which lives in the skill's prose and is
+applied by the comparator, so the fix belongs in the prose plus the report template that makes it
+auditable. No code enforces the classification today and none is added — an important honesty: this
+is an instruction change, so it binds only as well as the reviewers follow it.
+
+## 4. Signal vs authority compliance
+
+The comparator retains exactly the authority it had (emit `converged: true|false`). What changes is
+the definition it applies and the requirement that it consume a DECLARED class rather than infer one
+— moving a judgment from implicit to explicit. No new blocking power anywhere.
+
+## 5. Interactions
+
+`write-convergence-tag.mjs` is untouched: criterion 2 (zero unresolved `## Open questions`) is still
+enforced structurally there, so the STRUCTURAL half of convergence is unchanged and this change
+cannot weaken it. The report template's Iteration Summary gains a column (design/precision split);
+existing reports remain readable, and future ones carry the counts the new criterion depends on.
+
+## 6. External surfaces
+
+None. `/spec-converge` is an instar-development skill, not user-facing, not an endpoint, no config
+key. The observable effect is that specs which would previously have hit the cap can now converge on
+their merits — and that convergence reports show two counts where they showed one.
+
+## 7. Multi-machine posture
+
+Not applicable. This is repo-level skill prose plus a report template, identical on every checkout,
+with no runtime state, no persistence, and nothing to replicate, proxy, or reconcile.
+
+## 8. Rollback cost
+
+Trivial: restore the previous criterion paragraph and the template's original column. No state, no
+migration, no code. A rollback re-creates the unterminating loop, so it should carry a reason.