instar 1.3.519 → 1.3.520

package/dashboard/index.html

@@ -815,18 +815,34 @@
     .mnd-bad { color: #f85149; border-color: #f8514955; font-weight: 700; }
     .mnd-deny { color: #d29922; border-color: #d2992255; }
     .mnd-dead { color: var(--text-dim); }
-    .mnd-meta { font-size: 13px; color: var(--text-dim); }
-    .mnd-authorities { margin: 0; padding-left: 18px; font-size: 13px; line-height: 1.7; }
+    /* Internals (id, fingerprints, scope slug, action slugs) are SUPPORT
+       metadata only — de-emphasized, never the headline (Operator-Surface
+       Quality item 2). */
+    .mnd-meta { font-size: 12px; color: var(--text-dim); }
+    /* The card's plain-language headline sentence — the primary content. */
+    .mnd-summary { margin: 0; font-size: 15px; line-height: 1.5; color: var(--text-bright); }
     .mnd-empty { font-size: 16px; color: var(--text-dim); line-height: 1.6; padding: 12px 0; }
-    .mnd-revoke-row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
+    .mnd-revoke-row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin: 8px 0 4px; }
     .mnd-pin { width: 110px; } .mnd-reason { flex: 1; min-width: 160px; }
     .mnd-btn { padding: 6px 14px; cursor: pointer; }
-    .mnd-btn-danger { color: #f85149; }
+    .mnd-btn-primary { font-weight: 600; }
+    /* Destructive action: quiet by design, never featured (item 3). */
+    .mnd-btn-danger { color: #f85149; font-weight: 400; }
     .mnd-dead-note { font-size: 13px; color: var(--text-dim); font-style: italic; }
     .mnd-grants-head { font-size: 13px; color: var(--text-dim); }
-    .mnd-grants { margin: 0; padding-left: 18px; font-size: 13px; line-height: 1.7; }
-    .mnd-grant-details { font-size: 13px; }
-    .mnd-grant-summary { cursor: pointer; color: var(--text-dim); }
+    .mnd-grants { margin: 0; padding-left: 18px; font-size: 14px; line-height: 1.7; }
+    .mnd-grant-id { color: var(--text-dim); font-size: 12px; }
+    /* The grant form is the card's PRIMARY action — an open, titled block, never
+       a collapsed toggle (Operator-Surface Quality item 1). */
+    .mnd-grant-block { border-top: 1px solid var(--border); padding-top: 10px; margin-top: 2px; }
+    .mnd-grant-title { font-size: 14px; font-weight: 600; color: var(--text-bright); margin-bottom: 6px; }
+    .mnd-grant-sep { font-size: 13px; color: var(--text-dim); }
+    /* Revoke is demoted to a quiet, collapsed secondary control (item 3). */
+    .mnd-revoke-details { font-size: 13px; margin-top: 4px; }
+    .mnd-revoke-summary { cursor: pointer; color: var(--text-dim); font-size: 13px; }
+    .mnd-about { font-size: 14px; color: var(--text-dim); margin-top: -8px; }
+    .mnd-about summary { cursor: pointer; }
+    .mnd-about p { margin: 8px 0 0; line-height: 1.55; }
     .mnd-grant-row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin: 8px 0 4px; }
     .mnd-grant-field { min-width: 130px; max-width: 100%; padding: 6px 8px; }
     .mnd-notice { min-height: 20px; font-size: 14px; color: #3fb950; }
@@ -842,9 +858,19 @@
     .mnd-notice-ok { border: 1px solid #15803d; background: rgba(21, 128, 61, 0.12); color: #86efac; padding: 12px 14px; border-radius: 8px; font-size: 17px; font-weight: 600; line-height: 1.5; }
     .mnd-table { width: 100%; border-collapse: collapse; font-size: 13px; }
     .mnd-table th, .mnd-table td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--border); vertical-align: top; }
-    .mnd-reason-cell { color: var(--text-dim); max-width: 420px; }
-    .mnd-audit-head { display: flex; gap: 12px; align-items: center; margin-bottom: 8px; }
+    .mnd-reason-cell { color: var(--text-dim); }
+    .mnd-audit-head { display: flex; gap: 12px; align-items: center; margin-bottom: 8px; flex-wrap: wrap; }
     .mnd-dim { font-size: 13px; color: var(--text-dim); }
+    /* Mobile-first (item 5): at phone width the 5-column audit table stacks into
+       labelled rows so the reason — the useful column — is never truncated. */
+    @media (max-width: 640px) {
+      .mnd-table thead { position: absolute; left: -9999px; }
+      .mnd-table tr { display: block; border: 1px solid var(--border); border-radius: 8px; margin-bottom: 10px; padding: 6px 4px; }
+      .mnd-table td { display: flex; justify-content: space-between; gap: 12px; border-bottom: none; padding: 4px 8px; }
+      .mnd-table td::before { content: attr(data-label); font-weight: 600; color: var(--text-dim); flex: 0 0 auto; }
+      .mnd-reason-cell { text-align: right; word-break: break-word; }
+      .mnd-grant-field, .mnd-pin, .mnd-reason { width: 100%; min-width: 0; flex: 1 1 100%; }
+    }
 
     /* ── process-health tab (PROCESS-HEALTH-DASHBOARD-TAB-SPEC §4.1) ──
        Large, readable, calm. No monospace, no tables, no alarm colors.
@@ -3384,7 +3410,11 @@
         <h2 class="ph-title">Coordination Mandates</h2>
         <div id="mndStamp" class="ph-stamp" aria-live="polite"></div>
       </div>
-      <p class="ph-intro">Your bounded "permission slips" for autonomous agent-to-agent work. The slip — never the agent — is the authorizer. Issuing and revoking require <strong>your dashboard PIN</strong>; agent credentials alone are refused by design. With no slip issued, every delegated action is denied.</p>
+      <p class="ph-intro">Permission slips you sign with your PIN to let your agents do bounded work together.</p>
+      <details class="mnd-about">
+        <summary>What is this?</summary>
+        <p>These are your permission slips for autonomous agent-to-agent work — each one authorizes a specific, bounded task. The slip — never the agent — is the authorizer. Issuing and revoking require <strong>your dashboard PIN</strong>; an agent's own credentials are refused by design. With no slip issued, every delegated action is denied.</p>
+      </details>
       <div id="mndNotice" class="mnd-notice" aria-live="polite"></div>
       <section class="ph-section">
         <h3 class="ph-h">Issued mandates</h3>

package/dashboard/mandates.js

@@ -61,12 +61,72 @@ function fmtWhen(iso) {
   } catch { return String(iso); }
 }
 
-function userLabel(slackUserId, slackUsers) {
+/** The registry name for a Slack id, or the id itself when we don't know them. */
+function userName(slackUserId, slackUsers) {
   const u = (slackUsers || []).find((x) => x.slackUserId === slackUserId);
-  return u ? `${u.name} (${slackUserId})` : slackUserId;
+  return u ? u.name : slackUserId;
 }
 
-/** The grants a mandate already carries, in operator language. */
+// Operator-Surface Quality (constitution): the card speaks plain language, never
+// the slugs/JSON the data model stores. These maps turn the stored enum/bounds
+// into the sentence a non-engineer would say. Unknown values fall back to a
+// de-slugified phrase — never a raw token dumped at the operator.
+
+// Both the coordination-mandate authority actions AND the RolePolicy floor
+// actions, in plain language. Returns the RAW human string; callers esc() it.
+const ACTION_PHRASES = {
+  'exchange-read-credential': 'exchange a read-only credential',
+  'sign-code-review': 'co-sign a code review',
+  'money-movement': 'move money',
+  'prod-deploy': 'deploy to production',
+  'credential-access': 'use a credential',
+  'destructive-data': 'run a destructive data operation',
+  'external-send': 'send something externally',
+  'grant-authority': 'grant authority to others',
+};
+function humanAction(slug) {
+  const s = String(slug ?? '');
+  return ACTION_PHRASES[s] || s.replace(/-/g, ' ');
+}
+
+/** "you" when the authorizer is the operator-via-PIN; otherwise the raw name. */
+function humanAuthorizer(authorizedBy) {
+  const s = String(authorizedBy ?? '');
+  return /operator|dashboard pin/i.test(s) ? 'you' : s;
+}
+
+/** A short title from the operator's scope name (de-slugified, not the raw slug). */
+function humanScope(scope) {
+  const s = String(scope ?? '').trim();
+  if (!s) return 'Permission slip';
+  const words = s.replace(/[-_]+/g, ' ');
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+/** Join phrases the way a person speaks them: "a, b and c". */
+function joinHuman(parts) {
+  if (parts.length === 0) return '';
+  if (parts.length === 1) return parts[0];
+  return parts.slice(0, -1).join(', ') + ' and ' + parts[parts.length - 1];
+}
+
+/**
+ * One plain sentence describing what the mandate authorizes + when it ends —
+ * the card's primary, human-language headline (no slugs, no JSON, no
+ * fingerprints). Each interpolated action is escaped at the call site.
+ */
+function humanSummary(m) {
+  const acts = (m.authorities || []).map((a) => esc(humanAction(a.action)));
+  const agents = (m.agents || []).filter(Boolean);
+  const who = agents.length >= 2 ? 'two agents' : 'an agent';
+  const when = fmtWhen(m.expiresAt);
+  if (acts.length === 0) {
+    return `A permission slip for ${who} that delegates no actions yet. Expires ${when}.`;
+  }
+  return `Lets ${who} ${joinHuman(acts)}. Expires ${when}.`;
+}
+
+/** The grants a mandate already carries, in plain operator language. */
 export function renderGrants(m, slackUsers) {
   const grants = Array.isArray(m.grants) ? m.grants : [];
   if (grants.length === 0) return '';
@@ -75,16 +135,22 @@ export function renderGrants(m, slackUsers) {
     const badge = expired
       ? '<span class="mnd-badge mnd-dead">expired</span>'
       : '<span class="mnd-badge mnd-ok">active</span>';
-    return `<li>${badge} <strong>${esc(userLabel(g.grantedTo, slackUsers))}</strong> may <code>${esc(g.floorAction)}</code> until ${fmtWhen(g.expiresAt)} — authorized by ${esc(g.authorizedBy)}</li>`;
+    const name = userName(g.grantedTo, slackUsers);
+    // The Slack id is support metadata, never the headline — shown muted only
+    // when it differs from the name we render (an unknown id IS the name).
+    const idDetail = name !== g.grantedTo ? ` <span class="mnd-grant-id">(${esc(g.grantedTo)})</span>` : '';
+    return `<li>${badge} <strong>${esc(name)}</strong>${idDetail} can ${esc(humanAction(g.floorAction))} until ${fmtWhen(g.expiresAt)} — authorized by ${esc(humanAuthorizer(g.authorizedBy))}</li>`;
   }).join('');
-  return `<div class="mnd-grants-head">User grants this mandate carries:</div><ul class="mnd-grants">${rows}</ul>`;
+  return `<div class="mnd-grants-head">Who this slip already lets act:</div><ul class="mnd-grants">${rows}</ul>`;
 }
 
 /**
- * The add-grant form for an ACTIVE mandate. Mobile-first by design (the
- * 2026-06-12 lesson, instar#1080): the operator PICKS a person and a duration —
- * the only thing typed is the PIN. A free-text Slack-id input appears only
- * when the user registry has nobody to offer.
+ * The add-grant form for an ACTIVE mandate — the card's PRIMARY action, always
+ * visible (Operator-Surface Quality: lead with the primary action, never behind
+ * a toggle). Mobile-first (the 2026-06-12 lesson, instar#1080): the operator
+ * PICKS a person and a duration — the only thing typed is the PIN. A free-text
+ * Slack-id input appears only when the user registry has nobody to offer. Action
+ * labels read in plain language; the slug is the option VALUE the server needs.
  */
 export function renderGrantForm(m, slackUsers) {
   const users = (slackUsers || []).filter((u) => u.slackUserId);
@@ -94,21 +160,23 @@ export function renderGrantForm(m, slackUsers) {
       }</select>`
     : `<input type="text" class="mnd-grant-field" data-grant-user="${esc(m.id)}" placeholder="Slack user id (e.g. U0…)" />`;
   const actionField = `<select class="mnd-grant-field" data-grant-action="${esc(m.id)}">${
-    FLOOR_ACTIONS.map((a) => `<option value="${a}"${a === 'prod-deploy' ? ' selected' : ''}>${a}</option>`).join('')
+    FLOOR_ACTIONS.map((a) => `<option value="${a}"${a === 'prod-deploy' ? ' selected' : ''}>${esc(humanAction(a))}</option>`).join('')
   }</select>`;
   const durationField = `<select class="mnd-grant-field" data-grant-duration="${esc(m.id)}">${
     GRANT_DURATIONS.map((d) => `<option value="${d.minutes}"${d.minutes === 60 ? ' selected' : ''}>${d.label}</option>`).join('')
   }</select>`;
-  return `<details class="mnd-grant-details"><summary class="mnd-grant-summary">Grant a user a floor action (PIN required)</summary>
+  return `<div class="mnd-grant-block">
+    <div class="mnd-grant-title">Grant a person an action</div>
     <div class="mnd-grant-row">
       ${granteeField}
       ${actionField}
+      <span class="mnd-grant-sep">for</span>
       ${durationField}
-      <input type="password" class="mnd-pin" data-grant-pin="${esc(m.id)}" placeholder="PIN" autocomplete="off" />
-      <button class="mnd-btn" data-grant="${esc(m.id)}">Grant</button>
+      <input type="password" class="mnd-pin" data-grant-pin="${esc(m.id)}" placeholder="Your PIN" autocomplete="off" />
+      <button class="mnd-btn mnd-btn-primary" data-grant="${esc(m.id)}">Grant</button>
     </div>
-    <span class="mnd-hint">Lifts the picked person to ONE floor action for the picked window. Signed into this mandate by your PIN — revoking the mandate voids it; it can never outlive the mandate.</span>
-  </details>`;
+    <span class="mnd-hint">Lets the person you pick take that one action for the window you choose. Confirmed with your PIN — never stored. A grant can never outlive this slip, and revoking the slip ends it.</span>
+  </div>`;
 }
 
 export function renderMandates(list, slackUsers = []) {
@@ -119,30 +187,39 @@ export function renderMandates(list, slackUsers = []) {
     const expired = Date.parse(m.expiresAt) < Date.now();
     const state = m.revoked ? 'revoked' : expired ? 'expired' : 'active';
     const stateCls = state === 'active' ? 'mnd-ok' : 'mnd-dead';
+    const stateLabel = state === 'active' ? 'active' : state === 'revoked' ? 'revoked' : 'expired';
     const authBadge = m.authorshipValid
       ? '<span class="mnd-badge mnd-ok">authorship verified</span>'
       : '<span class="mnd-badge mnd-bad">AUTHORSHIP INVALID</span>';
-    const authorities = (m.authorities || []).map((a) =>
-      `<li><code>${esc(a.action)}</code> — bounds <code>${esc(JSON.stringify(a.bounds))}</code>${a.requiresCondition ? ` — requires <code>${esc(a.requiresCondition)}</code>` : ''}</li>`,
-    ).join('');
-    const revokeUi = state === 'active'
-      ? `<div class="mnd-revoke-row">
-           <input type="password" class="mnd-pin" data-revoke-pin="${esc(m.id)}" placeholder="PIN" autocomplete="off" />
-           <input type="text" class="mnd-reason" data-revoke-reason="${esc(m.id)}" placeholder="reason" />
-           <button class="mnd-btn mnd-btn-danger" data-revoke="${esc(m.id)}">Revoke</button>
-         </div>`
-      : `<div class="mnd-dead-note">${m.revoked ? `revoked ${fmtWhen(m.revoked.at)} — ${esc(m.revoked.reason)}` : `expired ${fmtWhen(m.expiresAt)}`}</div>`;
+    // Internals (id, agent fingerprints, scope slug, raw action names, bounds)
+    // are SUPPORT metadata, never the headline — kept on one muted line so the
+    // operator can quote an id when asking for help, but never has to read JSON.
+    const actionSlugs = (m.authorities || []).map((a) => esc(a.action)).filter(Boolean).join(', ') || 'none';
+    const referenceLine = `<div class="mnd-meta">For support: id <code>${esc(m.id)}</code> · agents <code>${esc(shortFp(m.agents?.[0]))}</code> + <code>${esc(shortFp(m.agents?.[1]))}</code> · scope <code>${esc(m.scope)}</code> · authorizes ${actionSlugs} · issued by ${esc(m.author)}</div>`;
+    // The grant form is the PRIMARY action and renders ABOVE revoke. Revoke is
+    // destructive, so it is demoted to a quiet collapsed control, never featured.
     const grantUi = state === 'active' ? renderGrantForm(m, slackUsers) : '';
+    const revokeUi = state === 'active'
+      ? `<details class="mnd-revoke-details">
+           <summary class="mnd-revoke-summary">Revoke this permission slip</summary>
+           <div class="mnd-revoke-row">
+             <input type="password" class="mnd-pin" data-revoke-pin="${esc(m.id)}" placeholder="Your PIN" autocomplete="off" />
+             <input type="text" class="mnd-reason" data-revoke-reason="${esc(m.id)}" placeholder="reason (optional)" />
+             <button class="mnd-btn mnd-btn-danger" data-revoke="${esc(m.id)}">Revoke</button>
+           </div>
+           <span class="mnd-hint">Ends the slip and everything it authorized, right away. This cannot be undone.</span>
+         </details>`
+      : `<div class="mnd-dead-note">${m.revoked ? `Revoked ${fmtWhen(m.revoked.at)} — ${esc(m.revoked.reason)}` : `Expired ${fmtWhen(m.expiresAt)}`}</div>`;
     return `<div class="mnd-card">
       <div class="mnd-card-head">
-        <span class="mnd-scope">${esc(m.scope)}</span>
-        <span class="mnd-badge ${stateCls}">${state}</span>
+        <span class="mnd-scope">${esc(humanScope(m.scope))}</span>
+        <span class="mnd-badge ${stateCls}">${stateLabel}</span>
         ${authBadge}
       </div>
-      <div class="mnd-meta">id <code>${esc(m.id)}</code> · agents <code>${esc(shortFp(m.agents?.[0]))}</code> + <code>${esc(shortFp(m.agents?.[1]))}</code> · by ${esc(m.author)} · expires ${fmtWhen(m.expiresAt)}</div>
-      <ul class="mnd-authorities">${authorities}</ul>
+      <p class="mnd-summary">${humanSummary(m)}</p>
       ${renderGrants(m, slackUsers)}
       ${grantUi}
+      ${referenceLine}
       ${revokeUi}
     </div>`;
   }).join('');
@@ -157,13 +234,17 @@ export function renderAudit(payload) {
   if (entries.length === 0) {
     return `<div class="mnd-audit-head">${chainBadge}</div><div class="mnd-empty">No decisions recorded yet.</div>`;
   }
+  // Mobile-first (Operator-Surface Quality item 5): each cell carries a
+  // data-label so the table can stack into labelled rows at phone width (the
+  // CSS media query in index.html), instead of cramming five columns and
+  // truncating the most useful one — the reason — into an unreadable sliver.
   const rows = entries.slice(-25).reverse().map((e) =>
     `<tr>
-      <td>${fmtWhen(e.ts)}</td>
-      <td><span class="mnd-badge ${e.decision === 'allow' ? 'mnd-ok' : 'mnd-deny'}">${esc(e.decision)}</span></td>
-      <td><code>${esc(e.action)}</code></td>
-      <td><code>${esc(shortFp(e.agentFp))}</code></td>
-      <td class="mnd-reason-cell">${esc(e.reason)}</td>
+      <td data-label="When">${fmtWhen(e.ts)}</td>
+      <td data-label="Decision"><span class="mnd-badge ${e.decision === 'allow' ? 'mnd-ok' : 'mnd-deny'}">${esc(e.decision)}</span></td>
+      <td data-label="Action"><code>${esc(e.action)}</code></td>
+      <td data-label="Agent"><code>${esc(shortFp(e.agentFp))}</code></td>
+      <td data-label="Reason" class="mnd-reason-cell">${esc(e.reason)}</td>
     </tr>`,
   ).join('');
   return `<div class="mnd-audit-head">${chainBadge}<span class="mnd-dim">${entries.length} total decisions · newest first</span></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.519",
+  "version": "1.3.520",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

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:21:46.780Z",
+  "instarVersion": "1.3.520",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.520.md

@@ -0,0 +1,50 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+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
+
+- **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
+
+| 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 |

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.