instar 1.3.734 → 1.3.736

package/upgrades/side-effects/class-closure-gate.md

@@ -0,0 +1,111 @@
+# Side-Effects Review — Class-Closure Gate (increment 1: registry + report-only lint)
+
+**Version / slug:** `class-closure-gate`
+**Date:** `2026-07-03`
+**Author:** `echo`
+**Second-pass reviewer:** `CONCUR — no material concern (independent reviewer subagent, 2026-07-03)`
+
+> **Second-pass verdict (independent reviewer):** CONCUR — no material concern. Report-only
+> guarantee holds on every policy path (`class-closure-lint.mjs:271-272`: exit is nonzero only
+> when `enabled && !dryRun && hardViolations>0`; shipped defaults → exit 0 unconditionally,
+> confirmed on all four paths + a malformed-registry probe). Signal-only: no `docs/proposals`
+> writer, no attention-item producer, no `STANDARDS-REGISTRY.md` write in increment 1 (the sole
+> registry reference is a read-scope predicate). Scope honest: `escalatorDrafting` is plumbed
+> but never read (inert reserved key, not a half-built feature); the new TS has zero runtime
+> callers; the declare mutator is in no CI workflow. Drift guarded: both grader/registry parity
+> suites exist and pass. Interactions clean (complementary to `decision-audit-gate`, not
+> shadowing). Two minor non-blocking notes: (1) the CLI entrypoint lacks a top-level try/catch,
+> but all fs reads are individually try/caught so no throw on the real paths — inherent CI-script
+> fragility, not a policy path; (2) the config-default backfill claim is moot because an absent
+> key resolves to the report-only default. Neither requires a change before commit.
+
+## Summary of the change
+
+Increment 1 of the Class-Closure Gate (`docs/specs/class-closure-gate.md`, converged + approved). Ships **CI tooling only — no runtime gates**: a class registry (`docs/defect-classes.json`), a pure count/threshold library (`src/core/DefectClassRegistry.ts`), a self-contained guard grader (`scripts/lib/class-closure-grader.mjs`, mirroring `StandardsEnforcementAuditor`'s classification with a pinned parity test), a **report-only** PR-gate lint (`scripts/class-closure-lint.mjs`) that validates the class-declaration field-set on instar-dev decision-audit entries for fixes touching agent-authored artifacts, derives per-class recurrence counts (deduped by PR#), and LOGS any deterministic escalation-threshold crossing. A CI workflow (`.github/workflows/class-closure-gate.yml`) runs the lint report-only. Config-gated (`prGate.classClosure = {enabled, dryRun, escalatorDrafting}`, defaulting off/dry-run) and repo-gated (no-op on installs without `docs/defect-classes.json`). The escalator's LLM drafting arm, the `docs/proposals/*` writer, the attention-item producer, the runtime read route, and the consolidated axis-requirements ratchet are the spec's OWN dark **increment 3** — explicitly out of scope here, not orphan deferrals.
+
+## Decision-point inventory
+
+- `scripts/class-closure-lint.mjs` (CI PR-gate lint) — **add** — a build-time SIGNAL (report-only → later enforcing) that a fix to an agent-authored artifact carries a valid class declaration; feeds the operator, never a runtime allow/deny.
+- Deterministic recurrence trigger (inside the lint, via `computeEscalation`) — **add** — LOGS a threshold crossing; the acting-on-it (draft proposal + attention item) is increment 3.
+- `guardEvidence` grading (`evaluateGuardClosure`) — **add** — downgrades a `closure:guard` declaration to `gap` when the cited guard does not resolve to a live enforcing guard (ratchet/gate/lint). Report-only in increment 1.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+Increment 1 is **report-only** (`dryRun:true` default) — the lint ALWAYS exits 0 for declaration-content findings; it cannot reject any PR. The only nonzero exit is reserved for a hard structural violation (malformed registry JSON, a `novel` class with no semantics) AND only when `enabled && !dryRun` — which is a later increment's flip. So: **no over-block surface in increment 1.** (When the enforcing flip lands later, a legitimate fix whose guard citation doesn't resolve is not "blocked" — it downgrades to `closure:gap`, a valid tracked terminal state, per spec.)
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- A fix that bypasses the instar-dev gate entirely (no decision-audit entry) carries no `classClosure` block to validate. That bypass is caught separately by the existing `decision-audit-presence-check` at the PR boundary; this lint does not duplicate that.
+- **Classification accuracy** — an author who mislabels a defect's class (or picks a self-serving hyper-narrow class) is not caught here; the spec routes that to the escalator's periodic spot-check audit (increment 3) and to operator confirmation of `novel` classes. Increment 1 measures population/accuracy honestly during dryRun rather than enforcing.
+- Recurrence inside a single component below K=5 at normal severity does not escalate (by design — distinguishes a systemic pattern from one noisy component).
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes — a **CI PR-gate lint** in the same family as `decision-audit-gate`, `eli16-pr-gate`, `release-fragment-gate`. It is a SIGNAL producer at the build boundary, not a runtime authority, and it **reuses** the existing `StandardsEnforcementAuditor` grading logic (via a self-contained `.mjs` mirror pinned equivalent by a parity test, because PR-gate lints run on a fresh checkout with no build step) rather than re-implementing guard classification. The count/threshold math lives in a pure, unit-tested library (`DefectClassRegistry.ts`). No higher gate already does class-level closure; no lower primitive is being duplicated.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Does this hold blocking authority with brittle logic, or produce a signal that feeds a smart gate?** (`docs/signal-vs-authority.md`)
+
+**COMPLIANT — signal only.** The report-only lint emits a green/annotation signal; it holds no blocking authority in increment 1. The deterministic trigger only LOGS crossings. The downstream escalator (increment 3) drafts a *proposal* and raises an *attention item* — it has **no write path to `STANDARDS-REGISTRY.md`**; adoption is the operator's (Agent Proposes, Operator Approves). No brittle check is given blocking authority; the one place enforcement is later added (the flip) is a deterministic structural validation (registry well-formedness, declaration presence/shape), not a semantic judgment.
+
+---
+
+## 5. Interactions
+
+**Does it shadow another check, get shadowed, double-fire, race with adjacent cleanup?**
+
+- Rides the PR-gate workflow family alongside `decision-audit-gate.yml`/`eli16-pr-gate.yml`/`release-fragment-gate.yml`. It reads the SAME decision-audit entries as `decision-audit-presence-check` but a DIFFERENT field (`classClosure`) — no shadowing, no double-fire (presence-check asserts an entry EXISTS; class-closure validates the entry's declaration content).
+- The self-contained grader mirror could DRIFT from `StandardsEnforcementAuditor.gradeGuardCitation`/`classifyFileGuard` — mitigated by a pinned parity test that fails if they diverge (Structure > Willpower).
+- Counts derive from decision-audit entries **only** (deduped by PR#); the side-effects mirror is display-only and never summed — prevents the round-3 double-counting finding.
+
+---
+
+## 6. External surfaces
+
+**Does it change anything visible to other agents, other users, other systems?**
+
+- Adds one new CI check named `class-closure` to PRs against `main` (green + optional annotations). Report-only, so it can never block a merge in increment 1.
+- Adds a config key `prGate.classClosure` (off/dry-run default).
+- Adds an author helper `scripts/class-closure-declare.mjs` (stamps a `classClosure` block onto a decision entry).
+- No agent-to-agent, Telegram, or dashboard surface in increment 1 (the attention-item producer is increment 3). No dependence on runtime/conversation state — the lint is a pure function of the repo checkout + the PR diff.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Replicated / proxied-on-read / machine-local-by-design?**
+
+**Replicated — via git (the repo IS the replication medium).** The class registry, the `classClosure` declarations (in committed decision-audit entries), and (later) proposal files are all committed to the canonical repo and therefore identical on every machine. Dedup is **repo-state**, never machine-local JSONL, so two machines cannot double-file or double-count. Increment 1 runs entirely in GitHub Actions (not per-machine), so it holds no machine-local runtime state. No user-facing notice (no one-voice concern), no durable per-machine state to strand on topic transfer, no generated URL. The spec declares this posture explicitly ("Multi-machine posture (declared)").
+
+---
+
+## 8. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Trivial and safe. The lint is **report-only + config-gated (`prGate.classClosure` defaults off/dry-run) + repo-gated** — a buggy lint cannot block a merge (it exits 0 in dryRun) and is a no-op on any non-maintainer install. Back-out options, cheapest first: (a) leave defaults (already inert); (b) revert `.github/workflows/class-closure-gate.yml`; (c) revert the whole PR — no data migration, no agent-state repair, no runtime behavior to unwind (no runtime routes added in increment 1). The added `src/core` code is pure libraries with no callers in the runtime path yet.
+
+## Follow-up note — no-silent-fallbacks ratchet
+
+`DefectClassRegistry.ts` (`readDecisionDeclarations` absent-dir catch) and
+`StandardsEnforcementAuditor.gradeGuardCitation` (unresolvable-path catch) are pure
+libraries over a repo checkout with **no runtime / DegradationReporter surface** — their
+fail-closed catches return the correct answer (empty list / `resolved:false`, which the
+caller surfaces as a `gap` downgrade), not a degraded result. Both are tagged
+`@silent-fallback-ok` so the `no-silent-fallbacks` ratchet holds at baseline 491 rather than
+demanding a runtime degradation-report the library layer cannot emit.

package/upgrades/side-effects/three-standards-enforcement.md

@@ -0,0 +1,131 @@
+# Side-Effects Review — Enforcement of the three ratified standards (A/B/C)
+
+**Version / slug:** `three-standards-enforcement`
+**Date:** `2026-07-03`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Turns three operator-ratified constitutional standards into structure rather than reviewer willpower, per `docs/specs/three-standards-enforcement.md` (converged; this PR ships the enforcement MACHINERY only — the standard TEXTS ship separately under the already-granted ratification). Files touched: `skills/spec-converge/SKILL.md` and `skills/spec-converge/templates/reviewer-integration.md` (Standard A — the cross-machine review-check is upgraded from "a posture is *declared*" to "the default posture is `unified`; an undefended `machine-local` is a MATERIAL FINDING" over a closed 3-key justification taxonomy with a `machine-local-justification:` marker convention, bidirectional; Standard B — a self-heal-before-notify escalation-gate review-check requiring a watcher's operator-raise to be downstream of `selfHealAttempted && selfHealExhausted`, with declared `remediation-actions` + P19 brakes + `max-notification-latency` + severity class); `src/core/PostUpdateMigrator.ts` (a new idempotent `migrateThreeStandardsReviewChecks` so EXISTING agents receive the upgraded skill content — Migration Parity case 5b); `tests/integration/notification-flood-burst-invariant.test.ts` (Standard C — a table-driven routing CONTRACT test at the adapter/funnel boundary proving topic-less non-critical notices route to the ONE hub topic by default while HIGH/URGENT keep their own topic); and a new unit test `tests/unit/PostUpdateMigrator-threeStandardsReviewChecks.test.ts`. Decision points: the `/spec-converge` integration-reviewer verdict surface (A, B) — a review LENS on a smart reviewer, not a new blocking gate; and the Telegram topic-less-notice routing default (C) — a verification + test over machinery that already exists (the Agent-Health hub lane), no new block.
+
+## Decision-point inventory
+
+- `skills/spec-converge integration reviewer (A)` — modify — upgrades the cross-machine coherence review-check to reject an undefended machine-local (default `unified`), bidirectional, over a closed taxonomy. Semantic authority stays with the existing LLM reviewer; the `machine-local-justification` marker is the cheap deterministic signal.
+- `skills/spec-converge integration reviewer (B)` — add — a self-heal-before-notify review-check binding monitors/watchers/recurring notice sources.
+- `PostUpdateMigrator.migrateThreeStandardsReviewChecks` — add — idempotent, fingerprint-guarded re-copy of the two upgraded skill files to already-installed agents.
+- `TelegramAdapter topic-less-notice routing (C)` — pass-through — verified-already-correct default (Agent-Health hub lane routes housekeeping notices to one hub from the first item; HIGH/URGENT carve-out preserved); this PR proves the rule with a contract test, it introduces no new routing code.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+A/B are review-LENSES on the `/spec-converge` LLM reviewer — they raise MATERIAL FINDINGS for a human/operator to weigh, they do not hard-block a build. A false positive (e.g. a genuinely-correct `machine-local` surface the reviewer contests) surfaces as a finding the author defends with a taxonomy-keyed `machine-local-justification:` marker; it never silently rejects work. C's contract test asserts existing routing behavior; it rejects no runtime input (a topic-less notice still routes to the hub, HIGH/URGENT still get their own topic).
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+The deterministic marker LINT (A) and the self-heal field-schema LINT (B) are HARD-SEQUENCED to land WITH the registry ship (each standard's registered guard), NOT in this PR — so until they land, A/B enforcement is the per-spec `POST /spec/conformance-check` gate + the LLM review-lens (a semantic AUDIT), never a no-LLM deterministic guarantee. This is stated honestly in the spec and PR body; the review-check text does not claim the deterministic floor exists yet. C's contract test covers the enumerated routing cases (topic-less→hub, HIGH/URGENT→own, existing-owning-topic→that topic, unresolvable-hub→safe fallback) but cannot enumerate every future notice source — the funnel-level `createForumTopic` budget backstop (existing) remains the catch-all.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. A/B are prompt/skill-level review LENSES fed by a cheap deterministic marker convention — the constitutional *Signal vs. Authority* / *Body and the Mind* split: the marker (body) signals, the full-context reviewer (mind) holds authority. Neither is a brittle detector with blocking authority. C's change is a TEST over the existing `TelegramAdapter` Agent-Health hub lane + `AttentionTopicGuard` funnel — it USES the existing routing primitive rather than re-implementing one, and the migration reuses the exact `migrateMultiMachinePostureReviewDimension` pattern rather than inventing a new one.
+
+---
+
+## 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?**
+
+- [x] No — this change produces a signal consumed by an existing smart gate.
+
+The `machine-local-justification` marker and the declared self-heal fields are cheap deterministic SIGNALS; the `/spec-converge` LLM integration reviewer holds the semantic authority and contests correctness bidirectionally. No new brittle string-matcher gains blocking authority. The migration is a mechanical file re-copy (no decision logic). The Standard C contract test is a test, not a gate.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** the A upgrade EXTENDS the existing multi-machine posture check (same integration reviewer bullet) rather than shadowing it; both coexist. The B check is a new bullet in the same reviewer.
+- **Double-fire:** `migrateThreeStandardsReviewChecks` is fingerprint-guarded + marker-idempotent, so it re-copies each file at most once; it never fights `migrateMultiMachinePostureReviewDimension` (different marker string, and once one runs the file carries both bodies from the bundled source).
+- **Races:** none — migration is a synchronous one-shot file write with an installed-copy existence check.
+- **Feedback loops:** none.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- Other agents on the install base: YES — the upgraded spec-converge review-checks reach existing agents via the new migration (that is the intended Migration-Parity effect). New agents get them via `installBuiltinSkills`.
+- External systems: none. No Telegram/Slack/GitHub/Cloudflare behavior changes — C is verification of existing routing.
+- Persistent state: none new.
+- **Operator surface (Mobile-Complete):** No operator-facing actions added — the change is reviewer-prompt content + a migration + tests. Not applicable.
+
+---
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+No operator surface — not applicable. No dashboard renderer/markup, approval page, or grant/revoke/secret-drop form is touched.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN — with the reason, and it is the correct posture here (the standard applied to itself).**
+
+- The A/B review-check upgrades live in `/spec-converge` SKILL.md + template — **replicated** via git like all skills (machine-agnostic content); existing agents pick up the CHANGED content on their machine via `migrateThreeStandardsReviewChecks` (replication of the file is not the same as an already-running agent adopting it — the migration is the adoption path).
+- B's pattern is documentation + a per-watcher code shape; no new cross-machine state.
+- C's hub TOPIC is legitimately **machine-local** under `machine-local-justification: physical-credential-locality` — a Telegram forum + its topic ids are namespaced by the machine's bot token + forum binding, a per-disk service credential (NOT hardware-bound — this is the exact taxonomy-key correction the spec makes against its own first draft). The contract test asserts the hub id resolves from config/state and is NEVER a baked-in universal `7848` constant. The operator's CRITICAL-alert VIEW stays pool-unified via `GET /attention?scope=pool` (the acute miss-risk is closed); the residual Telegram-push gap is a registered Close-the-Loop follow-up, not built here.
+- Emits user-facing notices? C's hub routing is one-voice by construction (one hub topic). Durable state stranding on topic transfer? None new. Generated URLs? None.
+
+---
+
+## 8. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Pure code + prompt + test change — revert the commit and ship a patch. No persistent state, no data migration to unwind. The `migrateThreeStandardsReviewChecks` migration is idempotent and only re-copies bundled skill content over a stock installed copy; a revert restores the prior bundled content and the next update re-syncs installed copies. No user-visible regression during the rollback window (the review-check is a spec-review-time lens; C is verification of unchanged runtime routing).
+
+---
+
+## Conclusion
+
+The review confirms the change is a Signal-vs-Authority-compliant enforcement layer: A/B add review LENSES fed by cheap deterministic markers (semantic authority stays with the existing LLM reviewer), C proves an existing routing default with a table-driven contract test, and Migration Parity is satisfied by an idempotent migration that mirrors the established `migrateMultiMachinePostureReviewDimension` pattern. The purely-deterministic marker/field LINTS are honestly deferred to the registry ship (hard-sequenced) and the PR says so. Clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required
+
+Not a block/allow decision on messaging/dispatch, not a session-lifecycle change, not a coherence/idempotency/trust gate, and not a sentinel/guard/gate/watchdog runtime change — it is reviewer-prompt content + a migration + tests. Second-pass not required.
+
+---
+
+## Evidence pointers
+
+- `npx vitest run tests/unit/PostUpdateMigrator-threeStandardsReviewChecks.test.ts` → 7 passed (content-presence of A/B lenses + migration idempotency/fingerprint-guard).
+- `npx vitest run tests/integration/notification-flood-burst-invariant.test.ts` → 12 passed (5 new Standard C routing-contract cases + 7 existing burst-bound cases).
+- `npx tsc --noEmit` → clean.
+
+---
+
+## Class-Closure Declaration (display-only mirror)
+
+- **`defectClass`** — `structure-not-willpower-review-gap` (nearest existing: a review expectation that lived in prose/reviewer-habit where structure was required; the tiered-intelligence machine-local-memory slip surviving seven rounds is the motivating instance).
+- **`closure`** — `guard` for the migration + tests; the purely-deterministic marker/field LINT is a tracked `gap` hard-sequenced to the registry ship (per the spec's Rollout).
+- **`guardEvidence`** — enforcementType `gate` (the `/spec-converge` integration reviewer now instructs "undefended machine-local = MATERIAL FINDING", citation `skills/spec-converge/SKILL.md` + `skills/spec-converge/templates/reviewer-integration.md`; howCaught: the reviewer is now told to raise the exact machine-local-by-design declaration that previously passed) plus `lint`-graded migration/content tests (`tests/unit/PostUpdateMigrator-threeStandardsReviewChecks.test.ts`).
+- **`gap`** — the deterministic marker lint (A) + self-heal field-schema lint (B) land with the standards' registry guard; tracked in the spec's Close-the-Loop registration.