shakers-cli-beta 0.8.0-beta.0

package/src/render-ai-fluency.js

@@ -0,0 +1,266 @@
+'use strict';
+
+// Renders the "My work with AI" preview (3x3 matrix + vision E + howIWork F +
+// traction), terminal + HTML. Copy is inlined for the spike; promote to i18n later.
+
+const { SETUP_CODE, CELL_NAMES } = require('./ai-fluency-cell');
+const { detectedToolNames } = require('./detected-tools');
+
+const SETUP_ORDER = ['ASSISTED', 'EXTENDED', 'ORCHESTRATED'];
+const USAGE_ORDER = ['REACTIVE', 'DELIBERATE', 'RIGOROUS'];
+
+const COPY = {
+  es: {
+    title: 'Tu trabajo con IA (Setup x Uso)',
+    usage: { REACTIVE: 'Reactivo', DELIBERATE: 'Deliberado', RIGOROUS: 'Riguroso' },
+    setup: { ASSISTED: 'Asistido', EXTENDED: 'Extendido', ORCHESTRATED: 'Orquestado' },
+    aiNative: 'AI Native',
+    pending: 'Tu perfil se está evaluando; míralo en un momento en "Mi trabajo con IA".',
+    matrixUpdating: 'Tu matriz Setup x Uso se está actualizando; aparecerá en breve.',
+    setupOnly: 'Disponible en tu perfil tras iniciar sesión y compartir el informe.',
+    visionLabel: 'Mi visión sobre la IA',
+    howIWorkLabel: 'Cómo trabajo con IA',
+    howIWorkMissing: 'Se genera tras la entrevista de onboarding.',
+    tractionLabel: 'Actividad',
+    sessions90d: 'sesiones (90d)',
+    daysPerWeek: 'días/semana',
+    agents: (d, p) => `${d} agentes detectados${p != null ? ` · ${p} en tu perfil` : ''}`,
+    toolsLabel: 'herramientas',
+    axisSetup: 'Setup',
+    axisUsage: 'Uso',
+    agentsLabel: 'Agentes',
+  },
+  en: {
+    title: 'Your work with AI (Setup x Usage)',
+    usage: { REACTIVE: 'Reactive', DELIBERATE: 'Deliberate', RIGOROUS: 'Rigorous' },
+    setup: { ASSISTED: 'Assisted', EXTENDED: 'Extended', ORCHESTRATED: 'Orchestrated' },
+    aiNative: 'AI Native',
+    pending: 'Your profile is being evaluated; check "My work with AI" shortly.',
+    matrixUpdating: 'Your Setup x Usage matrix is updating; it will appear shortly.',
+    setupOnly: 'Available on your profile after you log in and share the report.',
+    visionLabel: 'My vision on AI',
+    howIWorkLabel: 'How I work with AI',
+    howIWorkMissing: 'Generated after the onboarding interview.',
+    tractionLabel: 'Traction',
+    sessions90d: 'sessions (90d)',
+    daysPerWeek: 'days/week',
+    agents: (d, p) => `${d} agents detected${p != null ? ` · ${p} on your profile` : ''}`,
+    toolsLabel: 'tools',
+    axisSetup: 'Setup',
+    axisUsage: 'Usage',
+    agentsLabel: 'Agents',
+  },
+};
+
+function copyFor(lang) {
+  return COPY[lang === 'es' ? 'es' : 'en'];
+}
+
+// The matrix band can lag behind E/F (independent projection). When absent, render
+// E/F/traction anyway and swap the 3x3 grid for a short "updating" note.
+function matrixReady(matrix) {
+  return !!(matrix && (matrix.setupLevel || matrix.usageLevel || matrix.cell));
+}
+
+const noColor = new Proxy({}, { get: () => '' });
+
+const esc = (s) => String(s).replace(/[&<>"]/g, (ch) =>
+  ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[ch]));
+
+// Traction metrics as compact "label: value" fragments, omitting null fields.
+function tractionParts(traction, t) {
+  if (!traction) return [];
+  const parts = [];
+  if (traction.sessions90d != null) parts.push(`${traction.sessions90d} ${t.sessions90d}`);
+  if (traction.activeDaysPerWeek != null) parts.push(`${traction.activeDaysPerWeek} ${t.daysPerWeek}`);
+  if (traction.agentsDetected != null) parts.push(t.agents(traction.agentsDetected, traction.agentsOnProfile));
+  const tools = detectedToolNames(traction.tools);
+  if (tools.length) parts.push(`${t.toolsLabel}: ${tools.join(', ')}`);
+  return parts;
+}
+
+function matrixTerminalLines(matrix, t, c) {
+  // Column widths from the longest label (incl. current-cell brackets). Pad BEFORE
+  // colorizing: padEnd counts ANSI escape bytes, so padding a colored string misaligns.
+  const rowLabels = SETUP_ORDER.map((s) => `${SETUP_CODE[s]} ${t.setup[s]}`);
+  const rowW = Math.max(...rowLabels.map((s) => s.length)) + 2;
+  const cellLabels = SETUP_ORDER.flatMap((s) => USAGE_ORDER.map((u) => CELL_NAMES[s][u]));
+  const headerLabels = USAGE_ORDER.map((u) => t.usage[u]);
+  const colW = Math.max(...cellLabels.map((x) => x.length), ...headerLabels.map((x) => x.length)) + 4;
+
+  const lines = [`  ${c.bold}${t.title}${c.reset}`];
+  lines.push(`  ${c.dim}${' '.repeat(rowW) + headerLabels.map((u) => u.padEnd(colW)).join('')}${c.reset}`);
+  for (const s of SETUP_ORDER) {
+    const rowLabel = `${SETUP_CODE[s]} ${t.setup[s]}`.padEnd(rowW);
+    const cells = USAGE_ORDER.map((u) => {
+      const name = CELL_NAMES[s][u];
+      const isCurrent = matrix.setupLevel === s && matrix.usageLevel === u;
+      if (isCurrent) return `${c.accent}${c.bold}${`[${name}]`.padEnd(colW)}${c.reset}`;
+      return `${c.muted}${name.padEnd(colW)}${c.reset}`;
+    }).join('');
+    lines.push(`  ${c.dim}${rowLabel}${c.reset}${cells}`);
+  }
+  return lines;
+}
+
+function buildProfileSections(preview, t) {
+  const sections = [];
+  const m = (preview && preview.matrix) || {};
+  const setupExp = preview.setup && preview.setup.explanation ? preview.setup.explanation : null;
+  if (m.setupLevel) {
+    const value = [m.setupCode, t.setup[m.setupLevel]].filter(Boolean).join(' ');
+    sections.push({ kind: 'axis', label: t.axisSetup, value, explanation: setupExp });
+  }
+  const usageExp = preview.usage && preview.usage.explanation ? preview.usage.explanation : null;
+  if (m.usageLevel) {
+    sections.push({ kind: 'axis', label: t.axisUsage, value: t.usage[m.usageLevel] || m.usageLevel, explanation: usageExp });
+  }
+  if (preview.vision) sections.push({ kind: 'narrative', label: t.visionLabel, body: preview.vision });
+  if (preview.howIWork) sections.push({ kind: 'narrative', label: t.howIWorkLabel, body: preview.howIWork });
+  return sections;
+}
+
+const axisBody = (s) => (s.explanation ? `${s.value} — ${s.explanation}` : s.value);
+
+// Full "My work with AI" preview, terminal. `preview` is the normalized shape from
+// resolveAiProfilePreview; `status` drives the fallbacks.
+function renderAiProfileTerminal({ status, preview } = {}, { lang = 'en', c = noColor } = {}) {
+  const t = copyFor(lang);
+  // Non-fatal notices (not-yet-judged / setup-only) → yellow.
+  if (status === 'unavailable') return `  ${c.warning || c.muted}${t.setupOnly}${c.reset}`;
+  if (status !== 'ready' || !preview) return `  ${c.warning || c.muted}${t.pending}${c.reset}`;
+
+  const lines = matrixReady(preview.matrix)
+    ? matrixTerminalLines(preview.matrix, t, c)
+    : [`  ${c.bold}${t.title}${c.reset}`, `  ${c.warning || c.muted}${t.matrixUpdating}${c.reset}`];
+  const sections = buildProfileSections(preview, t);
+  const axes = sections.filter((s) => s.kind === 'axis');
+  if (axes.length) {
+    lines.push('');
+    for (const a of axes) lines.push(`  ${c.bold}${a.label}:${c.reset} ${c.muted}${axisBody(a)}${c.reset}`);
+  }
+  for (const n of sections.filter((s) => s.kind === 'narrative')) {
+    lines.push('', `  ${c.bold}${n.label}${c.reset}`, `  ${c.muted}${n.body}${c.reset}`);
+  }
+  // Traction now lives in the Activity section (terminal-agents#printActivity).
+  return lines.join('\n');
+}
+
+function plainAgentLines(agents) {
+  if (!Array.isArray(agents) || agents.length === 0) return [];
+  return agents.map((a) => {
+    const bits = [a.category, a.role].filter(Boolean);
+    return bits.length ? `- ${a.name} — ${bits.join(' · ')}` : `- ${a.name}`;
+  });
+}
+
+// Full "My work with AI" report as plain markdown (NO ANSI), for the MCP tool so a chat client shows the same report the CLI terminal prints.
+function renderAiProfilePlain({ status, preview } = {}, { lang = 'en', agents = [] } = {}) {
+  const t = copyFor(lang);
+  const out = [];
+  if (status === 'unavailable') {
+    out.push(t.setupOnly);
+  } else if (status !== 'ready' || !preview) {
+    out.push(t.pending);
+  } else {
+    if (matrixReady(preview.matrix)) {
+      const gridLines = matrixTerminalLines(preview.matrix, t, noColor).slice(1);
+      out.push(`## ${t.title}`, '', '```', ...gridLines, '```');
+    } else {
+      out.push(`## ${t.title}`, '', t.matrixUpdating);
+    }
+    const sections = buildProfileSections(preview, t);
+    const axes = sections.filter((s) => s.kind === 'axis');
+    if (axes.length) {
+      out.push('');
+      for (const a of axes) out.push(`${a.label}: ${axisBody(a)}`);
+    }
+    for (const n of sections.filter((s) => s.kind === 'narrative')) {
+      out.push('', `**${n.label}**`, n.body);
+    }
+    const tp = tractionParts(preview.traction, t);
+    if (tp.length) out.push('', `**${t.tractionLabel}:** ${tp.join(' · ')}`);
+  }
+  const agentLines = plainAgentLines(agents);
+  if (agentLines.length) out.push('', `**${t.agentsLabel}**`, ...agentLines);
+  return out.join('\n');
+}
+
+// Full "My work with AI" preview, HTML. '' when there is nothing to show inline.
+function renderAiProfileHtml({ status, preview } = {}, { lang = 'en' } = {}) {
+  const t = copyFor(lang);
+  if (status === 'unavailable') return `<p class="ai-fluency-note">${esc(t.setupOnly)}</p>`;
+  if (status !== 'ready' || !preview) return `<p class="ai-fluency-note">${esc(t.pending)}</p>`;
+
+  const m = preview.matrix;
+  const out = [
+    `<section class="ai-fluency" aria-label="${esc(t.title)}">`,
+    `<h3>${esc(t.title)}</h3>`,
+  ];
+  if (matrixReady(m)) {
+    const rows = SETUP_ORDER.map((s) => {
+      const cells = USAGE_ORDER.map((u) => {
+        const current = m.setupLevel === s && m.usageLevel === u;
+        return `<td class="ai-fluency-cell${current ? ' is-current' : ''}">${esc(CELL_NAMES[s][u])}</td>`;
+      }).join('');
+      return `<tr><th scope="row">${esc(SETUP_CODE[s])} ${esc(t.setup[s])}</th>${cells}</tr>`;
+    }).join('');
+    const head = USAGE_ORDER.map((u) => `<th scope="col">${esc(t.usage[u])}</th>`).join('');
+    out.push(
+      '<table class="ai-fluency-matrix">',
+      `<thead><tr><th></th>${head}</tr></thead>`,
+      `<tbody>${rows}</tbody>`,
+      '</table>',
+    );
+  } else {
+    out.push(`<p class="ai-fluency-note">${esc(t.matrixUpdating)}</p>`);
+  }
+  if (m.cell) {
+    out.push(`<p class="ai-fluency-current">${esc(m.setupCode)}·${esc(t.usage[m.usageLevel] || m.usageLevel)} → <strong>${esc(m.cell)}</strong>${m.isAiNative ? ` <span class="ai-native">★ ${esc(t.aiNative)}</span>` : ''}</p>`);
+  }
+  if (preview.vision) {
+    out.push(`<div class="ai-vision"><h4>${esc(t.visionLabel)}</h4><p>${esc(preview.vision)}</p></div>`);
+  }
+  out.push(`<div class="ai-howiwork"><h4>${esc(t.howIWorkLabel)}</h4><p>${preview.howIWork ? esc(preview.howIWork) : `<em>${esc(t.howIWorkMissing)}</em>`}</p></div>`);
+  const parts = tractionParts(preview.traction, t);
+  if (parts.length) {
+    out.push(`<p class="ai-traction"><strong>${esc(t.tractionLabel)}:</strong> ${esc(parts.join(' · '))}</p>`);
+  }
+  out.push('</section>');
+  return out.join('');
+}
+
+// Matrix-only HTML (kept for render-sheet.js; the HTML report is a separate iteration).
+function renderAiFluencyMatrixHtml({ status, usage } = {}, { lang = 'en' } = {}) {
+  const t = copyFor(lang);
+  if (status === 'unavailable') return `<p class="ai-fluency-note">${esc(t.setupOnly)}</p>`;
+  if (status !== 'ready' || !usage || !usage.cell) return `<p class="ai-fluency-note">${esc(t.pending)}</p>`;
+  const rows = SETUP_ORDER.map((s) => {
+    const cells = USAGE_ORDER.map((u) => {
+      const current = usage.setupLevel === s && usage.usageLevel === u;
+      return `<td class="ai-fluency-cell${current ? ' is-current' : ''}">${esc(CELL_NAMES[s][u])}</td>`;
+    }).join('');
+    return `<tr><th scope="row">${esc(SETUP_CODE[s])} ${esc(t.setup[s])}</th>${cells}</tr>`;
+  }).join('');
+  const head = USAGE_ORDER.map((u) => `<th scope="col">${esc(t.usage[u])}</th>`).join('');
+  return [
+    `<section class="ai-fluency" aria-label="${esc(t.title)}">`,
+    `<h3>${esc(t.title)}</h3>`,
+    '<table class="ai-fluency-matrix">',
+    `<thead><tr><th></th>${head}</tr></thead>`,
+    `<tbody>${rows}</tbody></table>`,
+    `<p class="ai-fluency-current">${esc(usage.setupCode)}·${esc(t.usage[usage.usageLevel] || usage.usageLevel)} → <strong>${esc(usage.cell)}</strong>${usage.isAiNative ? ` <span class="ai-native">★ ${esc(t.aiNative)}</span>` : ''}</p>`,
+    '</section>',
+  ].join('');
+}
+
+module.exports = {
+  renderAiProfileTerminal,
+  renderAiProfilePlain,
+  renderAiProfileHtml,
+  renderAiFluencyMatrixHtml,
+  copyFor,
+  tractionParts,
+  SETUP_ORDER,
+  USAGE_ORDER,
+};

