instar 1.3.519 → 1.3.521

package/scripts/instar-dev-precommit.js

@@ -32,6 +32,7 @@ import { checkEli16Overview, MIN_ELI16_CHARS } from './eli16-overview-check.mjs'
 import { verifyProposalDerivedRunbooks } from '../skills/instar-dev/scripts/verify-proposal-derived-runbook.mjs';
 import { classifyTier, decideRequirementSet } from './lib/classify-tier.mjs';
 import { recognizeConvergence } from './lib/convergence-recognition.mjs';
+import { isOperatorSurfaceFile, artifactAddressesOperatorSurfaceQuality } from './lib/operator-surface.mjs';
 
 // Report-Backed Converging Audit (docs/specs/CONVERGING-AUDIT-DEFAULT.md, Part B).
 // The precommit reads NO config file and runs pre-compile, so it cannot import
@@ -884,6 +885,7 @@ if (!promotionGateResult.ok) {
 // ─── Pass ────────────────────────────────────────────────────────────────
 
 assertFrameworkGenerality(inScopeFiles, validTrace.trace);
+assertOperatorSurfaceQuality(staged, validTrace.trace);
 
 console.error(
   `[instar-dev-precommit] OK — trace ${path.basename(validTrace.entry.file)} covers ${inScopeFiles.length} in-scope file(s), artifact ${validTrace.trace.artifactPath} verified, spec ${spec} is converged + approved` +
@@ -930,6 +932,49 @@ function assertFrameworkGenerality(inScopeFiles, trace) {
   }
 }
 
+// Operator-Surface Quality review gate (docs/STANDARDS-REGISTRY.md →
+// "Operator-Surface Quality", CMT-1434). A change touching an operator surface
+// (dashboard renderers/markup, approval pages, grant/secret forms) must answer
+// the operator-surface-quality question in the side-effects artifact IN WRITING:
+// does the surface lead with its primary action, expose zero raw internals,
+// de-emphasize destructive actions, and work at phone width? A "reachable but
+// bad" surface passes Mobile-Complete and still fails the operator (the
+// 2026-06-12 "abysmal" Mandates-grant-form lesson) — this makes the quality
+// question unskippable. Operator-surface files are NOT in the gate's inScope set
+// (they live under dashboard/), so we scan the full STAGED set, not inScopeFiles.
+// Scoped tight so a non-surface commit pays nothing. Companion to
+// assertFrameworkGenerality.
+function assertOperatorSurfaceQuality(stagedFiles, trace) {
+  const touched = (stagedFiles || []).filter(isOperatorSurfaceFile);
+  if (touched.length === 0) return;
+  const artifactRel = trace.sideEffectsPath || trace.artifactPath;
+  if (!artifactRel) return; // a missing artifact is already blocked upstream
+  const artifactAbs = path.resolve(ROOT, artifactRel);
+  if (!fs.existsSync(artifactAbs)) return;
+  const content = fs.readFileSync(artifactAbs, 'utf8');
+  // The artifact must engage the operator-surface-quality question (the §6b
+  // section seeded by skills/instar-dev/templates/side-effects-artifact.md).
+  if (!artifactAddressesOperatorSurfaceQuality(content)) {
+    blockCommit(
+      touched,
+      [
+        'Operator-Surface Quality review gate:',
+        `  ${touched.join(', ')} change an OPERATOR SURFACE,`,
+        '  but the side-effects artifact never answers the operator-surface-quality',
+        '  question — a surface can be phone-reachable (Mobile-Complete) and still be',
+        '  unusable (the 2026-06-12 "abysmal" Mandates grant-form lesson, CMT-1434).',
+        '',
+        '  Add the "## 6b. Operator-surface quality" section and answer in writing:',
+        '  does the surface (1) lead with its primary action, (2) expose zero raw',
+        '  internals as primary content, (3) de-emphasize destructive actions, and',
+        '  (4) read in plain language at phone width? (Standard:',
+        '  docs/STANDARDS-REGISTRY.md → "Operator-Surface Quality". Template:',
+        '  skills/instar-dev/templates/side-effects-artifact.md §6b.)',
+      ].join('\n'),
+    );
+  }
+}
+
 function blockCommit(files, reason) {
   console.error('');
   console.error('╔════════════════════════════════════════════════════════════════════╗');
@@ -1125,6 +1170,7 @@ function enforceTier1(trace, traceFile) {
   }
 
   assertFrameworkGenerality(inScopeFiles, trace);
+  assertOperatorSurfaceQuality(staged, trace);
 
   console.error(
     `[instar-dev-precommit] OK (Tier 1) — trace ${traceName} covers ${inScopeFiles.length} in-scope file(s), ` +

package/scripts/lib/operator-surface.mjs

@@ -0,0 +1,54 @@
+/**
+ * operator-surface.mjs — pure decision logic for the Operator-Surface Quality
+ * review gate in the instar-dev commit gate (docs/STANDARDS-REGISTRY.md →
+ * "Operator-Surface Quality", CMT-1434).
+ *
+ * Two pure predicates, extracted so the gate's load-bearing decisions are
+ * unit-testable without git/fs mocking (the classify-tier.mjs pattern):
+ *
+ *   - isOperatorSurfaceFile(path): is this staged file an operator surface — a
+ *     dashboard renderer/markup file, an approval page, or a grant/secret form?
+ *   - artifactAddressesOperatorSurfaceQuality(content): does the side-effects
+ *     artifact engage the operator-surface-quality question in writing?
+ *
+ * SIGNAL-FREE: these never block; the gate (instar-dev-precommit.js) reads them
+ * and decides. Keeping them pure means both sides of every boundary are pinned
+ * by tests (Testing Integrity → semantic-correctness).
+ */
+
+/**
+ * An operator surface is anything a person uses to authorize, decide, or act:
+ *   - dashboard renderer / markup files (dashboard/*.js, dashboard/*.html), AND
+ *   - approval pages / one-time-approval links / secret-drop forms (a file whose
+ *     basename starts with approval / operator-approval / secret-drop).
+ * Build/test/spec siblings (*.test.js, *.spec.js) are NOT surfaces.
+ */
+export const OPERATOR_SURFACE_RE =
+  /^dashboard\/.+\.(?:js|html)$|(?:^|\/)(?:approval|operator-approval|secret-drop)[^/]*\.(?:js|html|ts)$/i;
+
+/**
+ * True when a staged file path is an operator surface.
+ * @param {string} file repo-relative path
+ * @returns {boolean}
+ */
+export function isOperatorSurfaceFile(file) {
+  const f = String(file ?? '');
+  if (!f) return false;
+  // A test/spec file that happens to live under dashboard/ or match the approval
+  // basename is NOT itself an operator surface — it's a guard for one.
+  if (/\.(?:test|spec)\.(?:js|ts|mjs)$/.test(f)) return false;
+  return OPERATOR_SURFACE_RE.test(f);
+}
+
+/**
+ * The artifact engages the operator-surface-quality question when it carries the
+ * §6b heading/phrase (seeded by side-effects-artifact.md). The gate's job is to
+ * ensure the question is structurally PRESENT for every operator-surface change —
+ * an agent that deletes/skips the section (or writes a bespoke artifact omitting
+ * it) is blocked. (Same strength as the framework-generality gate.)
+ * @param {string} content the side-effects artifact text
+ * @returns {boolean}
+ */
+export function artifactAddressesOperatorSurfaceQuality(content) {
+  return /operator[- ]surface quality/i.test(String(content ?? ''));
+}

package/skills/instar-dev/templates/side-effects-artifact.md

@@ -101,6 +101,21 @@
 
 ---
 
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+**REQUIRED whenever this change touches an operator surface** — a dashboard renderer/markup file (`dashboard/*.js`, `dashboard/*.html`), an approval page, or a grant/revoke/secret-drop form. The pre-commit gate (`scripts/instar-dev-precommit.js`) refuses the commit if this section is missing when an operator-surface file is staged. Reachable-but-bad still fails the operator (the 2026-06-12 "abysmal" Mandates-grant-form lesson, CMT-1434): Mobile-Complete asks *can they do it from a phone?*; this asks *is it good when they do?*
+
+Answer each in writing (a "no" or unjustified "n/a" blocks the commit):
+
+1. **Leads with the primary action?** The thing the operator came to do is visible and actionable on arrival — never collapsed behind a toggle, below the fold, or after explanatory prose.
+2. **Zero raw internals as primary content?** No JSON blobs, fingerprints, UUIDs, hashes, or enum/slug values shown as headline content — only human language; identifiers de-emphasized as support metadata when genuinely needed.
+3. **Destructive actions de-emphasized?** Revoke/delete/stop is visually quieter than the constructive primary action and never appears above it.
+4. **Plain language + phone width?** Labels/states read the way a non-engineer would say them; verified at phone width — real tap targets, readable type, no horizontal scroll, no truncated table hiding the answer.
+
+[Specific findings per criterion. "Grant form renders open as the card's primary block (mnd-grant-block); Revoke demoted to a collapsed mnd-revoke-details below it; bounds/fingerprints humanized, raw ids kept only on the muted 'For support' line; audit table stacks at ≤640px." If this change touches NO operator surface, state: "No operator surface — not applicable."]
+
+---
+
 ## 7. Multi-machine posture (Cross-Machine Coherence)
 
 **When this agent runs on MORE THAN ONE machine, what is this feature's posture?**

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-13T09:03:12.807Z",
-  "instarVersion": "1.3.519",
+  "generatedAt": "2026-06-13T09:25:14.093Z",
+  "instarVersion": "1.3.521",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.521.md

@@ -0,0 +1,69 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+The generic machinery that future cross-machine memory stores (preferences, relationships, learnings, …) will plug into. This step builds the reusable substrate ONLY — it adds no concrete store kind (that lands with the first store, WS2.1).
+
+- **Replicated-record envelope** (`src/core/ReplicatedRecordEnvelope.ts`) — the fields every replicated change carries on top of its store-specific data: `recordKey`, the `HybridLogicalClock` stamp (`hlc`), a `put`/`delete` `op`, the author machine (`origin`), and the single prior stamp the author had already merged for that key (`observed` — the last-writer-witness; absent ⇒ "no prior witness" ⇒ flag-on-conflict, the safe direction). A strict, parameterizable validator mirrors the coherence-journal typed-schema discipline (rejects free text, drops + counts unknown fields, jails path-shaped fields, validates the HLC fields). A `ReplicatedKindRegistry` (ships EMPTY) is the registration mechanism each store will use.
+- **Flag-gated emission (dark per store)** — a store emits its kind only when `multiMachine.stateSync.<store>.enabled` is on (default false). When off, no journal traffic — a strict no-op.
+- **Flag-coherence-gated emission** — a kind is forwarded to a peer ONLY when that peer advertises (`seamlessnessFlags.stateSyncReceive`) it can receive it. Emitting a new kind to an older peer would be silently dropped by the applier — the named data-loss skew mode this gate prevents. The per-peer decision is correct for N peers; a boot-time pool-flag-coherence check surfaces a mixed-flag pool ONCE, coalesced.
+- **Config + invariants** (`src/core/stateSyncConfig.ts`, `ConfigDefaults.ts`, `types.ts`) — the foundation-level `multiMachine.stateSync` knobs (journal budget, the §3.4 HLC drift ceiling, snapshot-cache bounds), validated at startup by `validateStateSyncInvariants()` (an out-of-range value is REJECTED, not silently coerced), backfilled to existing agents via the add-missing migration path.
+
+Pure MECHANISM, dark by default. The only two refusal surfaces are at the receive door (the validator rejects malformed data) and the emission door (don't forward to a non-advertising peer); neither blocks a user-initiated action. A single-machine install is a strict no-op.
+
+Two cohesive changes (topic 22367, CMT-1434):
+
+1. **Mandates dashboard tab redesign.** The Mandates card now leads with the Grant
+   form as its primary, always-open block; Revoke is demoted to a quiet, collapsed
+   control beneath it. Raw JSON bounds, agent fingerprints, and scope slugs are
+   replaced with a plain-language summary sentence; identifiers survive only on a
+   muted "For support" line. Existing grants read as plain English ("Adam Admin can
+   deploy to production until 9:37 PM — authorized by you"), and the decision-audit
+   table stacks into labelled rows at phone width so the reason column is never
+   truncated. Renderer + markup + CSS only — the mandate API, payloads, and
+   PIN-never-retained discipline are unchanged. Ships via `dashboard/` static
+   serving, so it reaches every agent through the normal update path.
+
+2. **New constitutional standard: Operator-Surface Quality** (sibling to
+   Mobile-Complete Operator Actions) in `docs/STANDARDS-REGISTRY.md`. Where
+   Mobile-Complete asks "can the operator do this from a phone?", this asks "is it
+   actually good when they do?" — lead with the primary action, zero raw internals,
+   de-emphasized destructive actions, plain language, phone-width layout. It lands
+   with teeth: a new operator-surface-quality question in the instar-dev
+   side-effects review template, and a pre-commit gate
+   (`scripts/instar-dev-precommit.js`) that blocks any commit touching an operator
+   surface unless the review answers it. The standard names that gate, so the
+   Standards-Enforcement-Coverage audit classifies it as an enforced gate.
+
+## What to Tell Your User
+
+None — internal substrate (no user-facing surface). The replicated cross-machine memory stores that this foundation enables ship later, store by store, each with its own announcement when its user-facing surface (conflict viewing, rollback) lands.
+
+- **A cleaner Mandates screen on your phone**: "I gave the Mandates tab a real
+  overhaul. The action you actually came to do — granting someone permission — is
+  now front and centre, the risky Revoke button is tucked quietly out of the way,
+  and the screen reads in plain English instead of raw data. The history list also
+  finally fits your phone without cutting off the reason column."
+- **A new quality bar for everything you touch**: "I also turned this into a
+  standing rule for myself: any screen you use to approve or decide something has to
+  be genuinely good to use on your phone, not just technically reachable. I added an
+  automatic check that holds me to it whenever I build one of those screens."
+
+## Summary of New Capabilities
+
+None — internal change. This is the reusable substrate the first concrete replicated store (the cross-machine preferences pool, WS2.1) will register a journal kind onto; it exposes no new endpoint, config a user would set, or behavior a user would notice until a store turns its flag on.
+
+| Capability | How to Use |
+|-----------|-----------|
+| Redesigned Mandates tab (humanized, mobile-first) | Open the Mandates tab in the dashboard |
+| Operator-Surface Quality standard | docs/STANDARDS-REGISTRY.md (constitution) |
+| Operator-surface-quality pre-commit gate | automatic during instar-dev work |
+
+## Evidence
+
+Tier-1 unit tests in `tests/unit/ReplicatedRecordEnvelope.test.ts` (46 tests, all green) cover both sides of every boundary: the validator (valid put/delete; missing recordKey/hlc; malformed hlc; observed present-valid / present-malformed-rejected / absent-legal; unknown-field-dropped-and-counted; path-shaped field jailed; non-object/free-text rejected; store-schema rejection), the registry (empty default, unregistered-kind absent, conflict-throws, idempotent re-register), flag-gated emission (enabled=false ⇒ no emission; enabled=true ⇒ emits), flag-coherence (advertising ⇒ emit; non-advertising ⇒ withhold + surface; 3+-peer mix ⇒ per-peer correctness + ONE coalesced surface), `validateStateSyncInvariants` (maxDriftMs floor/ceiling/in-range), and a wiring-integrity case for the advert self-report (driven by registered+enabled stores, never a hardcoded true).
+
+Gate-parity (run in the worktree): `tsc --noEmit` clean; `no-silent-fallbacks` = 471 (= BASELINE, no bump — the new files carry no un-tagged silent catches); `docs-coverage --check` PASS (class floor 55% held — `ReplicatedRecordEnvelope` documented in `multi-machine.md` + `under-the-hood.md`); `feature-delivery-completeness` PASS; `lint-dev-agent-dark-gate` PASS (the config line-map recomputed for the +17 cartographer shift); focused suites `CoherenceJournal*` / `JournalSyncApplier*` / `CoherenceJournalReader` + the new test all green.

package/upgrades/side-effects/multi-machine-replicated-store-foundation-step2-journal-kind.md

@@ -0,0 +1,104 @@
+# Side-Effects Review — Replicated-store foundation Step 2 (journal-kind tagging + flag-gated emission)
+
+**Version / slug:** `multi-machine-replicated-store-foundation-step2-journal-kind`
+**Date:** `2026-06-13`
+**Author:** `Echo (instar-dev subagent)`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Step 2 of the multi-machine replicated-store foundation builds the GENERIC machinery that the concrete replicated stores (preferences, relationships, learnings, …) will layer a journal kind onto — it adds NO concrete store kind itself. New module `src/core/ReplicatedRecordEnvelope.ts` defines (A) the replicated-record envelope type (`recordKey`, `hlc`, `op`, `origin`, `observed`) plus a strict, parameterizable validator that mirrors the CoherenceJournal typed-schema discipline (reject free text, drop+count unknown fields, jail path-shaped fields, validate HLC fields); (B) a `ReplicatedKindRegistry` (ships empty — the registration mechanism, no concrete kind); (C) flag-gated emission (`isStoreEmissionEnabled` — a store emits only when `multiMachine.stateSync.<store>.enabled`, default false); and (D) flag-coherence-gated emission (`shouldEmitToPeer` + `checkPoolFlagCoherence` — never forward a kind to a peer that does not advertise it can receive it, N-peer-correct, one coalesced surface). New module `src/core/stateSyncConfig.ts` resolves + validates the foundation-level `stateSync` knobs (`validateStateSyncInvariants`, the §3.4 maxDriftMs clamp). Config defaults (`ConfigDefaults.ts` `multiMachine.stateSync`), a `StateSyncConfig` type + the `stateSyncReceive` advert flag (`types.ts`), and the server wiring (startup invariant assertion, the empty registry, the advert self-report, the boot-time coherence check) complete it. The change is pure MECHANISM, dark by default; a single-machine install is a strict no-op.
+
+## Decision-point inventory
+
+- `validateReplicatedEnvelope` (RECEIVE door) — **add** — rejects malformed replicated-record data before it can enter a stream. The only "block" surface, and it blocks DATA, never a user action.
+- `isStoreEmissionEnabled` / `shouldEmitToPeer` (EMISSION door) — **add** — withholds emitting a store's kind when the store is dark or a peer can't receive it. Withholds JOURNAL TRAFFIC, never a user action.
+- `validateStateSyncInvariants` (startup config gate) — **add** — rejects an out-of-range foundation knob at boot (loud, not silent), mirroring `validateSeamlessnessInvariants`.
+- `seamlessnessFlags.stateSyncReceive` (capability advert) — **add** — self-reported per-store receive capability in the capacity heartbeat.
+
+---
+
+## 1. Over-block
+
+The validator rejects: a non-object/array; a missing/empty/oversized/path-shaped `recordKey`; a malformed/missing `hlc`; an `op` outside `{put,delete}`; a missing/empty/path-shaped `origin`; a PRESENT-but-malformed `observed`. These are all genuinely-malformed records — there is no legitimate replicated record that fails them. The one deliberate design choice that could look like over-block is the path-shape jail on `recordKey`/`origin`: a store whose primary key legitimately contains a `/` would be rejected. This is intentional (§4 "jail any path-shaped field") — the envelope carries identifiers, not paths, and a concrete store (WS2.1) must choose a non-path key. ABSENT `observed` is explicitly NOT rejected (legal ⇒ "no prior witness" ⇒ flag-on-conflict, the safe direction). No user-message surface exists, so no user input is over-blocked.
+
+---
+
+## 2. Under-block
+
+The validator does NOT semantically validate store-specific fields beyond delegating to the supplied `StoreFieldSchema` — a store that supplies a permissive schema could let through store data the envelope can't reason about. This is by design (parameterizable substrate; the store owns its field discipline) — BUT the envelope's own LOAD-BEARING fields are now protected against a buggy/hostile store by construction (post-adversarial-review hardening, findings #1–#3):
+- **A store can NEVER override a reserved envelope field on `data`.** `validateReplicatedEnvelope` strips every `RESERVED_ENVELOPE_FIELDS` key (`op`/`recordKey`/`hlc`/`origin`/`observed`) from the store's returned object (counting each as a dropped field) and spreads the store fields FIRST, the VALIDATED envelope fields LAST — so `data.op/recordKey/hlc/origin/observed` always equal the validated `envelope.*`. The earlier `...storeFields`-last ordering let a store's un-validated, un-jailed copy win on a key collision; that divergence is closed (finding #1).
+- **A schema cannot claim a reserved field name.** `ReplicatedKindRegistry.register()` throws (a wiring-time programmer error, like the conflict throws) if `knownFields` intersects `RESERVED_ENVELOPE_FIELDS` — the reserved constant is now ENFORCED, not merely documented for self-check (finding #2).
+- **Reusable store-field path-jail.** The §4 path-jail is now reusable machinery for store fields too: a store declares `pathSensitiveFields` (auto-jailed by the validator before its `validate()`, rejecting the whole record with `store-field-path-shaped` + a jail-counter bump) and/or calls the exported `jailStoreStringField(value, ctx)` helper, which feeds the SAME `jailRejects` counter via the new `StoreValidateContext.countJailReject` (finding #3). Structure > Willpower instead of every store re-implementing (and possibly forgetting) the jail.
+
+The emission gate's flag-coherence check trusts the peer's advert: a peer that advertises `stateSyncReceive[store]=true` but is actually unable to apply the kind would still be sent to. This is the same trust model as the existing `ws11DeliverReceive`/`ws12DrainReceive` adverts — the advert is self-reported from machinery presence, and a lying peer is out of scope for this foundation (the applier's per-record validation at the RECEIVE door is the backstop). The validator never throws on bad data (it counts + rejects); a thrown error is reserved for a programmer error (a registration conflict OR a reserved-field knownFields collision), which is the correct loud-fail.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Correct layer. This is a low-level, deterministic PRIMITIVE (a validator + a registry + pure decision functions) with no reasoning and no context — exactly right for a substrate that runs on every replicated record. It does NOT hold smart-gate authority; it produces typed verdicts (`EnvelopeValidationResult`, `shouldEmitToPeer` decision, `PoolFlagCoherenceResult`) that the eventual consumers (the concrete stores, the apply path) act on. It USES the existing lower-level primitive (`HybridLogicalClock.coerceHlc` for HLC validation) rather than re-implementing HLC parsing, and it MIRRORS — does not duplicate — the CoherenceJournal typed-schema discipline (the journal's own `validate()`/jail stays the authority for the existing kinds; this is the parallel discipline for the generic replicated envelope a concrete store will register).
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface **over a user action**.
+
+The two refusal surfaces (validator at the RECEIVE door, emission gate at the EMISSION door) are mechanism: they protect DATA integrity and prevent the named silent-drop skew mode. Neither blocks, delays, or rewrites a user-initiated action — there is no user-message path through this code at all. The validator's logic is deterministic-but-NOT-brittle-with-authority-over-a-user: it is a structural schema check (the same class as the existing journal typed-schema validation, which is the accepted pattern), and its "authority" is only over whether a malformed REPLICATED RECORD enters a stream. The emission gate is a conservative "don't forward what the peer can't receive" — withholding traffic, the safe direction. No brittle detector owns block authority over anything a user does.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** none. The new validator runs on the replicated-record envelope path, which does not yet exist on disk (the registry is empty); no concrete kind is emitted, so it shadows no existing check. The startup `assertStateSyncInvariants` runs alongside `assertSeamlessnessInvariants` (independent config sub-trees) — neither shadows the other.
+- **PULL transport + dual-registry coupling (adversarial finding #4).** The real journal-sync transport is RECEIVER-DRIVEN PULL (`PeerPresencePuller.driveJournalDelta` iterates the SENDER's advert from `CoherenceJournal.getOwnAdvert()`, which enumerates the static `JOURNAL_KINDS`; serve + apply both gate on `JOURNAL_KINDS`). There is NO push-forward step, so `shouldEmitToPeer` is intentionally UNWIRED in Step 2 (no concrete kind to serve; it is the pure per-peer decision the WS2.1 serve/pull chokepoint will consult). The named "emit a new kind to an OLD peer → silently dropped" mode manifests on this PULL transport as "an old peer never PULLS a kind absent from its own JOURNAL_KINDS." CRITICAL COUPLING for the consumer PRs: a replicated kind MUST be added to BOTH `ReplicatedKindRegistry` (read by the gate + the `stateSyncReceive` advert) AND the static `JOURNAL_KINDS` (gates serve + apply, enumerated by `getOwnAdvert`) — registering into only the former yields a store that advertises receive=true yet serves/applies/pulls nothing (a silent no-replication). A wiring-integrity ratchet (`tests/unit/ReplicatedRecordEnvelope.test.ts`) asserts every registered replicated kind is present in `JOURNAL_KINDS`. Documented in spec §4 + the `ReplicatedRecordEnvelope.ts` module header.
+- **Double-fire:** the boot-time coherence check is guarded (`stateSyncCoherenceSurfaced` one-shot) so a mixed-flag pool surfaces ONCE, not per-tick — explicitly the anti-double-fire design (§4 "surfaces ONCE, coalesced"). With an empty registry it never fires at all.
+- **Races:** the registry is constructed once at boot and (in Step 2) never mutated after; the advert self-report reads config + the registry's store list (immutable in this step). No shared mutable state with concurrent code. The validator + decision functions are pure (no shared state).
+- **Feedback loops:** none — the coherence check is observe-only (logs a line); it never auto-enables/disables a store or changes the advert.
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** none — no new shared files, no new routes.
+- **Other users of the install base:** the capacity heartbeat now carries an additional `seamlessnessFlags.stateSyncReceive` field (`{}` until a store is registered+enabled). Older peers that don't know the field ignore it (forward-compat); newer peers read it. Additive, bounded, no breakage.
+- **External systems:** none.
+- **Persistent state:** config gains a `multiMachine.stateSync` block (foundation knobs only, no `enabled` key) via the existing `applyDefaults`/`migrateConfig` add-missing path — no new on-disk stream, no DB, no ledger. The replicated-record streams themselves land with WS2.1.
+- **Timing/runtime:** the boot coherence check timer (60s, unref'd) is inert while the registry is empty.
+- **Operator surface (Mobile-Complete Operator Actions):** no operator-facing actions — this is internal substrate with no PIN-gated or approval-class route. N/A.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Posture: replicated (journal-kind emission + flag-coherence-gated).** This IS the replication machinery — its entire purpose is to let a store's state follow the agent across machines via flag-gated, flag-coherence-gated journal-kind emission on top of the coherence-journal replication path (the same first-hop replication the existing kinds use). The named replication path is: a concrete store (WS2.1) registers a kind onto `ReplicatedKindRegistry`, the per-record envelope rides the coherence journal's existing serve/apply transport, and emission is gated per-peer on the `seamlessnessFlags.stateSyncReceive` advert so a kind is NEVER forwarded to a peer that would silently drop it (the named data-loss skew mode this step exists to prevent).
+
+- **User-facing notices:** the boot coherence check logs ONE coalesced line to the server log on a mixed-flag pool; it emits no user-facing Telegram notice (a richer surface is the store PR's to add). No one-voice gating needed.
+- **Durable state on topic transfer:** Step 2 holds no per-topic durable state (the registry is in-memory, config is per-machine). No strand-on-transfer risk.
+- **URLs across machine boundaries:** none generated.
+- **Single-machine:** strict no-op — emission is gated on a peer advertising the matching flag, so with no peers nothing is ever emitted; the registry is empty regardless.
+
+---
+
+## 8. Rollback cost
+
+- **Hot-fix release:** pure code change — revert the two new modules + the types/config/server additions and ship as the next patch. No persistent state to undo.
+- **Data migration:** none. The `multiMachine.stateSync` config block is add-missing and inert (no per-store `enabled` key shipped); leaving it on an agent after a code revert is harmless (the consuming code is gone). No new on-disk stream is created in this step.
+- **Agent state repair:** none — no agent needs notifying or resetting; the advert field simply stops being emitted after a revert (peers tolerate its absence).
+- **User visibility:** none — the feature is dark with no user-facing surface; a rollback is invisible to users.
+
+---
+
+## Conclusion
+
+This review produced no design changes — the change is, by construction, pure dark-by-default mechanism with its only two refusal surfaces at the receive door (malformed-data rejection) and the emission door (don't forward to a non-advertising peer), neither of which touches a user action. The N-peer correctness of the flag-coherence check and the coalesced single-surface design were verified by unit tests (3+-peer mixed cases). The line-map golden test was recomputed by hand for the +17 cartographer shift the `stateSync` config block introduced. The change is clear to ship as the substrate WS2.1 will register a concrete kind onto.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/ReplicatedRecordEnvelope.test.ts` (46 tests) — validator both-sides, registry, flag-gated + flag-coherence (incl. 3+-peer mix), config invariants, wiring-integrity advert.
+- Gate-parity (run in the worktree): `npx tsc --noEmit` clean; `no-silent-fallbacks` = 471 (= BASELINE, no bump, my files absent from the flagged list); `docs-coverage --check` PASS (class 55%); `feature-delivery-completeness` PASS (no new CLAUDE.md section); `lint-dev-agent-dark-gate` PASS (line-map updated); focused suites `CoherenceJournal*` / `JournalSyncApplier*` / new test all green.

package/upgrades/side-effects/operator-surface-quality-and-mandates-redesign.md

@@ -0,0 +1,200 @@
+# Side-Effects Review — Operator-Surface Quality standard + Mandates-tab redesign
+
+**Version / slug:** `operator-surface-quality-and-mandates-redesign`
+**Date:** `2026-06-12`
+**Author:** `Echo (instar dev agent)`
+**Second-pass reviewer:** `not required (Tier 1)`
+
+## Summary of the change
+
+Two cohesive changes from one operator finding (2026-06-12, topic 22367, CMT-1434):
+the freshly-shipped Mandates grant form was mobile-*reachable* (per Mobile-Complete
+Operator Actions) yet unusable ("abysmal"). This (A) redesigns the Mandates
+dashboard card to be genuinely good, and (B) lands a new constitutional standard,
+**Operator-Surface Quality**, with a real enforcement gate so reachable-but-bad
+cannot ship again.
+
+Files touched:
+- `dashboard/mandates.js` — renderers: grant form is now the card's primary,
+  always-open block (was wrapped in a collapsed `<details>`); revoke demoted to a
+  quiet collapsed control ordered after grant; JSON bounds / fingerprints / scope
+  slugs replaced by a plain-language summary, with ids kept only on a muted "For
+  support" line; grants list humanized; audit cells carry `data-label` for
+  mobile stacking.
+- `dashboard/index.html` — shortened the explanatory wall to one line + a
+  collapsible "What is this?"; added CSS for the primary grant block, the demoted
+  revoke, the plain summary, and a `@media (max-width:640px)` rule that stacks the
+  audit table so the reason column is never truncated.
+- `docs/STANDARDS-REGISTRY.md` — new "Operator-Surface Quality" article (Interaction
+  family), naming `scripts/instar-dev-precommit.js` as its gate.
+- `skills/instar-dev/templates/side-effects-artifact.md` — new §6b operator-surface
+  quality question.
+- `scripts/instar-dev-precommit.js` + `scripts/lib/operator-surface.mjs` — the gate
+  (`assertOperatorSurfaceQuality`) + its pure decision predicates.
+- Tests: `tests/unit/dashboard-mandateGrantForm.test.ts`,
+  `tests/unit/dashboard-mandatesTab.test.ts`,
+  `tests/unit/standards-enforcement-auditor.test.ts`,
+  `tests/unit/operator-surface-gate.test.ts`.
+
+## Decision-point inventory
+
+- `assertOperatorSurfaceQuality` (scripts/instar-dev-precommit.js) — **add** — a new
+  scoped review gate: when a commit touches an operator surface, the side-effects
+  artifact must answer the operator-surface-quality question or the commit blocks.
+- `isOperatorSurfaceFile` / `artifactAddressesOperatorSurfaceQuality`
+  (scripts/lib/operator-surface.mjs) — **add** — the gate's two pure predicates.
+- Mandates renderers (dashboard/mandates.js) — **modify** — presentation only; no
+  change to the grant/revoke/issue API calls, payloads, or PIN discipline.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The only block/allow surface added is the pre-commit gate. It fires ONLY when a
+staged file matches an operator surface (`dashboard/*.js|html`, or an
+approval/secret-drop/operator-approval form) AND the side-effects artifact lacks
+the operator-surface-quality phrase. A legitimate operator-surface change whose
+review genuinely answers §6b passes. A change touching no operator surface is never
+evaluated. The detector explicitly excludes `*.test.*`/`*.spec.*` siblings so a
+test guarding a surface isn't itself treated as the surface.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+A commit that touches an operator surface but stages NO in-scope file (src/,
+scripts/, .husky/, skill) never reaches the gate at all — the precommit only runs
+its body when an in-scope file is staged. This is the SAME boundary the sibling
+`assertFrameworkGenerality` gate has (it fires only when its src surface is
+touched). A pure dashboard-only commit (dashboard/ is not in-scope) would not be
+gated. Accepted for v1: the dashboard surface is authored by instar-dev work that
+near-always co-stages an in-scope file, and the standard + template question still
+guide the review. Widening the gate's trigger to operator surfaces directly is a
+tracked follow-up, not silently dropped.
+
+The gate also checks for *presence* of the §6b engagement, not the substantive
+quality of the four answers — that judgment stays with the reviewer (Signal vs.
+Authority: the gate signals the question must be present; the mind answers it).
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The gate is a brittle path/text detector that ENFORCES a written answer; it
+holds no semantic judgment about whether the UI is actually good — that is the
+reviewer's call. This is the correct split: the detector ensures the question is
+asked; the full-context mind answers it. It feeds the existing side-effects review
+flow rather than running parallel to it, mirroring `assertFrameworkGenerality`.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** docs/signal-vs-authority.md
+
+- [x] No — this change has no block/allow surface that makes a *semantic* judgment.
+  The gate's only authority is "the operator-surface-quality section must be present
+  in the artifact for an operator-surface change" — a structural presence check, not
+  a content-quality verdict. The quality verdict stays with the human/agent reviewer.
+
+## 5. Interactions
+
+- **Shadowing:** the new gate runs alongside `assertFrameworkGenerality` at both the
+  Tier-1 and Tier-2 pass sites; neither shadows the other (different surfaces,
+  different artifacts checks). Both run before `process.exit(0)`.
+- **Double-fire:** the gate is invoked once per pass path; only one pass path
+  executes per commit (Tier-1 lite exits, Tier-2 falls through). No double-fire.
+- **Races:** none — pure synchronous file reads at commit time.
+- **Feedback loops:** none.
+
+The dashboard renderer changes are pure presentation: the grant/revoke/issue
+controller, fetch calls, payloads, and PIN-never-retained discipline are untouched
+(verified — all existing controller tests pass unchanged).
+
+## 6. External surfaces
+
+- Other agents on the same machine? No.
+- Other users of the install base? Yes — the Mandates dashboard tab is the visible
+  change. It ships via the package's `dashboard/` (served by `express.static`), so
+  it reaches every agent through the normal release → auto-update path. No
+  agent-installed-file rewrite is involved for the dashboard.
+- External systems? No.
+- Persistent state? No.
+- **Operator surface (Mobile-Complete Operator Actions):** the Mandates grant/revoke
+  actions already have a phone-completable surface (this very tab). This change
+  improves that surface; it adds no new API-only operator action.
+
+**Migration parity (the one agent-installed file I touched —
+`skills/instar-dev/templates/side-effects-artifact.md`):** this template is deployed
+into dev-agent homes and is already migrated by
+`migrateMultiMachinePostureReviewDimension`. I deliberately did NOT add a new
+`PostUpdateMigrator` migration, and this is a recorded decision, not a silent skip:
+(1) the BINDING enforcement is the pre-commit gate in `scripts/`, which is
+instar-source-repo tooling run from `.husky` — it is NOT a deployed runtime file and
+works for ALL instar-dev work regardless of any installed template copy; (2) the gate
+is self-teaching — its block message names the exact §6b section to add, so no
+developer is left in a silent-fail state (the Migration Parity standard's actual
+concern: "a feature that only works for new agents"); (3) new agents get §6b via
+`installBuiltinSkills`; existing agents NOT yet on the multi-machine template get it
+automatically because the bundled file the existing migration re-copies now contains
+§6b; only an already-multi-machine dev agent misses the template PROMPT, and the gate
+covers it. Touching `PostUpdateMigrator` (fleet machinery the codebase declares
+"never Tier-1") to ship a convenience prompt to that narrow residual is
+disproportionate. Tracked: CMT-1434.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN.** The change is a stateless dashboard renderer + a
+commit-time repo gate. The dashboard reads pool-wide mandate/audit state from the
+server it is served by (no new per-machine state); the gate runs in whichever
+checkout the developer commits from. It emits no user-facing notices, holds no
+durable state, and generates no URLs — so there is nothing to replicate, proxy, or
+strand on a topic transfer. Framework generality: not applicable — this touches
+neither the session launch/inject abstraction nor messaging delivery.
+
+## 8. Rollback cost
+
+Pure code change. Revert the renderer/markup/CSS and the gate; ship as a patch. No
+persistent state, no data migration, no agent-state repair. During the rollback
+window users would simply see the prior Mandates card again — no functional
+regression (the underlying mandate API is unchanged throughout).
+
+## Conclusion
+
+The review produced one design refinement: extracting the gate's decision logic into
+a pure, unit-tested lib (`scripts/lib/operator-surface.mjs`) rather than inlining
+regexes in the precommit, so both sides of each boundary are pinned by tests and the
+gate's wiring is verifiable. The recorded migration-parity decision (no new
+`PostUpdateMigrator` migration, with explicit reasoning) is the one item flagged for
+the operator's awareness. Clear to ship as a Tier-1 change.
+
+## Operator-surface quality (Operator-Surface Quality standard) — §6b self-review
+
+This change IS an operator surface (`dashboard/mandates.js`, `dashboard/index.html`),
+so it is held to the standard it introduces:
+
+1. **Leads with the primary action?** Yes. The Grant form renders as an open,
+   titled `mnd-grant-block` — never inside a collapsed `<details>`. On a mandate
+   with no grants it is the visible call to action.
+2. **Zero raw internals as primary content?** Yes. The card headline is a
+   de-slugified scope title; the body is a plain-language summary. No JSON bounds,
+   no fingerprints, no slugs as primary content (asserted: the card body contains no
+   `{"` substring and no raw bounds keys). Ids/fingerprints/slugs survive only on a
+   muted "For support" line.
+3. **Destructive actions de-emphasized?** Yes. Revoke is a quiet, collapsed
+   `mnd-revoke-details` ordered AFTER the Grant block in the DOM; the danger button
+   is no longer bold/featured (asserted: grant index < revoke index).
+4. **Plain language + phone width?** Yes. Grants read "Adam Admin can deploy to
+   production until … — authorized by you"; action slugs are humanized; the audit
+   table stacks into labelled rows at ≤640px so the reason column is never
+   truncated.
+
+## Evidence pointers
+
+- `tests/unit/dashboard-mandateGrantForm.test.ts` — grant form NOT in collapsed
+  `<details>`; no `{"` JSON in card body; revoke ordered after grant; humanized
+  grants; mobile audit labels.
+- `tests/unit/operator-surface-gate.test.ts` — both predicates (both sides of each
+  boundary) + wiring-integrity (the gate is called on both pass paths, not a no-op).
+- `tests/unit/standards-enforcement-auditor.test.ts` — the new standard classifies as
+  `gate` with zero dangling refs over the real registry.