instar 1.3.767 → 1.3.769

package/upgrades/eli16/act1174-lint-floors.eli16.md

@@ -0,0 +1,75 @@
+# ELI16 — Two deterministic lint floors for Standards A and B
+
+## The one-sentence version
+
+Two tiny no-AI checkers now read a design spec's plain text and flag when it forgets
+the "which machine does this live on?" tag (Standard A) or writes a broken
+"try to fix it yourself before bugging the operator" plan (Standard B) — cheap
+signals that back up the smart reviewer instead of replacing it.
+
+## Why this exists
+
+Instar's constitution has two rules that used to live only in prose and reviewer
+habit:
+
+- **Standard A — "always multi-machine":** every piece of state a feature adds should
+  be SHARED across all the agent's machines by default. Keeping it on one machine is
+  only allowed for a short list of concrete reasons (a login/key that physically sits
+  on one disk, a piece of hardware, or something the operator explicitly signed off on).
+  This rule was ratified *because* a spec once wrongly kept its memory on one machine
+  and it survived SEVEN review rounds — only the operator caught it.
+- **Standard B — "self-heal before notify":** a watchdog should try a bounded, logged
+  self-repair FIRST and only ping the operator when that repair genuinely runs out of
+  road. A repair plan that does nothing, or that can retry forever, is exactly the trap
+  the rule forbids.
+
+The smart `/spec-converge` reviewer already reads for these. But "a reviewer will
+notice" is willpower, and Instar's root rule is **structure beats willpower**. So each
+rule gets a cheap deterministic floor that runs first and never needs to remember.
+
+## What actually shipped
+
+Two small parser scripts (no AI, just text rules) plus their tests:
+
+- **`scripts/lint-machine-local-justification.js` (Standard A).** It looks in a spec's
+  `## Multi-machine posture` section. If the spec says a surface is "machine-local" but
+  carries no `machine-local-justification: <reason>` tag, that's a finding. It also
+  checks the OTHER direction: a tag with a made-up reason (not one of the three allowed),
+  or an "operator ratified it" claim that cites no checkable proof (a commit SHA, a URL,
+  or a registry key), is also a finding.
+- **`scripts/lint-self-heal-fields.js` (Standard B).** When a spec declares a watchdog's
+  self-heal, it must list all its brakes (max attempts, time limit, backoff, dedupe key,
+  a breaker, a notification deadline with real units like "300s", an audit location, and
+  the concrete repair actions), plus the severity class. An empty repair-actions list
+  (the fake heal that does nothing) or a deadline written as a bare "300" with no units
+  is a finding.
+
+Both are registered in `docs/STANDARDS-REGISTRY.md` so Instar's own conformance auditor
+now grades Standards A and B as enforced by a real deterministic `lint` on disk, not just
+"documented" (the auditor confirmed: 0 → 2 lint-enforced standards).
+
+## The important nuance: report-first
+
+These lints ship in **report mode** — they PRINT their findings but exit 0 (they do not
+block anything yet). A `--strict` flag makes them exit non-zero; that is the FAIL
+capability the tests exercise and the hook a future graduation can flip on. This is
+deliberate: the marker convention is brand new, existing specs predate it, and the spec's
+own honesty clause says the deterministic floor's grade is "inert until the registry
+ship." Shipping a brand-new blocking gate over the whole spec corpus would be a wall of
+false failures. Report-first is the graduated-rollout path Instar always takes with a new
+enforcement.
+
+## Signal vs. authority
+
+Neither lint decides the hard question. Standard A's lint cannot tell whether a
+justification is TRUE; Standard B's lint cannot tell whether a repair is genuinely
+SUBSTANTIVE or a severity label is HONEST. Those calls stay with the smart `/spec-converge`
+reviewer. The lint is the cheap body; the reviewer is the mind. Together they enforce the
+rule; neither alone does.
+
+## What did NOT change
+
+No constitutional text was written or re-ratified — Standards A and B were already
+ratified by the operator on 2026-07-03. This change is purely the enforcement machinery
+(two lints + tests + the registry rows that register them as guards). It touches no
+runtime server code and changes nothing for a user.