package/src/render-certification.js

@@ -0,0 +1,177 @@
+'use strict';
+
+const { getCatalog } = require('./i18n');
+const { buildRemediationPrompt } = require('./certify-remediation-prompt');
+const { sanitizeRenderText } = require('./sanitize-network-text');
+const { palette } = require('./ansi');
+const { BRAND_ANSI } = require('./brand-ansi');
+const { DEFAULT_REPORT_GATE } = require('./report-gating');
+
+// Local shorthand: this file has ~15 paint sites and spelling the full name at
+// each one buried the markup. Non-strings degrade to '' (see the primitive).
+const display = (s) => sanitizeRenderText(s);
+
+const C = palette({
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  primary: BRAND_ANSI.primary,
+  accent: BRAND_ANSI.accent,
+  success: BRAND_ANSI.success,
+  warning: BRAND_ANSI.warning,
+  danger: BRAND_ANSI.danger,
+});
+
+function anyTruncated(items) {
+  return (items || []).some((i) => i && i.sampling && i.sampling.truncated);
+}
+
+// ADR-024 rubric dimension order (terminal).
+const DIMENSION_KEYS = ['idiomatic', 'correctness', 'depth', 'structure', 'testing'];
+
+// Score band -> semantic (shared with the HTML/graph CSS class via `graph-certs.js`, which still imports this).
+function scoreBand(score) {
+  if (typeof score !== 'number') return 'mid';
+  if (score >= 70) return 'high';
+  if (score >= 40) return 'mid';
+  return 'low';
+}
+
+// ADR-016: named skill level (by decision power, not points) shown INSTEAD of the numeric grade.
+function skillLevelForScore(score) {
+  const band = scoreBand(score);
+  if (typeof score !== 'number') return { key: null, band };
+  return { key: band === 'high' ? 'expert' : band === 'low' ? 'middle' : 'senior', band };
+}
+
+// Localized level label from the certify.report.skillLevels catalog.
+function skillLevelLabel(key, r) {
+  const names = (r && r.skillLevels) || {};
+  return key ? (names[key] || key) : (names.na || '—');
+}
+
+const RULE = '────────────────────────────────────────';
+
+// Terminal-condense (CPO feedback): the LLM rationale can be several sentences.
+const RATIONALE_MAX = 220;
+function conciseRationale(text) {
+  const s = String(text == null ? '' : text).replace(/\s+/g, ' ').trim();
+  if (s.length <= RATIONALE_MAX) return s;
+  const window = s.slice(0, RATIONALE_MAX);
+  const lastStop = Math.max(window.lastIndexOf('. '), window.lastIndexOf('! '), window.lastIndexOf('? '));
+  if (lastStop >= 80) return window.slice(0, lastStop + 1);
+  return `${window.replace(/[\s.,;:]+$/, '')}…`;
+}
+
+function renderCertificationTerminal(certification, lang, opts = {}) {
+  const r = getCatalog(lang).certify.report;
+  const items = Array.isArray(certification && certification.items) ? certification.items : [];
+  const lines = [];
+  // issue 123 / ADR-044: the SAME identity gate the footprint report reads.
+  const gate = opts.gate || DEFAULT_REPORT_GATE;
+
+  // Header stands out; disclaimer + cost note are deliberately quiet (dim) so
+  // the per-Skill results below are visually dominant (issue 011 feedback).
+  lines.push(`${C.bold}${C.primary}${r.heading}${C.reset}`);
+  // talents-ai-score, ADR-051: this whole render is now a FALLBACK — reached only when the mandatory interview did not complete.
+  if (opts.noInterview && r.noInterviewNote) lines.push(`${C.bold}${C.warning}${r.noInterviewNote}${C.reset}`);
+  lines.push('');
+  lines.push(`${C.dim}${r.disclaimer}${C.reset}`);
+  lines.push(`${C.dim}${r.costNote}${C.reset}`);
+  // ADR-025 authorship receipt (run-level): repo + commit range + honest note,
+  // shown once. Attribution is based on git authorship, NOT cryptographic proof.
+  const authorship = (certification && certification.authorship) || null;
+  const rc = r.receipt;
+  if (rc && authorship && (authorship.repository || authorship.commitRange)) {
+    const bits = [];
+    if (authorship.repository) bits.push(`${rc.repoLabel}: ${display(authorship.repository)}`);
+    if (authorship.commitRange) bits.push(`${rc.commitRangeLabel}: ${authorship.commitRange}`);
+    lines.push(`${C.dim}${rc.label} — ${bits.join(' · ')}${C.reset}`);
+  }
+  if (rc) lines.push(`${C.dim}${rc.note}${C.reset}`);
+  if (anyTruncated(items)) lines.push(`\n  ${C.warning}${r.partialSampleWarning}${C.reset}`);
+  lines.push('');
+
+  if (items.length === 0) {
+    lines.push(`  ${r.noItems}`);
+    return lines.join('\n');
+  }
+
+  for (const item of items) {
+    const title = `${display(item.skillName)}${item.technology ? ` (${display(item.technology)})` : ''}`;
+    lines.push(`${C.bold}${C.primary}╭─ ${title}${C.reset}`);
+
+    if (item.sampling && item.sampling.sampleable === false) {
+      lines.push(`${C.primary}│${C.reset}  ${r.notSampleableNote(display(item.technology))}`);
+      lines.push(`${C.primary}╰─${C.reset}`);
+      lines.push('');
+      continue;
+    }
+    if (!item.result) {
+      lines.push(`${C.primary}│${C.reset}  ${r.notCertified}`);
+      lines.push(`${C.primary}╰─${C.reset}`);
+      lines.push('');
+      continue;
+    }
+
+    // ADR-016: the HEADLINE is the named level (Middle/Senior/Expert) instead of the numeric 0-100 grade.
+    const { key: levelKey } = skillLevelForScore(item.result.score);
+    lines.push(`${C.primary}│${C.reset}  ${C.bold}${C.accent}${r.levelLine(skillLevelLabel(levelKey, r))}${C.reset}`);
+    // ADR-024: show the anchored rubric dimensions so the level is explainable.
+    if (item.result.dimensions && r.dimensionsLabel && r.dimensionLabels) {
+      lines.push(`${C.primary}│${C.reset}  ${C.bold}${r.dimensionsLabel}:${C.reset}`);
+      for (const key of DIMENSION_KEYS) {
+        const v = item.result.dimensions[key];
+        const shown = typeof v === 'number' ? `${v}/4` : r.dimensionNA;
+        lines.push(`${C.primary}│${C.reset}    ${C.dim}${r.dimensionLabels[key] || key}:${C.reset} ${shown}`);
+      }
+    }
+    if (item.result.rationale) {
+      lines.push(`${C.primary}│${C.reset}  ${C.bold}${r.rationaleLabel}:${C.reset} ${conciseRationale(display(item.result.rationale))}`);
+    }
+    if (Array.isArray(item.result.improvements) && item.result.improvements.length > 0) {
+      lines.push(`${C.primary}│${C.reset}  ${C.bold}${r.improvementsLabel}:${C.reset}`);
+      for (const imp of item.result.improvements) lines.push(`${C.primary}│${C.reset}    • ${display(imp)}`);
+    }
+    if (item.sampling) {
+      const summary = r.sampleSummary(item.sampling.includedCount, item.sampling.candidateCount, item.sampling.estTokens);
+      const tag = item.sampling.truncated ? ` ${r.partialTag}` : '';
+      lines.push(`${C.primary}│${C.reset}  ${C.dim}${summary}${tag}${C.reset}`);
+    }
+    // ADR-025 per-Skill authorship receipt (compact in terminal): attributed
+    // file count + the author emails confirmed against the identity.
+    if (rc && Array.isArray(item.fileAttribution) && item.fileAttribution.length > 0) {
+      const attributed = item.fileAttribution.filter((f) => f.attributed).length;
+      lines.push(
+        `${C.primary}│${C.reset}  ${C.bold}${rc.label}:${C.reset} ${rc.summary(attributed, item.fileAttribution.length)}`,
+      );
+      const matched = (item.authorEmails || []).filter((a) => a && a.matched).map((a) => display(a.email));
+      if (matched.length > 0) {
+        lines.push(`${C.primary}│${C.reset}    ${C.dim}${rc.confirmedLabel}: ${matched.join(', ')}${C.reset}`);
+      }
+    }
+
+    // Remediation prompt (issue 011): a clearly delimited copyable block.
+    const remediation = gate.showCertifyRemediation ? buildRemediationPrompt(item, lang) : null;
+    if (remediation) {
+      lines.push(`${C.primary}│${C.reset}`);
+      lines.push(`${C.primary}│${C.reset}  ${C.bold}${r.remediationHeading}${C.reset}`);
+      lines.push(`${C.primary}│${C.reset}  ${C.dim}${r.remediationHint}${C.reset}`);
+      lines.push(`${C.primary}│${C.reset}  ${C.dim}${RULE}${C.reset}`);
+      for (const l of remediation.split('\n')) lines.push(`${C.primary}│${C.reset}  ${display(l)}`);
+      lines.push(`${C.primary}│${C.reset}  ${C.dim}${RULE}${C.reset}`);
+    }
+
+    lines.push(`${C.primary}╰─${C.reset}`);
+    lines.push('');
+  }
+
+  return lines.join('\n').replace(/\n+$/, '');
+}
+
+module.exports = {
+  renderCertificationTerminal,
+  anyTruncated,
+  scoreBand,
+  skillLevelForScore,
+};

