instar 1.3.44 → 1.3.45

package/dashboard/index.html

@@ -795,24 +795,74 @@
     .ph-headline { font-size: 26px; font-weight: 600; line-height: 1.5; color: var(--text-bright); }
     .ph-subline { font-size: 18px; color: var(--text-dim); margin-top: 8px; line-height: 1.55; }
     .ph-section { display: flex; flex-direction: column; gap: 10px; }
-    .ph-h { font-size: 20px; font-weight: 600; color: var(--text-bright); line-height: 1.5; }
+    .ph-h { font-size: 20px; font-weight: 600; color: var(--text-bright); line-height: 1.5; margin: 0; }
+    .ph-h-sub { font-size: 15px; color: var(--text-dim); line-height: 1.55; margin: 4px 0 4px 0; max-width: 720px; }
     .ph-empty { font-size: 18px; color: var(--text-dim); line-height: 1.6; }
-    .ph-card {
-      padding: 14px 16px; border: 1px solid var(--border); border-radius: 10px;
-      display: flex; flex-direction: column; gap: 6px;
+    /* Page intro — one-sentence grounding right under the title so terms like
+       "it" / "the system" later in the page have a clear referent. */
+    .ph-intro { font-size: 17px; color: var(--text); line-height: 1.55; margin: 0; max-width: 720px; }
+    /* Status color tokens — calm, never alarming. The dot is a scan-aid:
+       glance the collapsed list, see which problems are still being worked
+       on (amber), cause known (blue), or worked out (green). */
+    .ph-status-dot {
+      display: inline-block; width: 10px; height: 10px; border-radius: 50%;
+      flex-shrink: 0; margin-top: 8px; background: var(--text-dim);
+    }
+    .ph-status-dot.status-open      { background: #f59e0b; } /* amber: still looking */
+    .ph-status-dot.status-attributed{ background: #60a5fa; } /* soft blue: cause known */
+    .ph-status-dot.status-verified  { background: var(--ph-accent); }
+    .ph-status-dot.status-resolved  { background: var(--ph-accent); }
+    .ph-status-dot.status-closed    { background: #6b7280; } /* muted gray */
+    /* Labeled rows inside the expanded body — scaffolding, not paragraphs. */
+    .ph-label { font-weight: 600; color: var(--text); margin-right: 4px; }
+    .ph-value { color: var(--text-dim); }
+    /* Expandable items (captured problems + pattern cards): summary always
+       visible, body revealed on tap. Plain ELI16 inside both. */
+    .ph-item {
+      border: 1px solid var(--border); border-radius: 10px; padding: 0;
+      background: transparent;
     }
+    .ph-item + .ph-item { margin-top: 10px; }
+    .ph-item-summary {
+      padding: 14px 44px 14px 16px; font-size: 18px; color: var(--text); line-height: 1.6;
+      cursor: pointer; list-style: none; position: relative;
+      display: flex; flex-direction: row; align-items: flex-start; gap: 12px;
+    }
+    .ph-item-text { flex: 1; display: flex; flex-direction: column; gap: 6px; }
+    .ph-item-summary::-webkit-details-marker { display: none; }
+    /* Subtle chevron on the right edge — signals "tap to expand" without shouting. */
+    .ph-item-summary::after {
+      content: '▾'; position: absolute; right: 16px; top: 16px;
+      color: var(--text-dim); font-size: 16px; opacity: 0.8;
+    }
+    .ph-item[open] > .ph-item-summary::after { content: '▴'; opacity: 1; }
+    .ph-item[open] > .ph-item-summary { color: var(--text-bright); border-bottom: 1px solid var(--border); }
+    .ph-item-body { padding: 14px 16px; display: flex; flex-direction: column; gap: 8px; }
+    .ph-item-row { font-size: 16px; color: var(--text-dim); line-height: 1.55; }
+    .ph-item-row.ph-card-rec { color: var(--text); }
+    .ph-item-inert { opacity: 0.7; }
+    /* Pattern-card-specific lines inside the summary stack. */
     .ph-card-summary { font-size: 18px; color: var(--text-bright); line-height: 1.5; }
     .ph-card-frame { font-size: 15px; color: var(--text-dim); font-style: italic; }
-    .ph-card-rec { font-size: 17px; color: var(--text); line-height: 1.55; }
-    .ph-card-evidence { font-size: 15px; color: var(--text-dim); }
-    .ph-record { font-size: 18px; color: var(--text); line-height: 1.6; padding: 5px 0; }
-    .ph-record-inert { color: var(--text-dim); }
-    .ph-stage { display: flex; align-items: baseline; gap: 10px; font-size: 18px; padding: 3px 0; color: var(--text-dim); line-height: 1.5; }
-    .ph-stage-here { color: var(--text-bright); }
+    /* Maturation track: each stage is also an expandable row. */
+    .ph-stage {
+      padding: 4px 0; line-height: 1.5; color: var(--text-dim);
+    }
+    .ph-stage-summary {
+      display: flex; align-items: baseline; gap: 10px; font-size: 18px;
+      cursor: pointer; list-style: none; padding: 4px 0; position: relative;
+    }
+    .ph-stage-summary::-webkit-details-marker { display: none; }
+    .ph-stage-summary::after {
+      content: '▾'; margin-left: auto; color: var(--text-dim); font-size: 12px; opacity: 0.4;
+    }
+    .ph-stage[open] > .ph-stage-summary::after { content: '▴'; opacity: 0.8; }
+    .ph-stage-here > .ph-stage-summary { color: var(--text-bright); }
     .ph-stage-glyph { color: var(--text-dim); }
     .ph-stage-here .ph-stage-glyph { color: var(--ph-accent); }
     .ph-stage-marker { color: var(--ph-accent); font-size: 15px; }
     .ph-stage-note { color: var(--text-dim); font-size: 15px; }
+    .ph-stage-body { font-size: 16px; color: var(--text-dim); line-height: 1.55; padding: 6px 0 6px 26px; }
     .ph-detail { margin-top: 4px; }
     .ph-detail-summary { font-size: 17px; color: var(--text-dim); cursor: pointer; }
     .ph-detail-body { display: flex; flex-direction: column; gap: 6px; margin-top: 12px; }
@@ -3063,21 +3113,25 @@
         <h2 class="ph-title">Process Health</h2>
         <div id="phStamp" class="ph-stamp" aria-live="polite"></div>
       </div>
+      <p class="ph-intro">A quiet look at what the failure-watching system has spotted in this agent’s recent work — problems it’s caught, any patterns that keep coming up, and how far the system is switched on for this agent.</p>
       <div id="phHeadline" class="ph-headline-wrap" aria-live="polite"></div>
       <section class="ph-section">
-        <h3 class="ph-h">Patterns to know about</h3>
+        <h3 class="ph-h">Recurring patterns</h3>
+        <p class="ph-h-sub">Kinds of problem that have come up more than once across different changes.</p>
         <div id="phPatterns"></div>
       </section>
       <section class="ph-section">
-        <h3 class="ph-h">What’s been captured</h3>
+        <h3 class="ph-h">Problems it’s noticed lately</h3>
+        <p class="ph-h-sub">Individual things the system has caught. When the same kind keeps repeating, it shows up as a pattern above.</p>
         <div id="phCaptured"></div>
       </section>
       <section class="ph-section">
-        <h3 class="ph-h">Maturation</h3>
+        <h3 class="ph-h">How far the system is switched on</h3>
+        <p class="ph-h-sub">Where this agent sits on the rollout — from "off" to "on for everyone by default".</p>
         <div id="phMaturation"></div>
       </section>
       <details class="ph-detail">
-        <summary class="ph-detail-summary">Detail</summary>
+        <summary class="ph-detail-summary">More detail</summary>
         <div id="phDetail" class="ph-detail-body"></div>
       </details>
     </div>

package/dashboard/process-health.js

@@ -116,35 +116,51 @@ export function safeUrl(value) {
 
 // ── Friendly wording (§4.2c) ───────────────────────────────────────────────
 const CATEGORY_WORDS = {
-  concurrency: 'A concurrency issue',
-  'config-parse': 'A config problem',
-  'type-error': 'A type error',
-  'logic-error': 'A logic bug',
-  'test-failure': 'A failing test',
-  'build-failure': 'A build break',
-  'integration-gap': 'An integration gap',
-  regression: 'A regression',
-  'wiring-gap': 'A wiring gap',
-  unknown: 'An issue',
+  concurrency: 'A timing problem (two things ran at once)',
+  'config-parse': 'A settings problem',
+  'type-error': 'A data mix-up (wrong kind of value)',
+  'logic-error': 'A logic mistake',
+  'test-failure': 'A test that failed',
+  'build-failure': 'The build broke',
+  'integration-gap': "Two parts that didn't connect",
+  regression: 'Something that used to work broke',
+  'wiring-gap': "Something that wasn't hooked up",
+  unknown: 'A problem',
 };
 
 export function friendlyCategory(category) {
   const key = typeof category === 'string' ? category : 'unknown';
-  return CATEGORY_WORDS[key] || 'An issue';
+  return CATEGORY_WORDS[key] || 'A problem';
 }
 
+// Short plural nouns for the Detail drawer's per-type counts (plain English, no
+// raw category codes like "config-parse"). Unknown keys fall back to the
+// sanitized raw key (defense-in-depth — these are server-controlled enum values).
+const TYPE_WORDS = {
+  concurrency: 'Timing problems',
+  'config-parse': 'Settings problems',
+  'type-error': 'Data mix-ups',
+  'logic-error': 'Logic mistakes',
+  'test-failure': 'Failing tests',
+  'build-failure': 'Build breaks',
+  'integration-gap': 'Parts that didn’t connect',
+  regression: 'Things that broke again',
+  'wiring-gap': 'Things not hooked up',
+  unknown: 'Other',
+};
+
 // initiativeId → human label. NEVER expose the raw initiativeId (§4.2c). Seeded
 // with the known instar initiatives; unmapped IDs fall back to a generic phrase.
 export const ATTRIBUTION_LABELS = {
-  'failure-learning-loop': 'the failure-learning loop',
-  'process-health-dashboard-tab': 'the process-health tab',
-  'ledger-spine': 'the ledger spine',
-  'threadline-keystone': 'the agent-network keystone',
+  'failure-learning-loop': 'the failure-watching feature',
+  'process-health-dashboard-tab': 'this Process Health page',
+  'ledger-spine': 'the record-keeping feature',
+  'threadline-keystone': 'the agent-to-agent messaging feature',
 };
 
 export function attributionLabel(initiativeId, labelMap = ATTRIBUTION_LABELS) {
   if (typeof initiativeId === 'string' && labelMap[initiativeId]) return labelMap[initiativeId];
-  return 'a tracked feature';
+  return 'a feature we were working on';
 }
 
 export function relativeTime(iso, now = Date.now()) {
@@ -188,16 +204,21 @@ export function renderHeadline(doc, target, { failures, stale, staleAgeMin }) {
   target.replaceChildren();
   if (stale) {
     target.appendChild(
-      el(doc, 'div', 'ph-headline', `Connection paused — showing the last view${staleAgeMin != null ? ` from ${staleAgeMin}m ago` : ''}`),
+      el(doc, 'div', 'ph-headline', `Can't refresh right now — showing the last update${staleAgeMin != null ? ` from ${staleAgeMin} min ago` : ''}`),
     );
-    target.appendChild(el(doc, 'div', 'ph-subline', "Couldn't refresh just now — showing the last good view. Will retry."));
+    target.appendChild(el(doc, 'div', 'ph-subline', "We'll keep trying — nothing is lost."));
     return;
   }
   const list = Array.isArray(failures) ? failures : [];
   const n = list.length;
   const open = list.filter((f) => f && f.status !== 'resolved' && f.status !== 'closed').length;
-  target.appendChild(el(doc, 'div', 'ph-headline', `Watching — ${n} issue${n === 1 ? '' : 's'} recorded so far`));
-  const subline = n === 0 ? 'Nothing recorded yet — capture-only mode' : open === 0 ? 'all linked to a known cause · capture-only mode' : `${open} still being traced · capture-only mode`;
+  const headline = n === 0 ? 'Keeping an eye out — all quiet so far' : `Keeping an eye out — ${n} thing${n === 1 ? '' : 's'} noticed so far`;
+  target.appendChild(el(doc, 'div', 'ph-headline', headline));
+  const subline = n === 0
+    ? "Nothing has come up yet. We're just quietly watching — no alerts."
+    : open === 0
+      ? "We know what caused each one. Just quietly watching — no alerts yet."
+      : `Still looking into ${open} of them. Just quietly watching — no alerts yet.`;
   target.appendChild(el(doc, 'div', 'ph-subline', subline));
 }
 
@@ -214,9 +235,9 @@ export function renderDisabled(doc, els) {
     det.setAttribute('class', 'ph-operator');
     const sum = doc.createElement('summary');
     sum.setAttribute('class', 'ph-operator-summary');
-    sum.textContent = 'for operators';
+    sum.textContent = 'For whoever set this up';
     det.appendChild(sum);
-    det.appendChild(el(doc, 'p', 'ph-operator-hint', 'An operator can enable it by turning the failure-learning monitor on in the agent settings.'));
+    det.appendChild(el(doc, 'p', 'ph-operator-hint', 'You can switch it on in this agent’s settings.'));
     els.headline.appendChild(det);
   }
   for (const k of ['patterns', 'captured', 'maturation', 'detail']) {
@@ -225,38 +246,139 @@ export function renderDisabled(doc, els) {
   if (els.stamp) els.stamp.textContent = '';
 }
 
-/** Patterns cards (§4.2b — awareness-only, NO action authority). */
+/** Insight lifecycle wording — informational only, no action-implying language. */
+const INSIGHT_STATUS_WORDS = {
+  discovered: 'Just noticed',
+  'acted-on': 'Being looked into',
+  verified: 'Confirmed no longer happening',
+  reopened: 'Came back after the previous attempt',
+};
+function friendlyInsightStatus(status) {
+  return INSIGHT_STATUS_WORDS[status] || 'Not set';
+}
+
+/**
+ * Patterns cards (§4.2b — awareness-only, NO action authority). Each card is
+ * an expandable <details> element: the headline summary is visible by default;
+ * the recommendation, evidence breakdown, and lifecycle are revealed on tap.
+ * The renderer-owned "verify before acting" framing stays on the summary so
+ * the no-action-authority signal is never hidden behind a tap.
+ */
 export function renderPatterns(doc, target, insights) {
   if (!target) return;
   target.replaceChildren();
   const list = Array.isArray(insights) ? insights : [];
   if (list.length === 0) {
     target.appendChild(
-      el(doc, 'p', 'ph-empty', 'Nothing flagged yet. The monitor needs to see a wider variety of issues before it surfaces a pattern — that’s expected this early.'),
+      el(doc, 'p', 'ph-empty', 'Nothing to flag yet. We need to see a few more different problems before a real pattern shows up — totally normal this early.'),
     );
     return;
   }
   for (const ins of list) {
-    const card = el(doc, 'div', 'ph-card');
-    card.appendChild(el(doc, 'div', 'ph-card-summary', sanitizeForDisplay(ins && ins.summary, 'summary')));
-    // Renderer-owned framing line (static literal — NOT a data-restateable prefix).
-    card.appendChild(el(doc, 'div', 'ph-card-frame', 'A pattern the monitor noticed — verify before acting.'));
-    if (ins && ins.recommendation) {
-      card.appendChild(el(doc, 'div', 'ph-card-rec', sanitizeForDisplay(ins.recommendation, 'recommendation')));
-    }
+    const card = doc.createElement('details');
+    card.setAttribute('class', 'ph-item ph-card');
+    const sum = doc.createElement('summary');
+    sum.setAttribute('class', 'ph-item-summary');
+    sum.appendChild(statusDot(doc, ins && ins.status));
+    // Just the pattern headline — the section title + subtitle above already
+    // establish "this is a kind of problem that has repeated", so a per-card
+    // restatement would be the third echo of the same idea. The "informational
+    // only, not a prompt to act" signal is structural now (the rendered card
+    // has nothing actionable on it), not chrome.
+    const text = el(doc, 'div', 'ph-item-text');
+    text.appendChild(el(doc, 'div', 'ph-card-summary', sanitizeForDisplay(ins && ins.summary, 'summary')));
+    sum.appendChild(text);
+    card.appendChild(sum);
+    // Body: same fixed label vocabulary as captured items, in the same order.
+    // Status · Times seen · First noticed. (Where/Cause don't apply to a class.)
+    // The recommendation field is intentionally omitted: this tab informs,
+    // doesn't direct — actionable insight is the deferred §10 surface.
+    const body = el(doc, 'div', 'ph-item-body');
+    body.appendChild(labeledRow(doc, 'Status', friendlyInsightStatus(ins && ins.status)));
     const ds = ins && Number.isFinite(ins.distinctSessions) ? ins.distinctSessions : 0;
-    card.appendChild(el(doc, 'div', 'ph-card-evidence', `Seen across ${ds} change${ds === 1 ? '' : 's'}.`));
+    const dc = ins && Number.isFinite(ins.distinctCauseCommits) ? ins.distinctCauseCommits : 0;
+    const timesSeen = dc > 0
+      ? `Across ${ds} different change${ds === 1 ? '' : 's'} (from ${dc} separate fix${dc === 1 ? '' : 'es'})`
+      : `Across ${ds} different change${ds === 1 ? '' : 's'}`;
+    body.appendChild(labeledRow(doc, 'Times seen', timesSeen));
+    if (ins && ins.discoveredAt) {
+      body.appendChild(labeledRow(doc, 'First noticed', relativeTime(ins.discoveredAt)));
+    }
+    card.appendChild(body);
     target.appendChild(card);
   }
 }
 
-/** What's been captured (§4.2c — operator-safe subset only, sentences not rows). */
+/**
+ * Friendly status / cause-confidence wording for the expandable body (§4.2c).
+ * Plain ELI16, no Instar-internal jargon. Unknown values fall back to a generic
+ * phrase — the body never shows raw status/attribution codes.
+ */
+// Terser status values — these pair with a bold "Status:" label in the body
+// (so the value carries the state, the label carries the noun).
+const STATUS_WORDS = {
+  open: 'Still looking into this',
+  attributed: 'We know what caused it',
+  verified: 'Confirmed worked out',
+  resolved: 'Worked out',
+  closed: 'Closed',
+};
+function friendlyStatus(status) {
+  return STATUS_WORDS[status] || 'Not set';
+}
+
+const CAUSE_CONFIDENCE_WORDS = {
+  automatic: 'Auto-spotted from the fix commit — we’re confident',
+  'one-tap': 'Tagged by hand by whoever found it',
+  inferred: 'Best guess from the surrounding context',
+};
+function friendlyCauseConfidence(attribution) {
+  return CAUSE_CONFIDENCE_WORDS[attribution] || 'Not recorded';
+}
+
+/**
+ * Map an upstream status (failure or insight) to a status-dot CSS class.
+ * The dot is a scan-aid only — colors are calm (amber/blue/green/gray),
+ * never alarm reds.
+ */
+export function statusDotClass(status) {
+  switch (status) {
+    case 'open': case 'reopened': case 'discovered': return 'status-open';
+    case 'attributed': case 'acted-on': return 'status-attributed';
+    case 'verified': case 'resolved': return 'status-verified';
+    case 'closed': return 'status-closed';
+    default: return 'status-closed';
+  }
+}
+
+/**
+ * Build a labeled-row inside the expanded body: `<bold-label>:<value>`. Keeps
+ * the structure scannable without paragraph-walls. Both halves are textContent
+ * (the safety contract is unaffected).
+ */
+function labeledRow(doc, label, value) {
+  const row = el(doc, 'div', 'ph-item-row');
+  row.appendChild(el(doc, 'span', 'ph-label', `${label}:`));
+  row.appendChild(doc.createTextNode(' '));
+  row.appendChild(el(doc, 'span', 'ph-value', value));
+  return row;
+}
+
+/** Status-dot span (always at the left edge of an item summary; color-coded by status). */
+function statusDot(doc, status) {
+  const dot = doc.createElement('span');
+  dot.setAttribute('class', `ph-status-dot ${statusDotClass(status)}`);
+  dot.setAttribute('aria-hidden', 'true');
+  return dot;
+}
+
+/** What's been captured (§4.2c — operator-safe subset only, expandable for depth on demand). */
 export function renderCaptured(doc, target, failures, labelMap = ATTRIBUTION_LABELS, now = Date.now()) {
   if (!target) return;
   target.replaceChildren();
   const list = Array.isArray(failures) ? failures.slice(0, 10) : [];
   if (list.length === 0) {
-    target.appendChild(el(doc, 'p', 'ph-empty', 'No issues recorded yet — that just means nothing has come through since this was turned on.'));
+    target.appendChild(el(doc, 'p', 'ph-empty', 'Nothing yet — that just means nothing has come up since this was switched on.'));
     return;
   }
   for (const f of list) {
@@ -265,22 +387,45 @@ export function renderCaptured(doc, target, failures, labelMap = ATTRIBUTION_LAB
     const summary = sanitizeForDisplay(f.summary, 'summary');
     const label = attributionLabel(f.initiativeId, labelMap); // NEVER raw initiativeId
     const when = relativeTime(f.detectedAt, now);
-    // ONE plain-English sentence. Separator + wording are renderer-owned literals.
-    const text = `${cat}: ${summary}${CHROME.sep}attributed to ${label}${CHROME.sep}${when}.`;
-    const row = el(doc, 'p', 'ph-record', text);
-    if (isMixedScript(f.summary)) row.setAttribute('class', 'ph-record ph-record-inert');
-    target.appendChild(row);
+    // The collapsed summary line — one plain-English sentence, as before.
+    const summaryText = `${cat}: ${summary}${CHROME.sep}came up while building ${label}${CHROME.sep}${when}.`;
+    const item = doc.createElement('details');
+    item.setAttribute('class', isMixedScript(f.summary) ? 'ph-item ph-item-inert' : 'ph-item');
+    const sum = doc.createElement('summary');
+    sum.setAttribute('class', 'ph-item-summary');
+    sum.appendChild(statusDot(doc, f.status));
+    sum.appendChild(el(doc, 'div', 'ph-item-text', summaryText));
+    item.appendChild(sum);
+    // Expanded body: a fixed-shape fact sheet. Same labels in the same order
+    // are used by patterns (§4.2b) where applicable — predictable scanning.
+    // Order: Status · Where · Times seen · First noticed · Cause.
+    const body = el(doc, 'div', 'ph-item-body');
+    body.appendChild(labeledRow(doc, 'Status', friendlyStatus(f.status)));
+    if (f.detail && typeof f.detail.redacted === 'string' && f.detail.redacted.trim()) {
+      body.appendChild(labeledRow(doc, 'Where', sanitizeForDisplay(f.detail.redacted, 'detail')));
+    }
+    const occ = Number.isFinite(f.occurrenceCount) ? f.occurrenceCount : 1;
+    body.appendChild(labeledRow(doc, 'Times seen', occ > 1 ? `${occ} times so far` : 'Just once'));
+    body.appendChild(labeledRow(doc, 'First noticed', relativeTime(f.detectedAt, now)));
+    body.appendChild(labeledRow(doc, 'Cause', friendlyCauseConfidence(f.attribution)));
+    item.appendChild(body);
+    target.appendChild(item);
   }
 }
 
 /** Maturation track (§4.2d). 4th stage is permanently-future (no per-agent flag). */
 const STAGES = [
-  { key: 'dark', label: 'Dark' },
-  { key: 'capture-only', label: 'Capture-only' },
-  { key: 'insight-push', label: 'Insight push' },
-  { key: 'default-on', label: 'Default for all agents' },
+  { key: 'dark', label: 'Not switched on yet', description: 'Not switched on for this agent yet — nothing is being recorded.' },
+  { key: 'capture-only', label: 'Quietly watching', description: 'Quietly recording what comes up. No alerts go anywhere — we’re just building up evidence to learn from.' },
+  { key: 'insight-push', label: 'Watching + flagging patterns to you', description: 'Same quiet recording, plus a heads-up when the same kind of problem keeps showing up. Only fires on real patterns, never on one-offs.' },
+  { key: 'default-on', label: 'On for everyone by default', description: 'Switched on for every agent by default — the fully-rolled-out end state.' },
 ];
 
+/**
+ * Maturation track (§4.2d). Each stage is an expandable <details> row so the
+ * label stays glanceable but the meaning is one tap away. The 4th stage is
+ * permanently-future (no per-agent flag).
+ */
 export function renderMaturation(doc, target, rollout) {
   if (!target) return;
   target.replaceChildren();
@@ -290,12 +435,17 @@ export function renderMaturation(doc, target, rollout) {
     const s = STAGES[i];
     const isHere = i === currentIdx;
     const done = currentIdx >= 0 && i < currentIdx;
-    const row = el(doc, 'div', isHere ? 'ph-stage ph-stage-here' : 'ph-stage');
+    const row = doc.createElement('details');
+    row.setAttribute('class', isHere ? 'ph-stage ph-stage-here' : 'ph-stage');
+    const sum = doc.createElement('summary');
+    sum.setAttribute('class', 'ph-stage-summary');
     // glyph + label + marker are ALL renderer-owned static literals
-    row.appendChild(el(doc, 'span', 'ph-stage-glyph', done || isHere ? CHROME.stageDone : CHROME.stageFuture));
-    row.appendChild(el(doc, 'span', 'ph-stage-label', s.label));
-    if (isHere) row.appendChild(el(doc, 'span', 'ph-stage-marker', CHROME.hereMarker));
-    else if (done) row.appendChild(el(doc, 'span', 'ph-stage-note', 'done'));
+    sum.appendChild(el(doc, 'span', 'ph-stage-glyph', done || isHere ? CHROME.stageDone : CHROME.stageFuture));
+    sum.appendChild(el(doc, 'span', 'ph-stage-label', s.label));
+    if (isHere) sum.appendChild(el(doc, 'span', 'ph-stage-marker', CHROME.hereMarker));
+    else if (done) sum.appendChild(el(doc, 'span', 'ph-stage-note', 'done'));
+    row.appendChild(sum);
+    row.appendChild(el(doc, 'div', 'ph-stage-body', s.description));
     target.appendChild(row);
   }
 }
@@ -309,16 +459,17 @@ export function renderDetail(doc, target, analysis) {
     return;
   }
   const add = (label, val) => target.appendChild(el(doc, 'div', 'ph-detail-row', `${label}: ${val}`));
-  add('Total recorded', String(analysis.total ?? 0));
-  add('Linked to a known cause', String(analysis.attributed ?? 0));
-  add('Not yet linked to a feature', String(analysis.noFeatureLink ?? 0));
+  add('Total noticed', String(analysis.total ?? 0));
+  add('Ones we know the cause of', String(analysis.attributed ?? 0));
+  add('Not yet tied to a feature', String(analysis.noFeatureLink ?? 0));
   const byCat = analysis.byCategory && typeof analysis.byCategory === 'object' ? analysis.byCategory : {};
   for (const [k, v] of Object.entries(byCat)) {
-    add(`Category — ${sanitizeForDisplay(k, 'label')}`, String(v));
+    const typeLabel = TYPE_WORDS[k] || sanitizeForDisplay(k, 'label');
+    add(typeLabel, String(v));
   }
   const unknown = analysis.unknownToolchainByAuthor && typeof analysis.unknownToolchainByAuthor === 'object' ? analysis.unknownToolchainByAuthor : {};
   const unknownTotal = Object.values(unknown).reduce((a, b) => a + (Number(b) || 0), 0);
-  add('Records with an unknown toolchain', String(unknownTotal));
+  add("Ones where we're not sure which tools were involved", String(unknownTotal));
 }
 
 // ── Polling controller (§4.3 — visibility-gated, abort-safe, coordinated, diff-aware) ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.44",
+  "version": "1.3.45",
   "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/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-28T01:59:27.143Z",
-  "instarVersion": "1.3.44",
+  "generatedAt": "2026-05-28T02:17:30.185Z",
+  "instarVersion": "1.3.45",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.45.md

@@ -0,0 +1,28 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+UX refinement of the Process Health dashboard tab shipped in v1.3.27. Eight rounds of user-driven copy + structure iteration landed on the design that became the **Dashboard Standard** — the bar all future dashboard features now start from. Pure dashboard-only change (`dashboard/process-health.js` + `dashboard/index.html` + tests); no `src/` / `scripts/` / `.husky/` / `skills/` changes.
+
+What the page looks like now: a one-sentence intro grounds the subject so "it" later in the page has a referent; each section title carries a one-line subtitle that distinguishes it from the others (with explicit cross-references — "When the same kind keeps repeating, it shows up as a pattern above"); each captured problem and pattern card is a `<details>` element with a status color dot on the left (amber/blue/green/gray — never alarm reds) and a chevron on the right; the expanded body is a labeled fact-sheet using a fixed vocabulary (Status / Where / Times seen / First noticed / Cause) used identically across both lists. All action-implying language ("Suggested next step", "verify before acting", "Fix worked") is gone — the page informs, it doesn't direct. Internal codenames (`capture-only`, `failure-learning-loop`, `config-parse`) never reach the DOM; they pass through renderer-owned plain-English maps.
+
+The reference implementation now backs a durable agent memory (`feedback_dashboard_copy_eli16.md`) that codifies the seven rules + eight default substitutions + four status-color tokens so future dashboard work starts from this bar.
+
+## What to Tell Your User
+
+- The Process Health tab on your dashboard reads a lot more clearly now: a calm intro tells you what the page is showing in one sentence, every problem and pattern collapses to one plain line with a small color dot (amber = still being looked into, blue = cause known, green = worked out, gray = closed), and tapping any row opens up the same set of labeled details — Status, Where, Times seen, First noticed, Cause — every time. The bar this set for "what a calm, informative dashboard reads like" is now the standard for everything I build next.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Process Health tab — ELI16 + structure pass | Open the Process Health tab in your dashboard (no action needed; it’s just clearer now) |
+| Dashboard Standard (durable, applies to future dashboard work) | Reference: `feedback_dashboard_copy_eli16.md` (in agent memory) — 7 rules + 8 substitutions + 4 status-color tokens |
+
+## Evidence
+
+- 46 tests green: 30 unit + 12 integration + 4 e2e — includes structural assertions for the unified label order, status-dot CSS classes, and that the dropped framing line is genuinely absent.
+- Safety contract unchanged: XSS negative fixture still fires zero live elements + no canary; `detail.full` redaction is verified end-to-end.
+- Show-don't-tell iteration: eight rounds, each rendered to a real browser and screenshotted for user thumbs-up before committing — no merge-and-iterate churn. The harness pattern is captured in the standard.

package/upgrades/side-effects/process-health-tab-eli16-pass.md

@@ -0,0 +1,49 @@
+# Side-Effects Review — Process Health tab ELI16 + structure pass
+
+**Version / slug:** `process-health-tab-eli16-pass`
+**Date:** 2026-05-27
+**Author:** echo
+**Spec:** `docs/specs/PROCESS-HEALTH-DASHBOARD-TAB-SPEC.md` (v4, the original feature spec; this PR is a UX-refinement follow-up that does NOT change the spec's behavioral surface)
+
+## Summary of the change
+
+Eight rounds of user-driven copy + UX iteration on the Process Health dashboard tab (originally shipped in v1.3.27 via PR #435). Pure dashboard-only refinement — no `src/` / `scripts/` / `.husky/` / `skills/` changes — so this PR is outside the instar-dev gate's in-scope set. The reference implementation now backs a durable agent memory (`feedback_dashboard_copy_eli16.md`) that codifies the **Dashboard Standard** for future dashboard features.
+
+**Files changed (UI):**
+- `dashboard/process-health.js` (renderers): rewritten `CATEGORY_WORDS`, `ATTRIBUTION_LABELS`, `STAGES`, `INSIGHT_STATUS_WORDS`; new `TYPE_WORDS`, `STATUS_WORDS`, `CAUSE_CONFIDENCE_WORDS`, `statusDotClass`, `statusDot`, `labeledRow`. Restructured `renderCaptured` and `renderPatterns` around the fixed label vocabulary + `<details>` expandability + status color dots. `renderMaturation` reshaped per-stage as expandable `<details>` with plain-English descriptions. Dropped the redundant per-card framing line in v7.
+- `dashboard/index.html`: added page-intro paragraph + per-section subtitles that distinguish each section and cross-reference adjacent ones; new CSS for `.ph-intro`, `.ph-h-sub`, `.ph-item`, `.ph-item-summary`, `.ph-item-text`, `.ph-item-body`, `.ph-item-row`, `.ph-label`, `.ph-value`, `.ph-status-dot` (+ 5 status-color variants), `.ph-stage-summary`, `.ph-stage-body`; chevron disclosure indicator on every `<details>` (opacity 0.8).
+
+**Files changed (tests):**
+- `tests/unit/process-health-render.test.ts`: assertions rewritten for new label vocabulary + new status copy + new framing absence + structural assertions on `<details>` + status-dot CSS classes (3 new structural tests added).
+- `tests/integration/process-health-tab.test.ts`: assertions updated for new copy; new framing-absence check.
+- `tests/e2e/process-health-tab-lifecycle.test.ts`: assertions updated for new copy.
+
+**Files changed (release):**
+- `upgrades/NEXT.md` (NEW for this PR, `bump: patch`).
+
+## Decision-point inventory
+
+- **Pure UX refinement vs. functional change?** Pure UX. No new endpoints, no new data fields, no new auth surfaces, no behavioral changes to the polling controller, no changes to the route layer, no changes to migration parity. Only the rendered text + DOM structure changes.
+- **Drop the recommendation field entirely vs. keep + relabel?** Dropped. Justin explicitly directed "avoid language that implies user needs to act unless ABSOLUTELY essential". The recommendation field is upstream prose that is action-implying by content; relabeling chrome around it doesn't change that. Actionable insight delivery is the deferred §10 surface anyway; v1 of the tab is the calm informational surface.
+- **Drop the per-card framing line vs. keep + rephrase?** Dropped in v7. Once "verify before acting" was rephrased to "Same kind of problem has come up more than once" in v5, it became the third echo of the section title + section subtitle. The no-action-authority signal that the framing was originally carrying is now structural (the rendered card has nothing actionable on it), not chrome.
+- **Add status color dots vs. status text only?** Dots. Lets the user scan the collapsed list and read state at a glance without expanding each item. Colors are calm (amber/blue/green/gray) — never alarm reds, per the existing visual rules.
+
+## Side-effects analysis
+
+- **Behavioral:** None. The polling controller, route layer, and migration paths are unchanged. Only the rendered DOM differs.
+- **Architectural:** None. Same file structure; the renderer module is the same self-contained ESM as before. No new build step, no new runtime dependency.
+- **Security:** The safety contract (`sanitizeForDisplay`, textContent-only DOM writes, element ban, safeUrl) is unchanged. New label spans (`.ph-label`, `.ph-value`) use textContent only. The XSS negative fixture continues to fire zero live elements + no canary. The `detail.full` redaction is unchanged.
+- **Migration parity:** Not applicable — no agent-installed-file changes (`templates.ts` / `PostUpdateMigrator` / shadow markers untouched).
+- **Performance:** Marginal increase in DOM nodes per item (each captured item now has 4–5 `<div>`s of body content instead of 0–4 flat children). Diff-aware rendering still works (signature mechanism is structure-agnostic). No new fetches.
+- **Reversibility:** Fully reversible — revert the commit and the previous render returns.
+
+## Standard captured (the durable artifact this PR exists to back)
+
+The 8-round iteration converged on a design that's now codified as the **Dashboard Standard** in `feedback_dashboard_copy_eli16.md` (agent memory): 7 rules (ELI16 copy + codename maps + grounding intro + self-contained section titles with subtitles + expandable items + fixed label vocabulary + no action-implying language), 8 default substitutions, 4 calm status-color tokens, and the show-don't-tell iteration pattern. The Process Health tab is now the reference implementation.
+
+## Evidence pointers
+
+- All 46 tests green: 30 unit + 12 integration + 4 e2e — includes structural assertions for the unified label order, status-dot CSS classes, and that the dropped framing line is genuinely absent.
+- Safety verified end-to-end: XSS negative fixture still fires zero live elements + no canary; `detail.full` redaction unchanged.
+- Typecheck: `tsc --noEmit` clean.
+- Live-rendered both views (collapsed + expanded) to Chrome headless across 8 iterations and sent screenshots to the user for thumbs-up before each commit. Justin approved v8 with "this is good enough, let's go with it; save this as the standard for future dashboard features".