package/upgrades/side-effects/act1174-lint-floors.md

@@ -0,0 +1,124 @@
+# Side-Effects Review — ACT-1174: two deterministic lint floors (Standards A + B)
+
+**Version / slug:** `act1174-lint-floors`
+**Date:** `2026-07-04`
+**Author:** `echo (build hand)`
+**Second-pass reviewer:** `not required (Tier 1)`
+
+## Summary of the change
+
+Ships the two DEFERRED deterministic lint floors named in
+`docs/specs/three-standards-enforcement.md` (§178-202 for A, §256-289/§343-361 for B) —
+the "registry ship" the spec hard-sequences against each standard's registered guard.
+Two no-LLM parser scripts + their unit tests + fixtures, plus the STANDARDS-REGISTRY
+guard-registration rows that let the conformance auditor grade Standards A and B as
+enforced by a deterministic `lint`.
+
+Files touched:
+- `scripts/lint-machine-local-justification.js` — Standard A marker floor (no-LLM).
+- `scripts/lint-self-heal-fields.js` — Standard B self-heal field-schema floor (no-LLM).
+- `tests/unit/lint-machine-local-justification.test.ts`, `tests/unit/lint-self-heal-fields.test.ts` — self-tests.
+- `tests/fixtures/spec-lint/*.md` — positive / negative / bidirectional / out-of-scope fixtures.
+- `docs/STANDARDS-REGISTRY.md` — the two `**Applied through.**` rows now cite the lints (enforcement registration, NOT new ratification prose).
+- `upgrades/eli16/act1174-lint-floors.eli16.md`, `upgrades/side-effects/act1174-lint-floors.md`, `upgrades/next/act1174-lint-floors.md` — gate artifacts.
+
+No constitutional text is minted or re-ratified (the standard TEXTS were ratified by the operator 2026-07-03). No runtime `src/` code changes.
+
+## Decision-point inventory
+
+- `Standards Enforcement-Coverage auditor classification (StandardsEnforcementAuditor)` — pass-through — the audit reads the registry and now classifies A + B as `lint` because the two rows cite `scripts/lint-*.js` (verified: baseline lint 0 → 2, A/B out of the gaps list, dangling still 0).
+- `/spec-converge integration reviewer` — pass-through — the semantic authority is unchanged; these lints are the deterministic SIGNAL beneath it.
+
+---
+
+## 1. Over-block
+
+The lints DO have a block/allow surface, but ONLY under `--strict`. In report mode (the shipped default) they never block. Under `--strict` the plausible over-block is: a spec that legitimately mentions "machine-local" inside its `## Multi-machine posture` section as prose discussion (not a real surface) would trip A1. This is mitigated by scoping A1's trigger to the posture section AND skipping `<placeholder>` marker values, and by the report-first default — a false positive is a printed line, never a blocked commit. `--strict` is opt-in (tests + a future graduation), so no live over-block exists today.
+
+---
+
+## 2. Under-block
+
+The deterministic floor is PRESENCE + well-formedness only, by design (Signal vs. Authority). It misses: a marker whose key is valid but substantively WRONG (A), and a self-heal whose fields are all present but whose remediation is a plausible-but-ineffective no-op or whose severity class is dishonestly `recoverable` (B). Those are exactly the semantic calls left to the `/spec-converge` reviewer — the lint is not meant to catch them. A spec that omits a posture section entirely is also not flagged (that is the reviewer's §168 call).
+
+---
+
+## 3. Level-of-abstraction fit
+
+Correct layer: a cheap, brittle DETECTOR that produces a signal, explicitly paired with the existing high-context `/spec-converge` reviewer that owns the semantic authority. This is the constitutional Signal-vs-Authority / Body-and-Mind split the spec mandates (§87-95). The lint does NOT hold blocking authority over a merge in its shipped (report) mode.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** docs/signal-vs-authority.md
+
+- [x] No — this change produces a signal consumed by an existing smart gate (the `/spec-converge` integration reviewer), and in its shipped mode it does not block at all.
+
+The lints are deterministic signals. Their `--strict` FAIL capability exists for tests and a future, separately-decided CI graduation; it is not wired into the blocking `npm run lint` chain. The reviewer holds semantic authority.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** none. The lints are standalone scripts, not wired into the blocking lint `&&`-chain, so they cannot shadow an existing lint or be shadowed.
+- **Double-fire:** none. No runtime path invokes them; they are dev/CI tooling run explicitly or by their tests.
+- **Races:** none. Pure fs-read parsers, no shared state.
+- **Feedback loops:** none.
+
+The one real interaction is the Standards Enforcement-Coverage auditor: the registry rows now resolve to on-disk `lint` guards, which RAISES the enforced ratio (0.4429 → 0.4714). That is the intended effect, not a regression; the coverage ratchet (`standards-coverage.mjs --check`) passes (floors: ratio ≥ floor, dangling ≤ 0).
+
+---
+
+## 6. External surfaces
+
+- Other agents on the same machine? No.
+- Install base? These are instar-repo dev/CI tooling; they do not ship into agent homes as runtime behavior.
+- External systems? No.
+- Persistent state? No (the coverage script's `.instar/standards-coverage.json` output is untracked runtime state, never a committed baseline).
+- Operator surface (Mobile-Complete): No operator-facing actions — dev/CI tooling only.
+
+---
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN — pure per-machine dev/CI tooling with no durable state.** These lint scripts + tests + fixtures are repo source, replicated to every machine via git like all source (so there is no per-machine divergence to reconcile). They emit no user-facing notices (no one-voice gating needed), hold no durable state (nothing to strand on a topic transfer), and generate no URLs. The registry rows they add are likewise git-replicated source. There is no runtime state surface introduced by this change, so the multi-machine posture question is satisfied structurally: source is uniform across machines by construction.
+
+---
+
+## 8. Rollback cost
+
+Pure additive dev/CI change — revert the commit and ship as the next patch. No persistent state, no data migration, no agent-state repair, no user-visible regression. The registry rows revert cleanly (the conformance auditor simply re-grades A/B back to their prior kind). Because the lints ship report-first and are not in the blocking chain, a rollback cannot un-block anything that was blocking.
+
+## Conclusion
+
+The review produced no design changes. The two lints are correctly scoped as deterministic signals beneath the existing reviewer authority, ship report-first per the spec's honesty / hard-sequencing clause, and are registered so the conformance auditor grades Standards A and B as `lint`-enforced. Clear to ship as a Tier-1 change.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required (Tier 1)
+**Independent read of the artifact: [concur]**
+
+Tier-1 low-risk additive tooling; no independent reviewer required per the tier policy.
+
+---
+
+## Evidence pointers
+
+- `npx vitest run tests/unit/lint-machine-local-justification.test.ts tests/unit/lint-self-heal-fields.test.ts` → 13 passed (7 A + 6 B).
+- `node scripts/standards-coverage.mjs` → `lint 2` (baseline 0), A/B absent from the gaps list, dangling 0, enforced-ratio 0.4429 → 0.4714.
+- Manual fixture runs: A good-defended/good-ratified pass `--strict`; A-bad-undefended (A1), A-bad-spurious-key (A2), A-bad-ratified-noref (A2) fail `--strict`; B-good-complete + B-out-of-scope pass; B-bad-missing-fields (B1), B-bad-noop-and-unitless (B2/B3/B4) fail `--strict`; report mode exits 0 on all bad fixtures.
+
+---
+
+## Class-Closure Declaration (display-only mirror)
+
+No agent-authored-artifact defect and no self-triggered controller — not applicable. This change adds enforcement lints; it does not fix a defect in an LLM prompt/hook/config/skill/standards-text, and it introduces no loop/monitor/sentinel/reaper/scheduler/recovery path.

package/upgrades/side-effects/outbound-advisory-offswitch-config-shape.eli16.md

@@ -0,0 +1,41 @@
+# ELI16 — the "off" button for the auto-message advisory didn't do anything
+
+## The story
+
+Instar has an "outbound advisory" — when a background job tries to send you a message, it first checks
+the text for raw file paths, dev jargon, or localhost links and, if it finds any, holds the message so
+the agent can fix it. It's on by default, and the docs told operators they could turn it off by
+setting a switch: `messaging.outboundAdvisory.enabled: false`.
+
+The problem: that switch never worked on a real setup. The config's "messaging" section is a **list**
+of chat platforms, not a labeled box — so a switch addressed as if it were a box *inside* that list
+can't be read. The program looked, found nothing, and used the default ("on"). So an operator who
+tried to turn the advisory off would find it stubbornly still on, with no error explaining why.
+
+This is the same shape of bug we fixed earlier for the promise follow-through feature (PR #1379). That
+one was worse — a feature you could never turn *on*. This one is milder — a feature you can't turn
+*off* — because it defaults to on, so it still works; you just can't disable it.
+
+## What this change does
+
+It moves the switch to a spot the program can actually read: a **top-level `outboundAdvisory`**
+setting, right next to the other real settings instead of buried in the platform list. Setting
+`outboundAdvisory.enabled: false` there now genuinely turns the advisory off. The old (broken) nested
+key is still honored where it *can* be read (for setups that use a box-shaped config), so nothing that
+worked before breaks. The docs are corrected to point at the new switch — both for new agents and, via
+a small automatic update, for agents that already have the old wording in their notes.
+
+## Why it's safe
+
+- The advisory is inform-only — it never blocks your messages — so there's no risk of it wrongly
+  rejecting anything. The only change is that its off-button now works.
+- Old configs keep working (the old key is a fallback), so it's backwards compatible.
+- It's a plain code + docs change; if it were ever wrong, the fix is a simple revert with no leftover
+  data to clean up.
+
+## How we know it works
+
+A new test sets up the config the **real** way — "messaging" as a list — flips the new top-level
+off-switch, and confirms the advisory reports itself disabled (which was impossible before the fix). It
+also checks the default-on behavior when the switch isn't set, and that the old box-shaped config still
+works. The 58 existing advisory tests all still pass.

package/upgrades/side-effects/outbound-advisory-offswitch-config-shape.md

@@ -0,0 +1,117 @@
+# Side-Effects Review — outbound-advisory off-switch reachable on array-shaped messaging
+
+**Version / slug:** `outbound-advisory-offswitch-config-shape`
+**Date:** `2026-07-04`
+**Author:** `Echo`
+**Second-pass reviewer:** `not required (Tier-1)`
+
+## Summary of the change
+
+The outbound-advisory preflight route read its off-switch (and tuning knobs) at
+`messaging.outboundAdvisory.*`. On a real install `messaging` is a JSON **array** of adapter configs,
+so that dot-path resolves `undefined` → the read's default. For the `enabled` read (default `true`)
+that meant the **documented off-switch (`messaging.outboundAdvisory.enabled: false`) had no effect —
+an operator could not disable the advisory** (the un-DISABLABLE sub-class of the PR #1379 bug). Fix:
+read from the reachable **top-level `outboundAdvisory`** block (canonical), honoring the legacy
+`messaging.outboundAdvisory` as a back-compat fallback. Applied to all four reads
+(`enabled`, `ignoreEscalationThreshold`, `ignoreEscalationSlugThreshold`, `timeClaim.enabled` dev-gate),
+the documented off-switch key in both templates, and an existing-agent CLAUDE.md doc migration.
+Files: `src/server/routes.ts`, `src/core/PostUpdateMigrator.ts`, `src/scaffold/templates.ts`, + test.
+
+## Decision-point inventory
+
+- `POST /messaging/preflight` `enabled` gate (`routes.ts`) — **modify** — top-level-first resolution.
+- `OutboundAdvisoryAudit` threshold reads (`routes.ts`) — **modify** — top-level-first.
+- `timeClaim.enabled` dev-gate value (`routes.ts`) — **pass-through** — sourced top-level-first;
+  `undefined → live-on-dev` semantics unchanged.
+- CLAUDE template off-switch text (both `PostUpdateMigrator` content + `scaffold/templates`) —
+  **modify** — documents the reachable top-level key.
+- `PostUpdateMigrator` TIME_CLAIM anchor marker — **modify** — matched on the stable `- Off-switch: \``
+  prefix so it still anchors regardless of which key the line carries.
+- New `migrateClaudeMd` swap — **add** — updates an existing agent's stale nested-key off-switch line.
+
+## 1. Over-block / 2. Under-block
+
+No block/allow surface change of consequence: the advisory is inform-only and never blocks a message.
+The only behavior change is that the **off-switch now actually works** — an operator who sets
+`outboundAdvisory.enabled: false` disables the advisory (previously impossible). Over-block N/A;
+under-block N/A.
+
+## 3. Level-of-abstraction fit
+
+Right layer — same top-level-first config-read pattern as PR #1379, applied at the read sites. No new
+authority, no new machinery.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — no runtime block/allow surface changes; the advisory remains inform-only. This restores a
+  broken operator control (an off-switch), it does not add gating authority.
+
+## 5. Interactions
+
+- **Shadowing:** none — top-level-first read is a superset of prior behavior; on object-messaging the
+  legacy fallback resolves identically.
+- **Double-fire / races / feedback loops:** none.
+- **Migration marker:** the TIME_CLAIM anchor now matches the stable `- Off-switch: \`` prefix, so it
+  still finds the off-switch line whether CLAUDE.md carries the old nested or the new top-level key —
+  verified the substring is present in both.
+
+## 6. External surfaces
+
+- **Install base / agents:** existing agents get the corrected off-switch DOC via the new
+  `migrateClaudeMd` swap (content-sniff, idempotent) on their next update; new agents via the
+  templates. The CODE fix ships with the server. No config migration needed to keep working (top-level
+  is additive; legacy still honored).
+- **Operator surface:** restores a documented operator control (the off-switch). No new UI/route.
+- **Persistent state / external systems:** none.
+
+## 6b. Operator-surface quality
+
+No dashboard/approval/form surface — not applicable (the off-switch is a config edit, now at a
+reachable key, documented for the operator).
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN** — config (`.instar/config.json`) is per-machine; the advisory runs
+per-machine on the sending machine. This change only alters where in the local config the flag is
+read. No cross-machine state, notice, durable state, or URL.
+
+## 8. Rollback cost
+
+Pure code + doc change — revert the reads + template text + the one migration block. No persistent
+state; the top-level key is additive and the legacy fallback preserves prior behavior. Zero-cost
+back-out.
+
+## Conclusion
+
+Restores the outbound-advisory off-switch that was silently broken on every real (array-`messaging`)
+install — the un-DISABLABLE sibling of the PR #1379 un-ENABLABLE bug, found by the sibling audit
+(`docs/investigations/messaging-config-unreachable-audit-2026-07-04.md`). Code + docs + existing-agent
+migration + a real-LiveConfig array-shape test. Clear to ship.
+
+## Second-pass review (if required)
+
+**Reviewer:** not required (Tier-1)
+
+## Evidence pointers
+
+- `tests/unit/outbound-advisory-config-shape.test.ts` — real LiveConfig + real array-shaped config:
+  top-level off-switch disables (was impossible before the fix), default-on when unset, object-shape
+  back-compat.
+- Existing `outbound-advisory-routes` / `outbound-advisory` / `telegram-reply-advisory-script` tests
+  (58) stay green; `tsc` clean; `lint-no-unreachable-messaging-gate` clean.
+
+## Class-Closure Declaration (display-only mirror)
+
+- **`defectClass`** — `config-unreachable-on-shape` (the PR #1379 class; this is its un-DISABLABLE
+  default-ON sub-class).
+- **`closure`** — `gap` — the #1381 lint catches the default-OFF (un-enablable) sub-class; the
+  default-ON un-disablable sub-class (`.get('messaging.*.enabled', true)` with a documented off-switch)
+  is not reliably lint-detectable without false positives (documented in the #1381 side-effects
+  follow-ups). This fix ships the direct regression test + moves the config to the reachable
+  convention; the class-level guard for the un-disablable sub-class remains a tracked gap.
+- **`guardEvidence`** — n/a for `closure: gap`.
+- **`gap`** — tracked in `docs/investigations/messaging-config-unreachable-audit-2026-07-04.md`
+  (follow-up 2) + the #1381 side-effects artifact.