@bongos/core 1.19.783 → 1.19.784

package/modules/hall-ui/public/sessions.js

@@ -42,6 +42,37 @@
 
   const shortSid = (sid) => String(sid || '').slice(0, 8) || '—';
 
+  // task 1002516 — the transcript accessibility dimension (criterion
+  // `accessibility-fluency-profile`, clause 4). Headed "Plain speech" rather than
+  // "Accessibility" because this page already lives under a shell whose only
+  // other accessibility control is the zoom, and two different meanings of one
+  // word in one view teaches nobody anything.
+  //
+  // A null score is "not scored", NOT a zero: the builder's own profile waived
+  // every signal (an engineer who asked for code terms cannot be marked down for
+  // using them), or the row predates the dimension. Both render as an em dash
+  // with the reason on hover — never as a bad number.
+  const ACCESSIBILITY_TITLE = {
+    clear: 'Read plainly for this builder’s profile.',
+    workable: 'Mostly plain for this builder’s profile.',
+    dense: 'Dense for this builder’s profile — jargon, terminal-first, or implementation framing.',
+    opaque: 'Hard to follow for this builder’s profile.',
+  };
+  // Emits the whole <td>: the page's warn colour is defined on `.ledger td.warn`
+  // (sessions.css), so the class has to land on the cell, not on a span inside it.
+  function accessibilityCell(s) {
+    const raw = s.accessibility_score;
+    const score = raw == null ? null : Number(raw);
+    if (score == null || !Number.isFinite(score)) {
+      return '<td class="ledger__num" title="Not scored — this builder’s own profile waived every signal, or the session predates this measure.">—</td>';
+    }
+    const title = ACCESSIBILITY_TITLE[String(s.accessibility_band || '')] || '';
+    // Below the rubric's own 6.0 threshold reads as the warning the tool-errors
+    // column already uses, so one colour means one thing across the row.
+    const cls = `ledger__num${score < 6 ? ' warn' : ''}`;
+    return `<td class="${cls}" title="${escapeHtml(title)}">${escapeHtml(score.toFixed(1))}</td>`;
+  }
+
   // ---- rendering -----------------------------------------------------------
 
   // Stats reflect the WHOLE corpus (server-computed `totals`), not just the
@@ -75,7 +106,7 @@
     const body = $('#sessions-body');
     if (!sessions.length) {
       body.innerHTML =
-        '<tr><td colspan="9" class="ledger__empty">No sessions recorded yet. They land here as builders ship and end sessions.</td></tr>';
+        '<tr><td colspan="10" class="ledger__empty">No sessions recorded yet. They land here as builders ship and end sessions.</td></tr>';
       return;
     }
     body.innerHTML = sessions
@@ -101,6 +132,7 @@
           `<td class="ledger__num" title="${fmtInt(s.total_tokens)} tokens">${escapeHtml(fmtCompact(s.total_tokens))}</td>` +
           `<td class="ledger__num${errs > 0 ? ' warn' : ''}">${errs}</td>` +
           `<td class="ledger__num">${escapeHtml(fmtDuration(s.duration_seconds))}</td>` +
+          accessibilityCell(s) +
           `<td class="ledger__date">${escapeHtml(fmtDate(s.uploaded_at))}</td>` +
           '</tr>'
         );

package/modules/lifecycle/github-push.js