package/src/render-html.js

@@ -0,0 +1,140 @@
+'use strict';
+
+const { sanitizeRenderText } = require('./sanitize-network-text');
+
+// SHARED SHAPING FOR AGENT CARDS AND CERTIFICATION EVIDENCE — no HTML.
+
+function normalizeAgentName(name) {
+  return String(name || '').trim().toLowerCase().replace(/^[`'"*]+|[`'"*]+$/g, '');
+}
+
+// talents-ai-score, description-always-present (real-browser user feedback): TWO earlier approaches were tried and rejected before this one.
+
+function humanizeAgentName(name) {
+  const spaced = String(name || '').replace(/[-_]+/g, ' ').replace(/\s+/g, ' ').trim();
+  return spaced.replace(/^\S/, (c) => c.toUpperCase());
+}
+
+function cleanRawDescription(text) {
+  return String(text || '')
+    .replace(/\\[nrt]/g, ' ') // literal 2-char escape sequences, as typed in the source frontmatter
+    .replace(/[\n\r\t]/g, ' ') // real control characters (e.g. from a `|` block scalar)
+    .replace(/\|/g, ' ') // stray YAML block-scalar/table-like pipe artifacts
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+const CARD_EXCERPT_MAX_LEN = 160;
+
+function excerptForCard(text, maxLen = CARD_EXCERPT_MAX_LEN) {
+  if (!text) return text;
+  const sentenceMatch = text.match(/[.!?](?=\s|$)/);
+  const sentenceEndIdx = sentenceMatch ? sentenceMatch.index + 1 : null;
+
+  if (sentenceEndIdx !== null && sentenceEndIdx <= maxLen) {
+    return text.slice(0, sentenceEndIdx).trim();
+  }
+  if (text.length <= maxLen) return text;
+  return `${text.slice(0, maxLen).trim()}…`;
+}
+
+// Every card field that is TALENT-AUTHORED or came OFF THE WIRE, neutralised once, here — issue 055.
+
+// Every card field that is TALENT-AUTHORED or came OFF THE WIRE, neutralised once, here — issue 055.
+function sanitizeCardText(v) {
+  return typeof v === 'string' ? sanitizeRenderText(v) : v;
+}
+
+function sanitizeCardList(v) {
+  return Array.isArray(v) ? v.map((x) => (typeof x === 'string' ? sanitizeRenderText(x) : x)) : v;
+}
+
+function buildAgentCardTree(report, t) {
+  const agents = Array.isArray(report.agents) ? report.agents : [];
+  const synthesisAgents =
+    report.agentSynthesis && Array.isArray(report.agentSynthesis.agents) ? report.agentSynthesis.agents : [];
+  const synthesisByName = new Map(synthesisAgents.map((a) => [normalizeAgentName(a.name), a]));
+  const rawDescriptions = Array.isArray(report.agentDescriptions) ? report.agentDescriptions : [];
+  const rawDescByName = new Map(rawDescriptions.map((d) => [normalizeAgentName(d.name), d.description]));
+  const byName = new Set(agents.map((a) => a.name));
+
+  // ADR-016 agent evaluation: the ephemeral LLM definition-quality score (+ rationale) keyed by normalized name, and the LOCAL usage count keyed by exact name.
+  const evaluations =
+    report.agentEvaluation && Array.isArray(report.agentEvaluation.evaluations)
+      ? report.agentEvaluation.evaluations
+      : [];
+  // The agents the evaluation call answered about but did NOT cover — declared by
+  // the service and cross-checked against what was sent (src/agent-evaluation.js).
+  const omittedNames = new Set(
+    report.agentEvaluation && Array.isArray(report.agentEvaluation.omittedAgentNames)
+      ? report.agentEvaluation.omittedAgentNames.filter((n) => typeof n === 'string' && n)
+      : [],
+  );
+  const evalByName = new Map(evaluations.map((e) => [normalizeAgentName(e.name), e]));
+
+  const cards = agents.map((a) => {
+    const key = normalizeAgentName(a.name);
+    const synth = synthesisByName.get(key);
+    const parentKey = a.parent && byName.has(a.parent) && a.parent !== a.name ? a.parent : null;
+    const tools = Array.isArray(a.tools) ? a.tools : [];
+    // AI product derived from the agent's SOURCE (agent-org-chart#deriveAiProduct) — shown on the card in place of the LLM model.
+    const aiProduct = typeof a.aiProduct === 'string' && a.aiProduct ? a.aiProduct : null;
+
+    const ev = evalByName.get(key);
+    const evalPhrase =
+      ev && typeof ev.description === 'string' && ev.description.trim() ? ev.description.trim() : null;
+    const synthPhrase =
+      synth && typeof synth.whatItDoes === 'string' && synth.whatItDoes.trim() ? synth.whatItDoes.trim() : null;
+    const rawRaw = rawDescByName.get(key);
+    const rawPhrase =
+      typeof rawRaw === 'string' && rawRaw.trim() ? excerptForCard(cleanRawDescription(rawRaw)) : null;
+    const fallbackPhrase = t && t.html.agentDescriptionFromName ? t.html.agentDescriptionFromName(humanizeAgentName(a.name)) : null;
+    const whatItDoes = evalPhrase || synthPhrase || rawPhrase || fallbackPhrase;
+
+    // The numeric score AND the local usage signal were removed from footprint cards (user decision) — not carried onto the card.
+    const rationale = ev && typeof ev.rationale === 'string' && ev.rationale.trim() ? ev.rationale.trim() : null;
+    // v4 (agent classification): closest catalog agent + how it was matched, and 2-3 improvement tips.
+    const classification = ev
+      ? ev.classification && ev.classification.catalogId
+        ? ev.classification
+        : { catalogId: null, category: null, role: null, level: null, method: 'unclassified' }
+      : null;
+    const improvements = ev && Array.isArray(ev.improvements) ? ev.improvements : [];
+    // THE FOUR-VALUE EVALUATION STATE, RESOLVED HERE AND NOWHERE ELSE (2026-08-03).
+    const evaluationState = ev
+      ? (classification && classification.catalogId ? 'classified' : 'unclassified')
+      : (omittedNames.has(a.name) ? 'omitted' : 'not-evaluated');
+
+    // The single render-safety pass for both the HTML and the terminal card (see sanitizeCardText above).
+    return {
+      name: sanitizeCardText(a.name),
+      symbolicName: sanitizeCardText(synth && synth.symbolicName ? synth.symbolicName : null),
+      whatItDoes: sanitizeCardText(whatItDoes),
+      tools: sanitizeCardList(tools),
+      // The declared LLM model (issue 089).
+      model: sanitizeCardText(a.model),
+      aiProduct,
+      parent: sanitizeCardText(parentKey),
+      rationale: sanitizeCardText(rationale),
+      classification: classification
+        ? { ...classification, role: sanitizeCardText(classification.role) }
+        : classification,
+      improvements: sanitizeCardList(improvements),
+      // Issue 106's provenance rule, applied to the fourth state: ONE field, on the card both surfaces read, so the terminal and the shared report cannot disagree about the same agent.
+      evaluationState,
+    };
+  });
+
+  const childrenByParent = new Map();
+  for (const card of cards) {
+    if (!childrenByParent.has(card.parent)) childrenByParent.set(card.parent, []);
+    childrenByParent.get(card.parent).push(card);
+  }
+
+  return { childrenByParent, roots: childrenByParent.get(null) || [] };
+}
+
+// Maps an AI-product key (e.g. 'claude-code') to its display name via i18n,
+// falling back to the raw key. Product names are proper nouns (same es/en).
+
+module.exports = { buildAgentCardTree };

package/src/render-report-text.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const { renderTerminal } = require('./render-terminal');
+const { renderAiProfilePlain } = require('./render-ai-fluency');
+const { reportGateForIdentity } = require('./report-gating');
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+const stripAnsi = (s) => String(s).replace(ANSI_RE, '');
+
+function renderFullReportText(report, maturity, aiProfile, { lang = 'en', gate } = {}) {
+  const profile = renderAiProfilePlain(
+    aiProfile || { status: 'unavailable', preview: null },
+    { lang },
+  );
+  let terminal = '';
+  try {
+    terminal = stripAnsi(renderTerminal(report, maturity, lang, { gate: gate || reportGateForIdentity() }))
+      .replace(/[ \t]+$/gm, '')
+      .replace(/\n{3,}/g, '\n\n')
+      .trim();
+  } catch {
+    terminal = '';
+  }
+  return terminal ? `\`\`\`\n${terminal}\n\`\`\`\n\n${profile}` : profile;
+}
+
+module.exports = { renderFullReportText, stripAnsi };