instar 1.3.1002 → 1.3.1004

package/upgrades/side-effects/channels-wa-imessage.md

@@ -0,0 +1,77 @@
+# Side-effects review — WhatsApp + iMessage join the channel registry
+
+**Change:** `buildUserChannelDefinitions` gains `user-whatsapp` and `user-imessage` rows, with
+exported `whatsappStateFrom` / `imessageStateFrom` mappers and route wiring from
+`ctx.whatsapp.getStatus().state` and `ctx.imessage.getConnectionInfo().state`.
+
+**Decision point touched?** No new gate. This is additive read-only observability on an existing
+`advisory: true` route. It does change what a caller CONCLUDES about reachability, which is why the
+verdict mapping is the whole of this review.
+
+---
+
+## 1. Over-block
+
+Nothing is blocked or rejected — the route is advisory and gates nothing. The over-claim risk runs the
+other way and is handled: `qr-pending` is reported as `reachable-no-credential` rather than `broken`,
+because the link is alive and needs a HUMAN to scan a code. Reporting it as broken would send an
+operator to debug a connection behaving exactly as designed.
+
+## 2. Under-block
+
+The honest limit, stated in both rows' own text rather than left to assumption: `working` means the
+link was up when probed. It does NOT prove a send to a particular chat or contact would land. Same
+caveat the Telegram and mutual-ssh rows already carry.
+
+Unrecognised states from either adapter map to `unknown`, never to `working`. That is the failure
+direction that matters — a state this module has not seen must not read as healthy — and it is
+pinned by a test.
+
+Not addressed: neither row probes a round-trip. A true reachability proof would require sending, which
+a status read must not do.
+
+## 3. Level-of-abstraction fit
+
+Correct, and it follows the pattern already established for Telegram and Slack: the STATE→VERDICT
+mapping is an exported pure function testable without constructing an adapter, and the route supplies
+live state through a narrow context. The mapping is where a wrong verdict would come from, so it is
+the part that is pinned.
+
+## 4. Signal vs authority compliance
+
+Compliant. Pure signal on an advisory route with no blocking power. Adding rows strengthens the
+registry's "absence is impossible" property — the invariant that a channel with no row cannot report
+that it is missing.
+
+## 5. Interactions
+
+`UserChannelProbeContext` gains two required fields, so any other constructor of it must supply them
+— there is exactly one (the `/channels` route), updated here. The `/channels` payload grows from 6
+rows to 8; the integration test that pins the exact set and the audience partition was updated in
+this change rather than left for CI to catch.
+
+`WhatsAppLiveState` mirrors the adapter's own union. If the adapter adds a state, the mapper reports
+`unknown` rather than mis-classifying — a deliberate fail-safe, not an oversight.
+
+## 6. External surfaces
+
+`GET /channels` returns two additional rows. Additive; existing consumers reading known ids are
+unaffected. No endpoint added, no config key, no behaviour change to messaging itself.
+
+## 7. Multi-machine posture
+
+**Machine-local by design for iMessage**, and this is a real property rather than a shortcut: the
+backend it talks to runs on this host, so the channel genuinely exists only where that backend is.
+That is recorded in the row's own `cost` text so a caller choosing it knows the work will not survive
+this machine going away.
+
+WhatsApp is pairing-bound to the operator's phone through whichever host holds the session — the same
+locality. Neither introduces replicated state; both are per-host reads of a per-host adapter, and a
+cross-machine merged view would be actively misleading since another machine's link says nothing
+about this one's.
+
+## 8. Rollback cost
+
+Trivial: remove the two rows, the two mappers, the two context fields and the route wiring, and
+restore the integration test's expected set. No persisted state, no schema, no migration. Rolling back
+re-opens the stated gap, so it should carry a reason.

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.

package/upgrades/side-effects/tier-config-hint-filename.md

@@ -0,0 +1,72 @@
+# Side-effects review — tier classifier no longer treats a .config FILENAME as a config surface
+
+**Change:** removes the `\.config\b` alternative from `CONFIG_SURFACE_HINT` in
+`scripts/lib/classify-tier.mjs`. That alternative matched a filename REFERENCE, so a diff that merely
+read `*.config.ts` satisfied the config-surface gate and, combined with any object literal, raised the
+risk floor for "new config key added".
+
+**Decision point touched?** Yes — the risk floor of the instar-dev tier gate. This LOWERS the floor in
+one specific false-positive case, so it is a loosening and reviewed as such.
+
+---
+
+## 1. Over-block
+
+This change exists to remove one. The over-block was concrete: a read-only developer script that adds
+no config key had its floor raised to 2 purely for naming `vitest.push.config.ts`.
+
+## 2. Under-block
+
+The real risk of the change, stated plainly: narrowing a heuristic can blind it. If a genuine
+config-key addition mentions ONLY a `*.config.ts` filename and none of the remaining anchors
+(`ConfigDefaults`, `config.json`, `defaultConfig`, `InstarConfig`, `configSchema`), its floor will no
+longer rise.
+
+Bounded two ways. The remaining anchors cover the actual config surfaces in this repo — a diff adding
+a real key names the module, the file, or the type. And a test now iterates EVERY remaining anchor and
+asserts the floor still rises, so a future narrowing that blinds the check fails.
+
+Residual: this is a heuristic over diff text and always was. It deters accidental omission; it is not
+a boundary against a determined author. Unchanged by this.
+
+## 3. Level-of-abstraction fit
+
+Correct — the defect is in the hint regex and the fix is in the hint regex. A broader alternative
+(requiring the anchor on the SAME line as the key) was considered and rejected as a larger behavioural
+change than the evidence supports: one bad alternative was identified precisely, so one alternative is
+removed.
+
+## 4. Signal vs authority compliance
+
+The classifier is a SIGNAL that informs a declared tier; the agent holds the authority and the
+declaration is audited. This change makes the signal more accurate without altering who decides. Per
+`docs/signal-vs-authority.md` that is the intended direction.
+
+## 5. Interactions
+
+`CONFIG_SURFACE_HINT` is used only to gate the `key: value` pattern inside the new-capability check.
+No other risk signal is affected; the `export class` and router patterns are untouched. All 47
+pre-existing classifier tests pass unchanged, plus 2 new ones.
+
+Changes to this file alter tier decisions for FUTURE commits only. Nothing recorded in past decision
+audits is rewritten.
+
+## 6. External surfaces
+
+None. Development-time classifier; no endpoint, no config key, no runtime behaviour, not user-facing.
+
+## 7. Multi-machine posture
+
+Not applicable: a pure function over diff text, identical on every checkout, with no state, no
+persistence, and nothing to replicate or reconcile.
+
+## 8. Rollback cost
+
+Trivial — restore the alternative. The regression test would then fail, which is the correct signal
+that the rollback reintroduces the false positive rather than a silent revert.
+
+## Disclosure
+
+I hit this false positive myself and declared Tier 1 under the raised floor without reading it first.
+That declaration and its deliberate re-declaration are both in the decision audit. This change fixes
+the classifier; it does not excuse the declaration.