@@ -524,10 +524,34 @@ async function enableAutoMerge({ nodeId }, deps = {}) {
 // the PR waits for a human nobody told. Returns { ok, reason } — reason is null on
 // success, else a short scrubbed string safe to hand the (ownership-gated) builder.
 // enableAutoMerge stays the boolean façade so existing callers are untouched.
+// logAutoMergeFailure — put the arming failure in the SERVER log, not only in the
+// response body (task 1003511). task 1001431 gave enableAutoMergeDetailed a reason,
+// but it travelled in ONE direction — the publish-branch 201 — so "seven PRs in a row
+// came back auto_merge:false" was diagnosable only by whoever still had the response
+// body. A cause the server computes and then discards is the same outage as one it
+// never computed. Through the module-api logger seam, not a raw console call:
+// console_call_count (config/fitness-baselines.json) is a shrink-only ratchet.
+// Lazy-required so DB-free tests stay hermetic; wrapped so a logger fault can never
+// turn a best-effort arming miss into a thrown publish. Scrubbed below, not at the
+// call sites, so a future caller that forgets cannot leak a token into the log.
+function logAutoMergeFailure(reason, context, logImpl) {
+  try {
+    const sink = logImpl || require('../../src/module-api').logger('lifecycle');
+    sink.warn('auto-merge could not be armed (PR needs a manual merge)',
+      { reason: scrubCredential(String(reason == null ? '' : reason)), context });
+  } catch (_) { /* logging is never load-bearing */ }
+}
+
 async function enableAutoMergeDetailed({ nodeId }, deps = {}) {
+  const context = deps.logContext || 'publish';
+  const fail = (raw) => {
+    const reason = scrubCredential(String(raw == null ? '' : raw));
+    logAutoMergeFailure(reason, context, deps.logImpl);
+    return { ok: false, reason };
+  };
   const token = await resolveToken(deps);
-  if (!token) return { ok: false, reason: 'no GitHub token could be resolved' };
-  if (!nodeId) return { ok: false, reason: 'the pull request has no node id to arm' };
+  if (!token) return fail('no GitHub token could be resolved');
+  if (!nodeId) return fail('the pull request has no node id to arm');
   const doFetch = deps.fetchImpl || fetch;
   const query = `mutation($id:ID!){enablePullRequestAutoMerge(input:{pullRequestId:$id,mergeMethod:MERGE}){clientMutationId}}`;
   try {
@@ -536,15 +560,15 @@ async function enableAutoMergeDetailed({ nodeId }, deps = {}) {
       headers: { ...ghHeaders(token), 'Content-Type': 'application/json' },
       body: JSON.stringify({ query, variables: { id: nodeId } }),
     });
-    if (!res.ok) return { ok: false, reason: `GitHub GraphQL returned HTTP ${res.status}` };
+    if (!res.ok) return fail(`GitHub GraphQL returned HTTP ${res.status}`);
     const out = await res.json();
     if (!out || !out.errors) return { ok: true, reason: null };
     // GitHub answers a repo with auto-merge disabled with a plain GraphQL error;
     // its own message is the actionable one, so pass it through (truncated).
     const msg = out.errors.map((e) => e && e.message).filter(Boolean).join('; ');
-    return { ok: false, reason: scrubCredential(msg || 'GitHub GraphQL rejected the mutation').slice(0, 300) };
+    return fail(scrubCredential(msg || 'GitHub GraphQL rejected the mutation').slice(0, 300));
   } catch (e) {
-    return { ok: false, reason: scrubCredential((e && e.message) || 'the GraphQL request threw').slice(0, 300) };
+    return fail(scrubCredential((e && e.message) || 'the GraphQL request threw').slice(0, 300));
   }
 }
 
