instar 1.3.977 → 1.3.979

package/upgrades/side-effects/assessment-confidence-unverified.md

@@ -0,0 +1,125 @@
+# Side-Effects Review — assessmentConfidence: my own honesty field was overclaiming
+
+## Summary of the change
+
+`CoverageSummary.assessmentTrustworthy` (shipped hours earlier in PR #1641) reported **`true` over
+the exact defect it was added to expose.** Verified on the LIVE endpoint after v1.3.975 deployed:
+
+```
+total: 22 | enforcedRatio: 0.0455 | assessmentTrustworthy: TRUE | canaryOk: true | canaryFailures: 0
+registry.parsed: 22 | articleHeadings: 22 | bytes: 46606 | families: [5 of the 6]
+```
+
+The source registry carries **81** articles. The stale agent-home copy is not malformed — it is a
+self-consistent document that is a quarter of the real one, so it passes every INTERNAL check by
+construction (all headings parse, none dropped, anchors present, count above the floor).
+
+`assessmentTrustworthy` was computed as `total > 0 && registry.canaryOk` — i.e. "my internal checks
+passed". It READ as "this assessment is trustworthy". Conflating those is the failure the whole
+instrument was being fixed for.
+
+Replaced by a tri-state `assessmentConfidence` (`'verified' | 'unverified' | 'untrustworthy'`) plus
+an always-populated `confidenceReason`. The boolean is retained, deprecated, TRUE only on
+`'verified'`.
+
+**Root insight:** nothing INSIDE a 22-rule document says it should have 81. Trustworthiness is not
+obtainable by looking harder at the file — it needs an EXTERNAL expectation. That mechanism is the
+blocked `standards-registry-snapshot-refresh` spec, so `'verified'` is unreachable today, and the
+honest verdict for every passing read is `'unverified'`.
+
+Proven against the real live registry (all four states):
+
+| input | before | after |
+|---|---|---|
+| the live 22-of-81 copy | `trustworthy: true` | `unverified` + reason |
+| the real 81-article registry | `true` | `unverified` — still correct; nothing to check against |
+| a MATCHING expectation | unreachable | `verified` |
+| a MISMATCHED expectation | unreachable | `untrustworthy` |
+
+## Decision-point inventory
+
+- `computeCoverage` / `GET /conformance/coverage{,/health}` — OBSERVE-ONLY. Gates nothing, blocks
+  nothing, no code path branches on the verdict. This changes what is REPORTED, never what anything
+  DOES.
+- `deriveAssessmentConfidence` — new, exported, pure. Extracted deliberately: inline, TypeScript's
+  flow analysis proved `'verified'` unreachable and REJECTED the comparison deriving the deprecated
+  boolean. That rejection is TRUE and is the point; a function keeps the union open for when an
+  expectation ships without pretending it is reachable now. (TS caught this, which is worth noting —
+  the compiler objected to a claim I could not yet honour.)
+- No gate, hook, sentinel, reaper, scheduler, migration or config surface touched.
+
+## 1. Over-block
+
+Nothing blocks. The adjacent risk is over-alarming: `assessmentTrustworthy` is now `false`
+EVERYWHERE, including for a complete and correct registry. That is intentional and argued in the
+ELI16: the instrument genuinely cannot verify completeness today, so anything stronger is the same
+overclaim in nicer clothes.
+
+The tri-state exists precisely so this is not alarming: `'unverified'` says *I do not know*, which is
+neither reassuring nor a red flag. A consumer reading only the deprecated boolean sees `false` and
+may over-read it — which is why the boolean is deprecated in its doc comment and the reason string is
+always populated.
+
+## 2. Under-block
+
+No detection is weakened: `'untrustworthy'` still fires on every case the boolean fired on (nothing
+parsed, canary objected), asserted in the updated tests. The change only ADDS a state between "fine"
+and "broken" where none existed.
+
+The residual gap, stated plainly: **a coherent stale registry is still reported with real-looking
+figures** (`total: 22, enforcedRatio: 0.0455`). It is now labelled `unverified` with a reason naming
+the possibility of "a coherent older copy", but the instrument cannot say *which* is the case. Only
+the blocked spec closes that. This change makes the uncertainty visible; it does not resolve it, and
+it must not be described as resolving it.
+
+## 3. Blast radius
+
+One field's semantics in `src/core/StandardsEnforcementAuditor.ts`; the route spreads the summary so
+the new fields flow automatically. Consumers checked with a full-text scan (`grep` silently returned
+nothing for a pattern present twice in this very file — python was used instead, and that tooling
+anomaly is recorded):
+
+- `assessmentTrustworthy` appears in exactly three test files (all updated) and nowhere in `src/`
+  outside its declaration and derivation. No runtime branch reads it.
+- The response is additive apart from the boolean's meaning narrowing; no field renamed or removed.
+
+## 4. Rollback plan
+
+Single-commit revert; no state, config, migration or persisted artifact. The audit recomputes per
+request.
+
+## 5. Test coverage (all three tiers)
+
+- **Unit** (`standards-enforcement-auditor.test.ts`, 16 pass): a coherent-but-stale registry (a real
+  whole-family subset of the live constitution) has zero dropped headings and `parsed ===
+  articleHeadings` — i.e. passes every internal check — and STILL must not read `verified`; plus
+  `deriveAssessmentConfidence`'s four verdicts in both directions, including that a mismatched
+  expectation is `untrustworthy` rather than merely `unverified`.
+- **Integration** (`conformance-dev-gate-route.test.ts`): the HTTP body carries
+  `assessmentConfidence: 'untrustworthy'` for an empty registry.
+- **E2E** (`standards-coverage-lifecycle.test.ts`): the verdict and its reason survive the production
+  initialization path.
+
+## 6. A fourth test found encoding the defect
+
+`standards-enforcement-auditor.test.ts` asserted `assessmentTrustworthy === true` for the full
+registry — pinning the overclaim as a specification. That is the FOURTH test found this evening
+asserting the behaviour it should have been challenging (the others: the standards parser's
+five-family allowlist, a fixture whose meaning changed with the wall clock, and the
+learning-velocity route's filed-items-count-as-learning fixtures).
+
+Four in one day is not a coincidence about those four tests. It is a property of how tests get
+written here: they pin what the code currently does. A green suite therefore attests to
+self-consistency, not correctness — which is the same shape as everything else this project has
+found, applied to our own verification. Recorded as a class; not fixed here, because the fix is a
+standard about how assertions are chosen, not a code change.
+
+## 7. How this was found, which is the transferable part
+
+Not by a test. By deploying and reading the live surface. The suite was fully green — it tested the
+cases I had thought of, which were exactly the cases my fix handled. The stale-but-coherent case was
+outside my imagination, and no amount of internal testing would have surfaced it.
+
+Two hours from shipping to discovery. The generalisable rule: **after shipping an honesty fix, read
+the live surface for the case you were fixing.** If the number you set out to correct still looks
+fine, you have not corrected it.

package/upgrades/side-effects/ci-green-latest-run.md

@@ -0,0 +1,119 @@
+# Side-Effects Review — CI greenness must use the LATEST run per check
+
+## Summary of the change
+
+`StageTransitionValidator.ciIsGreen` iterated EVERY entry in GitHub's `statusCheckRollup` and refused
+on any non-success conclusion. GitHub returns every run of every check, **including superseded ones**,
+so a check that failed and was then re-run to green appears twice and the failed entry never
+disappears.
+
+Verified on the live PR #1641 (merged legitimately at 02:07:44Z):
+
+```
+rollup entries: 31 | names appearing more than once: eli16 (2), UX impact declaration (2),
+                                                     UX assertions (messaging E2E) (2), UX merge safety (2)
+eli16  COMPLETED  FAILURE  completedAt 2026-07-26T01:44:01Z
+eli16  COMPLETED  SUCCESS  completedAt 2026-07-26T01:45:32Z
+```
+
+Branch protection merged the PR because it evaluates each check's CURRENT state. The tracker refused
+it with `CI_NOT_GREEN` because it evaluated the stale run too — so **no correct merge whose CI had
+ever been red could ever be recorded.**
+
+Fix: `latestRunPerCheck` collapses the rollup to the newest run per check name (by `completedAt`,
+falling back to `startedAt`) before `ciIsGreen` evaluates it. `GhPrView.statusCheckRollup`'s type
+gains the `name`/`context`/`startedAt`/`completedAt` fields the dedupe needs; the route's existing
+`gh pr view --json …statusCheckRollup` already returns them, so no query change.
+
+## Decision-point inventory
+
+- `ciIsGreen` feeds the `building → merged` GATE. This change makes the gate ACCEPT a case it
+  previously refused, so it is the direction that needs the most scrutiny — see §1/§2.
+- No other decision point, hook, sentinel, reaper, scheduler, migration or config surface is touched.
+- `latestRunPerCheck` is a pure function over the rollup array.
+
+## 1. Over-block
+
+Strictly reduced, and that is the intent: a merged PR with a superseded failure is now recordable.
+Nothing that used to pass now fails.
+
+The one preserved refusal worth naming: a **latest** run that is still in flight (`status` not
+`COMPLETED`) is still not green, asserted in its own test, so the dedupe cannot be used to skip a
+pending check by pairing it with an older success.
+
+## 2. Under-block — the part that matters
+
+A dedupe is a potential laundering mechanism, so three properties are enforced and each is tested:
+
+1. **Latest is authoritative in BOTH directions.** SUCCESS followed by a later FAILURE is NOT green.
+   Without this, "keep the latest" would let anyone bury a red by arranging run order.
+2. **Unorderable runs FAIL CLOSED.** Equal or missing timestamps ⇒ the FAILING run wins. An undatable
+   success must never mask a red. (Three variants tested: no timestamps either way round, and equal
+   timestamps.)
+3. **Unnamed entries are keyed individually.** Bare status contexts with neither `name` nor `context`
+   are never collapsed into each other, so a failing one cannot be replaced by a passing one.
+
+Residual, stated: the dedupe trusts GitHub's timestamps. A platform that reported them wrongly could
+mis-order runs — but the fail-closed rule bounds the damage to the unorderable case, and the
+alternative (ignoring the rollup entirely, or trusting merge status alone) is strictly weaker.
+
+## 3. Blast radius
+
+One function plus one type widening in `src/core/StageTransitionValidator.ts`. `ciIsGreen` is private
+to that module (`grep` for callers: only the `to === 'merged'` branch). The route passes the rollup
+through unchanged. No response shape changes; no new code.
+
+## 4. Rollback plan
+
+Single-commit revert; no state, config, migration or artifact. Reverting restores the previous
+(over-refusing) behaviour immediately.
+
+## 5. Test coverage
+
+`tests/unit/StageTransitionValidator.test.ts` (46 pass), five new cases: the live #1641 shape
+(superseded FAILURE + later SUCCESS ⇒ green); the reverse (SUCCESS + later FAILURE ⇒ not green);
+unorderable-runs-fail-closed across three variants; unnamed entries not collapsed; and an in-flight
+latest run still not green.
+
+No integration/e2e tier added: this is a pure predicate inside an existing gate whose route path is
+already covered, and the decisive evidence is the end-to-end check below.
+
+## 6. End-to-end evidence, gathered BEFORE the fix and after
+
+The validator's real logic was run against the two real merged PRs with the route's exact helper
+wiring:
+
+```
+before:  item 1 (PR 1641) -> CI_NOT_GREEN
+         item 2 (PR 1644) -> MERGE_BASE_UNVERIFIABLE   (stale local ref; resolved by git fetch)
+after:   item 1 (PR 1641) -> WOULD SUCCEED
+         item 2 (PR 1644) -> WOULD SUCCEED
+```
+
+Note the second line: the `MERGE_BASE_UNVERIFIABLE` code shipped hours earlier in #1643 did its job
+here on a real case — an unknown local SHA reported as *unverifiable* rather than as a false "not an
+ancestor".
+
+## 7. Third instance in one code path, in one evening
+
+The completion-recording path has now yielded three independent defects tonight, each the same
+underlying error:
+
+| | defect | what it reported |
+|---|---|---|
+| #1640 | the `gh` binary was unreachable | a flat refusal |
+| #1643 | a SourceTreeGuard refusal was caught and returned as `false` | "the merge is not on main" |
+| this | a superseded check run read as the check's current state | "CI is not green" |
+
+All three presented identically from outside — an opaque refusal — and each masked the next. That is
+worth recording as a property of the path rather than three coincidences: **a code path whose failures
+all render as one indistinguishable refusal will hide its own defects in series.** The general fix is
+the one #1643 started: distinguish "could not determine" from "determined, and the answer is no".
+
+## 8. How it was found
+
+By refusing to assert. I was about to report that recording would work once the server updated, and
+instead ran the validator's own logic against the real PRs. It returned two different refusals. That
+cost two minutes and avoided discovering both blockers serially, each appearing to be a fresh
+mystery. Habit worth keeping: **before claiming something will work once a dependency lands, execute
+its logic now and read what it returns.**

package/upgrades/side-effects/guard-heartbeat-unproven-summary.md

@@ -0,0 +1,137 @@
+# Side-Effects Review — Fleet guard-posture completeness
+
+**Version / slug:** `guard-heartbeat-unproven-summary`
+**Date:** `2026-07-25`
+**Author:** `Instar Agent (instar-codey)`
+**Second-pass reviewer:** `heartbeat_guard_review`
+
+## Summary of the change
+
+`src/monitoring/guardPostureView.ts` projects the existing `loadBearingUninspectableKeys` summary into the capacity heartbeat as a full `loadBearingUninspectable` count plus at most 16 sorted keys. `src/core/types.ts` adds the optional wire members, and `src/core/GuardPostureStore.ts` includes them in write-on-change semantic equality. `dashboard/glance.js` displays the received count and keys in the existing per-machine Layer-3 record. No guard row, gap membership, anomaly, attention item, notification, machine-health calculation, or placement decision changes.
+
+## Decision-point inventory
+
+No block/allow or actuation decision point is added or modified.
+
+- `buildHeartbeatPostureBlock` — **modify** — adds a bounded read-only projection of an existing summary list.
+- `GuardPostureStore.postureSemanticsEqual` — **modify** — recognizes changes to the new wire fields for persistence; it does not decide posture or liveness.
+- `machineRecordNode` — **modify** — displays received data at Layer 3 only.
+- `GuardPostureProbe` — **pass-through** — deliberately unchanged; it continues to alarm only the pre-existing posture and gap classes.
+- `guardPostureProblems` / `machineNeedsAttention` — **pass-through** — deliberately unchanged; the new field cannot alter fleet health or attention classification.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. The producer accepts every existing inventory, and older heartbeat payloads without the optional fields remain valid.
+
+---
+
+## 2. Under-block
+
+The 16-key sample can omit individual keys if the load-bearing manifest grows beyond 16, but the full count makes that truncation explicit and the dashboard says how many keys are shown. Today’s manifest contains 13 load-bearing guards, so every current key fits.
+
+One adjacent persistence limitation was observed and left unchanged: `GuardPostureStore.postureSemanticsEqual` does not compare the three older `loadBearingGapKeys`, `loadBearingSoakingKeys`, or `loadBearingAcceptedKeys` lists. Live in-memory posture still updates before the equality check, but a keys-only change to one of those older lists may not be written for restart recovery when every compared count stays equal. This PR compares only the two new fields required for its own durable wiring. The adjacent finding is reported to Echo and is neither fixed nor filed here.
+
+By instruction, the field name retains the earlier `Uninspectable` wording even though `off-runtime-divergent` is more precisely “inspected but unproven.” The code comment and operator label use “cannot prove protection” / “unproven,” preserving wire compatibility without a behavior-free rename.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The projection belongs in `buildHeartbeatPostureBlock`, which already translates the complete local inventory into the compact wire shape. It reuses the canonical list instead of re-deriving posture in the heartbeat or dashboard. The 16-key clamp is a transport bound, not a posture heuristic. Display belongs in the existing machine record because `/pool` is the fleet heartbeat consumer and that record already renders the machine’s guard counts.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [x] No — this change has no block/allow surface.
+- [ ] Yes — but the logic is a smart gate with full conversational context (LLM-backed with recent history or equivalent).
+- [ ] ⚠️ Yes, with brittle logic — STOP. Reshape the design.
+
+The new heartbeat members can only describe already-derived state. Neither the store nor the dashboard can enable, disable, suppress, alarm, notify, place, or authorize anything from them. Existing authorities receive byte-for-byte equivalent inputs because the probe does not read the new members.
+
+---
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+No new static heuristic is added at a competing-signals decision point. Membership comes from the existing closed list. The number 16 is an explicit transport ceiling over a deterministic sample, paired with an uncapped count; it does not decide whether protection is healthy.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** none. Posture classification and summary assembly complete before heartbeat projection. The dashboard reads the result after pool ingestion.
+- **Double-fire:** structurally prevented. No new call to `emitAttention`, `createAttentionItem`, notification code, or probe evaluator exists. The peer refusal test presents `errored: 1` together with the new key and obtains exactly one existing acute episode and no load-bearing episode.
+- **Races:** no new concurrent state is introduced. `MachinePoolRegistry` already replaces its in-memory posture on each beat; the store’s existing synchronous write-on-change path receives two more compared fields.
+- **Feedback loops:** none. `/pool` and the Machines glance are read surfaces. The displayed value is never fed into guard evaluation, machine health, routing, placement, or messaging.
+- **Compatibility:** the wire fields are optional for old persisted records and old peers. The renderer falls back to the key-array length when a transitional payload has keys but no count and refuses to display a count smaller than the keys actually present.
+- **Payload:** the new list is sorted and sliced to 16. The full count is one number; there is no unbounded free text.
+
+---
+
+## 6. External surfaces
+
+Authenticated `/pool` callers receive two additive optional members inside each machine’s existing `guardPosture` block. The Machines dashboard displays them in the existing machine detail record. No response status, authentication rule, peer URL, external-service call, Telegram/Slack message, attention item, or notification changes.
+
+The persisted `guard-posture-peers.json` may contain the two additive fields after an upgraded heartbeat. Old records deserialize because the fields are optional; rollback ignores the extra JSON members.
+
+No operator-facing action is added. The surface is diagnostic only: there is no grant, approval, destructive operation, or laptop-only workflow.
+
+---
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+1. **Leads with the primary action?** There is no action. The new answer appears directly in the already-open machine record beside its other safety-check facts; it is not hidden behind another toggle.
+2. **Zero raw internals as primary content?** The plain label is “Load-bearing protection unproven.” Guard keys are supporting identifiers after the human-readable count, not headline or tile content.
+3. **Destructive actions de-emphasized?** No destructive or constructive control is added.
+4. **Plain language + phone width?** The label is plain language and the existing record value style uses `overflow-wrap: anywhere`, so long guard keys wrap instead of forcing horizontal scroll. The change adds no table or fixed-width element. Unit, integration, and end-to-end DOM tests open the real Layer-3 record and require the count/key text; the existing phone-width record layout and tap targets are unchanged.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Posture: replicated via heartbeat.** Each machine derives its own machine-local guard truth and includes the bounded projection in its normal capacity heartbeat. `MachinePoolRegistry` receives it, `GuardPostureStore` retains the last known value for a dark peer, `GET /pool` returns it, and the Machines glance displays it with that machine’s identity.
+
+It emits no user-facing notice, so one-voice gating is not needed. It adds no new store or topic-bound state; it extends the existing per-machine posture record. It generates no URLs. The peer probe deliberately ignores the field, preventing a per-machine multiplication of notices.
+
+---
+
+## 8. Rollback cost
+
+Revert the two wire members, producer projection, semantic comparison, dashboard row, and tests, then ship a patch. Existing persisted JSON may retain unknown additive members, which older code ignores. There is no schema migration, database cleanup, agent reset, user notification, or classification repair.
+
+---
+
+## Conclusion
+
+The change completes the second read surface without creating a second behavioral system. The heartbeat is explicitly bounded, the count preserves truth under truncation, the fleet reader displays the field, and all existing authority paths remain unchanged. Refusal-first tests pin the errored guard’s exclusion from `loadBearingGapKeys`, inclusion in the new list, exactly one existing anomaly with no notification track, the 16-key ceiling, persistence, real `/pool` exposure, and end-to-end display.
+
+---
+
+## Second-pass review (required: guard-related change)
+
+**Reviewer:** `heartbeat_guard_review`
+
+**Independent read of the artifact:** Concur with the review: the errored load-bearing guard remains outside `loadBearingGapKeys`; the heartbeat adds only an honest full count plus a deterministic 16-key sorted sample; probe, notification, and machine-health decision paths do not consume the new fields; persistence and the real `/pool` → Machines record path are wired; and the focused unit/integration/e2e suite passes 98/98 with direct refusal assertions for field omission, count dishonesty, cap removal, persistence loss, and display loss. I found no inaccurate artifact claim or adjacent scope drift requiring rework.
+
+---
+
+## Evidence pointers
+
+- Before implementation, the focused unit suite failed three assertions: the heartbeat count/list were absent and the machine record omitted the load-bearing-unproven row.
+- Unit: 67/67 across producer, probe refusal, and dashboard drill-down suites.
+- Integration: 26/26 across heartbeat persistence, real `/pool`, and Machines glance wiring.
+- E2E: 5/5 in the shipped jargon-belt Machines lifecycle.
+- Static/build: `npm run lint` and `npm run build` pass without threshold changes.
+
+---
+
+## Class-Closure Declaration (display-only mirror)
+
+No agent-authored-artifact defect and no self-triggered controller change — not applicable.