@@ -558,7 +582,9 @@ async function enableAutoMergeDetailed({ nodeId }, deps = {}) {
 //      as a permanently-missing workflow, so both are "no readable deploy to wait for";
 //      task 1002472 for the 404 case);
 //    'unavailable'  = a transient read failure (5xx/429/other) — task 1002724).
-//   deploy_probe = { state, http, detail } — WHY the probe landed where it did,
+//   deploy_probe = { state, reason, http, detail } — WHY the probe landed where it did;
+//   `reason` separates the two permanent 'unconfigured' shapes that share a state:
+//   'no_deploy_workflow' (404) vs 'actions_read_forbidden' (403, no Actions:read).
 //   so a stuck disposition is diagnosable without a shell on the host.
 // Mirrors ship.js pollCiDeploy's two-stage check (PR merged -> deploy run).
 async function getPublishStatus({ branch }, deps = {}) {
@@ -596,7 +622,7 @@ async function getPublishStatus({ branch }, deps = {}) {
 
   // Merged → did the prod-deploy workflow succeed for the merge commit?
   let deployStatus = 'pending';
-  let deployProbe = { state: 'pending', http: null, detail: 'no matching deploy run yet' };
+  let deployProbe = { state: 'pending', reason: 'no_deploy_run_yet', http: null, detail: 'no matching deploy run yet' };
   try {
     const runsRes = await doFetch(
       `${api}/actions/workflows/deploy-prod.yml/runs?branch=main&per_page=15`,
@@ -624,7 +650,9 @@ async function getPublishStatus({ branch }, deps = {}) {
       if (exact || afterMerge) {
         deployStatus = 'success';
         deployProbe = {
-          state: 'success', http: runsRes.status,
+          state: 'success',
+          reason: exact ? 'deploy_run_for_merge' : 'main_deploy_after_merge',
+          http: runsRes.status,
           detail: exact ? 'deploy run for the merge commit' : 'main deploy succeeded after the merge (ADR 0161 carrier)',
         };
       }
@@ -648,7 +676,12 @@ async function getPublishStatus({ branch }, deps = {}) {
       // (deployProbeBlind) to route around a probe that will 403 on every sweep forever.
       deployStatus = 'unconfigured';
       deployProbe = {
-        state: 'unconfigured', http: runsRes.status,
+        state: 'unconfigured',
+        // THE SECOND AMBIGUITY (task 1003511): both causes are permanent and must
+        // keep the same state so landConfirmed() can still flip a merged PR, but they
+        // need DIFFERENT actions — 404 nothing to fix, 403 grant Actions:read.
+        reason: runsRes.status === 404 ? 'no_deploy_workflow' : 'actions_read_forbidden',
+        http: runsRes.status,
         detail: runsRes.status === 404
           ? 'no deploy-prod.yml in this repo'
           : 'workflow-runs read forbidden (token lacks Actions:read) — treated as no readable deploy to wait for',
@@ -666,11 +699,11 @@ async function getPublishStatus({ branch }, deps = {}) {
       // deploy state — and let the reconciler decide whether git history already
       // proves the land.
       deployStatus = 'unavailable';
-      deployProbe = { state: 'unavailable', http: runsRes.status, detail: `workflow-runs read failed (HTTP ${runsRes.status})` };
+      deployProbe = { state: 'unavailable', reason: 'workflow_runs_read_failed', http: runsRes.status, detail: `workflow-runs read failed (HTTP ${runsRes.status})` };
     }
   } catch (e) {
     // A network-level miss is genuinely transient — keep waiting, but say so.
-    deployProbe = { state: 'pending', http: null, detail: `workflow-runs fetch threw: ${e && e.message}` };
+    deployProbe = { state: 'pending', reason: 'probe_threw', http: null, detail: `workflow-runs fetch threw: ${e && e.message}` };
   }
   return {
     pr_state: pr.state, merged: true, merge_sha: mergeSha,
@@ -1390,12 +1423,34 @@ async function recheckPullRequest({ number }, deps = {}) {
   if (reopenDelayMs > 0) await doSleep(reopenDelayMs);
   const reopened = await patchState('open');
   let autoMerge = false;
+  let autoMergeReason = null;
   try {
-    if (reopened && reopened.node_id) autoMerge = await enableAutoMerge({ nodeId: reopened.node_id }, deps);
-  } catch (_) {
-    /* auto-merge re-arm is best-effort; mergeIfGreen sweep backstops it */
+    if (reopened && reopened.node_id) {
+      // The DETAILED variant: the boolean façade discarded the cause here, and no
+      // response body carried it either — the quietest of the four (task 1003511).
+      const armed = await enableAutoMergeDetailed(
+        { nodeId: reopened.node_id },
+        { ...deps, logContext: `recheck pr #${number}` }
+      );
+      autoMerge = armed.ok;
+      autoMergeReason = armed.reason;
+    } else {
+      autoMergeReason = 'the reopened pull request returned no node id';
+      logAutoMergeFailure(autoMergeReason, `recheck pr #${number}`, deps.logImpl);
+    }
+  } catch (e) {
+    /* best-effort; the mergeIfGreen sweep backstops it — but this throw used to be
+       invisible even to the operator. */
+    autoMergeReason = scrubCredential((e && e.message) || 'the re-arm threw').slice(0, 300);
+    logAutoMergeFailure(autoMergeReason, `recheck pr #${number}`, deps.logImpl);
   }
-  return { reopened: true, auto_merge: autoMerge, node_id: (reopened && reopened.node_id) || null };
+  return {
+    reopened: true,
+    auto_merge: autoMerge,
+    node_id: (reopened && reopened.node_id) || null,
+    // Only present when the re-arm did not take — the recheck itself still succeeded.
+    ...(autoMerge ? {} : { auto_merge_reason: autoMergeReason }),
+  };
 }
 
 module.exports = {

package/modules/sessions/accessibility.js

@@ -0,0 +1,373 @@
+// modules/sessions/accessibility.js — the ACCESSIBILITY dimension of the session
+// evaluator (task 1002516; clause 4 of criterion `accessibility-fluency-profile`).
+//
+// WHAT IT SCORES, AND WHY IT LIVES HERE AND NOT IN THE GRADER PANEL.
+//
+// The criterion asks for an accessibility dimension "scored from the transcript".
+// The v4 grader panel (modules/grading/) never sees a transcript — every worker
+// is handed { task, valueSummary, diff, changedFiles, ... } and judges the DIFF.
+// The session corpus is the only place the transcript exists, and this module is
+// the only scorer that reads it, so the dimension belongs here. ADR 0291 records
+// that split in full; the short version is that a diff lens cannot see how a
+// builder was TALKED TO, which is the whole subject of the criterion.
+//
+// THE THREE SIGNALS are the ones the criterion names, and only those:
+//   1. unexplained-jargon density — SWE vocabulary used without defining it.
+//   2. terminal-where-a-UI-exists — a shell command handed over for something
+//      the instance already has a supported click-path for.
+//   3. outcome-vs-implementation framing — trade-offs framed as design-pattern
+//      taxonomy instead of cost, time and what the reader will see.
+//
+// FOUR CONTRACTS THIS FILE MUST NEVER BREAK
+//
+// A. PROFILE-RELATIVE, NOT ABSOLUTE. The criterion is explicit that "an expert's
+//    terse experience is never degraded to help a newcomer". So a signal the
+//    builder's own interaction profile SANCTIONS is not scored down — it is not
+//    scored at all (`waived`), and a session whose every signal is waived scores
+//    `null`, not a number. A profile-sanctioned reply can therefore never produce
+//    a low score, which is a stronger guarantee than a generous threshold.
+//
+// B. TERSENESS IS NEVER A PENALTY. `verbosity` is not an input to this file and
+//    must not become one. Every rate below is per 1000 SAMPLED CHARACTERS, so a
+//    short reply and a long one are measured at the same density. Penalising
+//    brevity would invert the point of the whole criterion (the same reasoning
+//    that keeps `verbosity: concise` from dropping a render rung — task 1002518).
+//
+// C. ADVISORY, NEVER A GATE. This score is coaching, recorded on the session row
+//    and read by the BFG. It is not on the ship path and holds nothing. ADR 0241
+//    settled that a taste-shaped judgement may hold a deploy and never a
+//    builder's ship; a transcript-shaped one is the same kind of judgement.
+//
+// D. FAIL TOWARDS NOT PENALISING. Every detector below is deliberately
+//    high-precision and low-recall: a jargon term with any nearby definition
+//    marker counts as explained, and a command only counts when it lands on a
+//    subject with a KNOWN click-path. An undercount is a quiet score; an
+//    overcount is a metric that punishes correct work, which the task's own
+//    "watch out" calls actively harmful.
+//
+// SAMPLING, STATED HONESTLY. The digest stores only the first 160 characters of
+// each assistant turn (session-digest-build.js snippetOf), so this measures the
+// OPENING of every reply, not its whole body. That is a real bound and it is
+// reported rather than hidden: `sampled_chars` and `confidence` travel with the
+// score so a reader knows how much prose it actually saw. Widening the snippet
+// would inflate every session row against the SR-17 disk bounds, so the sample
+// stays where it is and the score stays honest about it.
+
+// NO REQUIRE OF builder-settings, deliberately. ADR 0083 forbids a module
+// importing a sibling and fitness.js enforces it, so the interaction profile
+// arrives as DATA: the upload route resolves the `builder-settings` kernel port,
+// asks it for the effective profile, and hands the plain object in. This file
+// only needs to know which VALUES mean what, so it keys on the literal strings
+// below — and tests/session_accessibility.mjs asserts those strings still exist
+// in interaction-prefs, so a rename there trips a test rather than silently
+// un-waiving an engineer's session.
+const PROFILE_DEFAULTS = Object.freeze({
+  technical_level: 'non_technical',
+  toolchain_familiarity: 'new',
+});
+const PROFILE_VALUES = Object.freeze({
+  technical_level: ['non_technical', 'mixed', 'engineer'],
+  toolchain_familiarity: ['new', 'comfortable'],
+});
+
+// ---------------------------------------------------------------------------
+// Signal 1 — unexplained jargon
+// ---------------------------------------------------------------------------
+
+// Software-engineering vocabulary a non-technical reader is not expected to
+// know. Deliberately NOT a list of this project's own nouns (task, claim, ship,
+// goal, blocker): those are the vocabulary of the product the builder is using,
+// which they learn by using it, not the SWE taxonomy the criterion is about.
+const JARGON_TERMS = [
+  'idempotent', 'idempotency', 'memoize', 'memoise', 'mutex', 'race condition',
+  'closure', 'middleware', 'singleton', 'dependency injection', 'polymorphic',
+  'monkey-patch', 'monkeypatch', 'refactor', 'regex', 'regexp', 'jsonb', 'upsert',
+  'transpile', 'webhook', 'CORS', 'JWT', 'OAuth', 'stack trace', 'nullable',
+  'coerce', 'serialize', 'serialise', 'deserialize', 'deserialise', 'async',
+  'promise chain', 'immutable', 'mutation', 'schema', 'migration', 'ORM',
+  'N+1', 'big-O', 'hoisting', 'shim', 'polyfill', 'tree-shaking', 'sharding',
+  'debounce', 'throttle', 'monorepo', 'worktree', 'rebase', 'cherry-pick',
+  'fast-forward', 'SIGTERM', 'SIGKILL', 'ENOENT', 'stdout', 'stderr', 'daemon',
+  'cron', 'socket', 'mutable', 'idempotently', 'abstraction layer',
+  'thunk', 'reducer', 'hydrate', 'marshalling', 'marshaling', 'nondeterministic',
+  'race-condition', 'deadlock', 'backpressure', 'fan-out', 'fanout',
+];
+
+// A jargon hit is EXPLAINED when a definition marker follows it closely. The
+// window is generous and the marker list is broad on purpose (contract D): a
+// false "explained" costs a quiet score, a false "unexplained" punishes a reply
+// that did define its terms.
+// WORD-BOUNDED, not substring. A naive indexOf made "ORM" fire on "format" and
+// "CORS" on "scores" — a metric that penalises ordinary English is worse than no
+// metric at all (contract D). Each term is compiled once, with a \b only on the
+// edges that are word characters so "N+1" and "big-O" still anchor correctly.
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+const JARGON_RE = JARGON_TERMS.map((term) => ({
+  term,
+  re: new RegExp(
+    (/^\w/.test(term) ? '\\b' : '') + escapeRe(term) + (/\w$/.test(term) ? '\\b' : ''),
+    'gi'
+  ),
+}));
+
+const DEFINITION_WINDOW = 70;
+const DEFINITION_MARKER_RE =
+  /\(|\s—\s|\s--\s|\bi\.e\.|\bthat is\b|\bwhich (?:is|means)\b|\bmeaning\b|\bmeans\b|\bin other words\b|\bthink of (?:it|this) as\b/i;
+
+// ---------------------------------------------------------------------------
+// Signal 2 — terminal where a UI exists
+// ---------------------------------------------------------------------------
+
+// The shape of handing someone a command to run. Not "a command appears in the
+// text" — the agent running a command itself is its own job and not a signal.
+const COMMAND_HANDOFF_RE =
+  /\brun\s+(?:this|the following|`|node |npm |git |psql )|\bin (?:your|a) terminal\b|\bfrom the command line\b|\bpaste (?:this|the following)\b|\b(?:type|enter) this (?:command|in)\b/i;
+
+// The subjects that ALREADY have a supported click-path in the hall. The path is
+// carried beside the pattern because it is the coaching too — a finding that can
+// name where the button is, is worth acting on; one that just says "you used the
+// terminal" is not. Keep this table honest: a subject whose UI does not exist
+// must not be listed, or the signal starts penalising the only way to do the job.
+const UI_BACKED_SUBJECTS = [
+  { re: /\bapi[- ]key|\bart[- ]key|\bgemini key|\banthropic key\b/i, path: 'Settings → API keys' },
+  { re: /\binteraction profile\b|\btechnical level\b|\bverbosity\b|\bwandering\b|\bpreference/i, path: 'Settings → Interaction' },
+  { re: /\bsign in\b|\bsign-in\b|\bre-?auth|\bsession (?:token|expired)\b/i, path: 'Settings → Session' },
+  { re: /\bclaim (?:a |the )?task\b|\bwhat can i work on\b/i, path: 'the hall task list' },
+  { re: /\bblocker\b/i, path: 'the hall blockers page' },
+  { re: /\bleaderboard\b|\bcredits?\b|\bdrachmae\b/i, path: 'the hall leaderboard' },
+];
+
+// ---------------------------------------------------------------------------
+// Signal 3 — implementation framing over outcome framing
+// ---------------------------------------------------------------------------
+
+// Framing a trade-off as design-pattern / architecture taxonomy.
+const IMPLEMENTATION_FRAMING_RE =
+  /\b(?:design pattern|architecture|abstraction|coupling|cohesion|inheritance|interface|polymorphism|dependency graph|module boundary|type system|data model|control flow|separation of concerns|the reducer|the middleware|the schema|refactor(?:ing)?)\b/i;
+
+// Framing the same trade-off as cost, time, or what the reader will see. The
+// criterion's own words: "cost, time and what the end user will see".
+const OUTCOME_FRAMING_RE =
+  /\$\d|\b(?:costs?|cheaper|expensive|free|per month|minutes?|hours?|days?|faster|slower|you(?:'ll| will) see|the (?:user|reader|owner) (?:will|would|sees)|what changes for you|downtime|on screen|in the browser)\b/i;
+
+// ---------------------------------------------------------------------------
+// Penalty curves
+// ---------------------------------------------------------------------------
+//
+// Each signal contributes at most `max` points off a 10. `free` is the rate a
+// session may carry without any penalty at all; `span` is how much further the
+// rate has to climb to reach the full penalty. Rates are per 1000 sampled
+// characters (contract B). The numbers are deliberately round and documented
+// rather than tuned to a corpus — the tests pin the PROPERTIES (monotonic,
+// clamped, waiver-respecting), not these magnitudes, so retuning is cheap.
+const SIGNAL_SPEC = Object.freeze({
+  unexplained_jargon: { max: 4, free: 1.0, span: 4.0 },
+  terminal_where_ui_exists: { max: 3, free: 0.0, span: 1.5 },
+  implementation_over_outcome: { max: 3, free: 0.0, span: 1.0 },
+});
+
+// Below this much sampled prose the rates are too noisy to stand behind.
+const LOW_CONFIDENCE_CHARS = 1000;
+
+function clamp(n, lo, hi) {
+  const x = Number(n);
+  if (!Number.isFinite(x)) return lo;
+  return Math.max(lo, Math.min(hi, x));
+}
+
+// resolveProfile — the effective interaction profile this session is scored
+// against. A missing/partial profile falls back to the field defaults, which are
+// the accessible-leaning posture (interaction-prefs.js FIELDS) — so a session
+// with no profile at all is scored as the default builder, never unscored.
+function resolveProfile(profile) {
+  const raw = profile && typeof profile === 'object' ? profile : {};
+  const out = {};
+  for (const f of Object.keys(PROFILE_DEFAULTS)) {
+    out[f] = PROFILE_VALUES[f].includes(raw[f]) ? raw[f] : PROFILE_DEFAULTS[f];
+  }
+  return out;
+}
+
+// waiversFor — which signals this profile sanctions, and WHY. The reason string
+// is carried onto the result so a builder reading a waived signal sees the
+// setting that waived it rather than a silent absence. Pure.
+//
+// `mixed` technical level relaxes rather than waives: its own contract says
+// "light SWE vocabulary is fine without defining every term", which is a wider
+// allowance, not a blank cheque — so it doubles the free rate instead.
+function waiversFor(profile) {
+  const p = resolveProfile(profile);
+  const w = {};
+  if (p.technical_level === 'engineer') {
+    w.unexplained_jargon = 'technical_level: engineer — this builder asked to be spoken to in code and architecture terms.';
+    w.implementation_over_outcome = 'technical_level: engineer — implementation framing is what this builder asked for.';
+  }
+  if (p.toolchain_familiarity === 'comfortable') {
+    w.terminal_where_ui_exists = 'toolchain_familiarity: comfortable — this builder does not need the click-path first.';
+  }
+  return w;
+}
+
+// Free-rate multiplier for a signal under this profile (1 = the spec's own free
+// rate). Only `mixed` currently widens anything; everything else scores at spec.
+function leniencyFor(profile, signal) {
+  const p = resolveProfile(profile);
+  if (signal === 'unexplained_jargon' && p.technical_level === 'mixed') return 2;
+  return 1;
+}
+
+// assistantProse — the sampled assistant text this scorer may read, as
+// { text, chars }. USER turns are excluded on purpose: a tool result or the
+// builder's own words are not the agent's prose, and scoring them would make the
+// metric depend on what the builder typed.
+function assistantProse(detail) {
+  const turns = (Array.isArray(detail) ? detail : []).filter(
+    (t) => t && typeof t === 'object' && t.role === 'assistant' && typeof t.snippet === 'string' && t.snippet
+  );
+  const snippets = turns.map((t) => t.snippet);
+  return { snippets, chars: snippets.reduce((n, s) => n + s.length, 0) };
+}
+
+// countUnexplainedJargon — jargon hits with no definition marker within
+// DEFINITION_WINDOW characters after them. Returns { count, evidence }.
+function countUnexplainedJargon(snippets) {
+  let count = 0;
+  let evidence = '';
+  for (const s of snippets) {
+    for (const { term, re } of JARGON_RE) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(s)) !== null) {
+        const end = m.index + m[0].length;
+        const after = s.slice(end, end + DEFINITION_WINDOW);
+        if (DEFINITION_MARKER_RE.test(after)) continue;
+        count++;
+        if (!evidence) evidence = `"${term}" undefined in: ${s.slice(0, 80)}`;
+      }
+    }
+  }
+  return { count, evidence };
+}
+
+// countTerminalWhereUiExists — a command handed over on a subject that has a
+// known click-path. Returns { count, evidence }; the evidence names the path so
+// the finding is actionable.
+function countTerminalWhereUiExists(snippets) {
+  let count = 0;
+  let evidence = '';
+  for (const s of snippets) {
+    if (!COMMAND_HANDOFF_RE.test(s)) continue;
+    const subject = UI_BACKED_SUBJECTS.find((u) => u.re.test(s));
+    if (!subject) continue;
+    count++;
+    if (!evidence) evidence = `${subject.path} exists for this — "${s.slice(0, 80)}"`;
+  }
+  return { count, evidence };
+}
+
+// countImplementationOverOutcome — turns that frame in implementation taxonomy
+// with NO outcome framing anywhere in the same turn. A turn carrying both is not
+// a finding: naming the architecture AND what it costs is exactly right.
+function countImplementationOverOutcome(snippets) {
+  let count = 0;
+  let evidence = '';
+  for (const s of snippets) {
+    if (!IMPLEMENTATION_FRAMING_RE.test(s)) continue;
+    if (OUTCOME_FRAMING_RE.test(s)) continue;
+    count++;
+    if (!evidence) evidence = `implementation framing, no cost/time/user framing: ${s.slice(0, 80)}`;
+  }
+  return { count, evidence };
+}
+
+const DETECTORS = Object.freeze({
+  unexplained_jargon: countUnexplainedJargon,
+  terminal_where_ui_exists: countTerminalWhereUiExists,
+  implementation_over_outcome: countImplementationOverOutcome,
+});
+
+function bandFor(score) {
+  if (score >= 8) return 'clear';
+  if (score >= 6) return 'workable';
+  if (score >= 4) return 'dense';
+  return 'opaque';
+}
+
+// scoreAccessibility — the whole dimension for one session's digest detail.
+// PURE (no I/O), so it is unit-tested and can be computed either at upload (the
+// route, from the authenticated builder's own profile) or at eval time by the
+// BFG for a historical row that predates the column.
+//
+// Returns:
+//   { score, band, signals[], profile, sampled_chars, sampled_turns, confidence }
+// `score` is null when every signal is waived (contract A) or when there was no
+// assistant prose to read at all — a null is the honest answer and the surfaces
+// render it as "—" rather than inventing a 10.
+function scoreAccessibility(detail, opts = {}) {
+  const profile = resolveProfile(opts.profile);
+  const waivers = waiversFor(profile);
+  const { snippets, chars } = assistantProse(detail);
+  const per1000 = chars > 0 ? 1000 / chars : 0;
+
+  const signals = [];
+  let penalty = 0;
+  let scored = 0;
+  for (const [type, spec] of Object.entries(SIGNAL_SPEC)) {
+    if (waivers[type]) {
+      signals.push({ type, waived: true, reason: waivers[type] });
+      continue;
+    }
+    scored++;
+    const { count, evidence } = DETECTORS[type](snippets);
+    const rate = Number((count * per1000).toFixed(3));
+    const free = spec.free * leniencyFor(profile, type);
+    const over = Math.max(0, rate - free);
+    const p = spec.span > 0 ? clamp((over / spec.span) * spec.max, 0, spec.max) : 0;
+    penalty += p;
+    signals.push({
+      type,
+      waived: false,
+      count,
+      rate,
+      penalty: Number(p.toFixed(2)),
+      ...(evidence ? { evidence } : {}),
+    });
+  }
+
+  const scorable = scored > 0 && chars > 0;
+  const score = scorable ? Number(clamp(10 - penalty, 0, 10).toFixed(1)) : null;
+  return {
+    score,
+    band: score == null ? 'n/a' : bandFor(score),
+    signals,
+    profile,
+    sampled_chars: chars,
+    sampled_turns: snippets.length,
+    // Confidence describes the SAMPLE, not the score — a fully-waived session
+    // still read real prose, and saying "none" there would misreport why the
+    // score is absent (the band already says `n/a`).
+    confidence: chars === 0 ? 'none' : chars < LOW_CONFIDENCE_CHARS ? 'low' : 'normal',
+  };
+}
+
+module.exports = {
+  scoreAccessibility,
+  // Exported so the tests can pin the contracts (waivers, leniency, each
+  // detector) without reconstructing a whole digest for every case.
+  resolveProfile,
+  waiversFor,
+  leniencyFor,
+  assistantProse,
+  countUnexplainedJargon,
+  countTerminalWhereUiExists,
+  countImplementationOverOutcome,
+  bandFor,
+  SIGNAL_SPEC,
+  JARGON_TERMS,
+  UI_BACKED_SUBJECTS,
+  LOW_CONFIDENCE_CHARS,
+  PROFILE_DEFAULTS,
+  PROFILE_VALUES,
+};

package/modules/sessions/db.js

@@ -490,6 +490,11 @@ const SESSION_ORDER = Object.freeze({
   tokens: 'sr.total_tokens DESC, sr.uploaded_at DESC',
   duration: 'sr.duration_seconds DESC NULLS LAST, sr.uploaded_at DESC',
   drachmae: 'sr.drachmae_earned DESC, sr.uploaded_at DESC',
+  // task 1002516 — WORST FIRST, like tool_errors: the sessions worth coaching are
+  // the low-scoring ones. NULLS LAST keeps the un-scorable rows (a fully-waived
+  // expert profile, or a row uploaded before the dimension existed) off the top
+  // of a ranking they have no score to earn.
+  accessibility: "(sr.metrics->'accessibility'->>'score')::numeric ASC NULLS LAST, sr.uploaded_at DESC",
 });
 function resolveSessionOrder(key) {
   return Object.prototype.hasOwnProperty.call(SESSION_ORDER, key) ? SESSION_ORDER[key] : SESSION_ORDER.recent;
@@ -544,6 +549,12 @@ const SESSION_SUMMARY_COLS = `
   sr.task_ids, sr.drachmae_earned, sr.total_tokens, sr.duration_seconds,
   COALESCE((sr.metrics->>'tool_error_count')::int, 0)  AS tool_errors,
   COALESCE((sr.metrics->>'assistant_turns')::int, 0)   AS assistant_turns,
+  -- task 1002516: the transcript accessibility dimension. NOT coalesced to 0 —
+  -- a missing score means "not scored" (waived, or pre-dating the dimension) and
+  -- a zero would read as the worst possible session. The band travels with it so
+  -- the ledger does not have to re-derive the thresholds in the browser.
+  (sr.metrics->'accessibility'->>'score')::numeric      AS accessibility_score,
+  (sr.metrics->'accessibility'->>'band')                AS accessibility_band,
   sr.uploaded_at`;
 
 // searchSessions — cross-builder search over the corpus, filtered by session

package/modules/sessions/routes/sessions.js

@@ -31,7 +31,12 @@ const express = require('express');
 const api = require('../../../src/module-api');
 const auth = api; // requireBuilder / requireRank live on the doorway surface
 const db = require('../db');
-const seams = api; // resolveOptional('reward') — the economy port, kernel-mediated
+// task 1002516 (clause 4 of `accessibility-fluency-profile`): the transcript
+// accessibility dimension. The scorer is this module's own PURE file — it takes
+// the interaction profile as data precisely so it does not have to require
+// builder-settings, which ADR 0083 forbids.
+const { scoreAccessibility } = require('../accessibility');
+const seams = api; // resolveOptional('reward' | 'builder-settings') — kernel-mediated ports
 const { validateOrRespond, parseId } = api;
 
 const UPLOAD_BODY_LIMIT = '4mb';
@@ -237,6 +242,35 @@ module.exports = function buildSessionsRouter() {
       const metrics = body.metrics && typeof body.metrics === 'object' ? { ...body.metrics } : {};
       delete metrics.total_tokens;
       delete metrics.model_usage; // promoted to its own column; avoid two copies
+      // task 1002516 — the accessibility dimension is computed HERE, server-side,
+      // for the same reason drachmae is: a score the uploader could supply is a
+      // score nobody can read. It is also the only place the builder's own
+      // interaction profile is available without another round trip — the
+      // SessionEnd hook runs under a 6-second watchdog, so asking it to fetch
+      // /me would trade a coaching metric for dropped uploads.
+      delete metrics.accessibility; // never trusted from the client
+      const settings = seams.resolveOptional('builder-settings');
+      let interactionProfile = null;
+      let profileUnavailable = false;
+      if (settings && settings.getBuilderBehaviorPrefs && settings.describeInteraction) {
+        // Best-effort: a coaching score must never be the reason an upload 500s.
+        // The failure is RECORDED ON THE ROW rather than logged — a durable flag
+        // a reader of the score can see beats a console line nobody correlates
+        // with the session it degraded.
+        try {
+          const prefs = await settings.getBuilderBehaviorPrefs(req.builder.id);
+          interactionProfile = settings.describeInteraction(prefs).effective;
+        } catch (_) {
+          profileUnavailable = true;
+        }
+      }
+      // With the module off (or the read failed) the scorer falls back to the
+      // accessible-leaning DEFAULT profile, which is the right posture: an
+      // instance that never configured a profile has every builder on it.
+      metrics.accessibility = {
+        ...scoreAccessibility(detailArr, { profile: interactionProfile }),
+        ...(profileUnavailable ? { profile_unavailable: true } : {}),
+      };
       const modelUsage = body.model_usage && typeof body.model_usage === 'object'
         ? body.model_usage : {};
       // upsert + cost-plus token reward in ONE transaction (task 1005). The