shakers-cli 0.15.0 → 0.17.0

package/src/onboarding-funnel.js

@@ -5,7 +5,7 @@ const fs = require('fs');
 const path = require('path');
 const { getConfigDir } = require('./config-dir');
 
-// Names and values mirror works-frontend onboarding-funnel-enums.ts.
+// Names and values mirror the web onboarding funnel enums.
 
 const FLOW_VERSION = 'signup_new_works_v1';
 
@@ -48,10 +48,32 @@ const WORK_SITUATION_VALUES = Object.freeze({
   OTHER: 'other',
 });
 
+const PRE_ACCOUNT_EVENTS = Object.freeze({
+  start: { onboarding_step_viewed: [], onboarding_step_completed: ['time_on_step_ms'] },
+  account_creation: {
+    onboarding_step_viewed: ['auth_methods_offered'],
+    onboarding_step_errored: ['error_type'],
+    onboarding_step_exited: ['time_on_step_ms', 'exited_to_step_name', 'exited_to_step_index'],
+  },
+});
+const AUTH_METHODS = Object.freeze(['google', 'linkedin', 'email']);
+const PRE_ACCOUNT_VALUES = Object.freeze({
+  time_on_step_ms: (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0,
+  auth_methods_offered: (v) => Array.isArray(v) && v.every((m) => AUTH_METHODS.includes(m)),
+  error_type: (v) => ERROR_TYPES.includes(v),
+  exited_to_step_name: (v) => v === 'start',
+  exited_to_step_index: (v) => v === STEP_INDEX.start,
+});
+const COMMON_PROPERTIES = new Set(['step_name', 'step_index', 'flow_version', 'surface', 'mcp_client']);
+const MAX_EVENT_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const MAX_CLOCK_SKEW_MS = 5 * 60 * 1000;
+
 const ONCE_PER_STEP = new Set(['onboarding_step_viewed', 'onboarding_step_completed']);
 const MAX_EVENTS_PER_REQUEST = 50;
 const SEND_TIMEOUT_MS = 3000;
+const EXIT_FLUSH_CAP_MS = 1500;
 const DEVICE_FILE_NAME = 'analytics-device.json';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 function mcpClientFor(clientName) {
   const name = typeof clientName === 'string' ? clientName.toLowerCase() : '';
@@ -83,7 +105,8 @@ function rateTypes({ partTimeSelected, fullTimeSelected } = {}) {
 
 function errorTypeFor(reason) {
   const r = String(reason || '');
-  if (r === 'no-session' || r === 'no-hub-token' || r === 'http-401' || r === 'http-403') return 'auth';
+  if (r === 'no-session' || r === 'no-hub-token' || r === 'http-401' || r === 'http-403' || r === 'login-failed' || r.startsWith('google-')) return 'auth';
+  if (r === 'missing-fields' || r === 'weak-password') return 'validation';
   if (r === 'timeout') return 'timeout';
   if (r === 'no-endpoint') return 'server';
   if (r.startsWith('bad-') || r.startsWith('no-') || r === 'duplicate-language' || r === 'unresolved-languages') return 'validation';
@@ -126,12 +149,27 @@ function loadOrCreateDeviceId(env = process.env, { fs: fsImpl = fs } = {}) {
   }
 }
 
-async function defaultSend({ endpoint, events, hubAccessToken }) {
+async function postEvents(endpoint, body, headers) {
   const { postJsonWithTimeout } = require('./backend-request');
-  const res = await postJsonWithTimeout(endpoint, { events }, SEND_TIMEOUT_MS, 'POST', null, { Authorization: `Bearer ${hubAccessToken}` });
+  const res = await postJsonWithTimeout(endpoint, body, SEND_TIMEOUT_MS, 'POST', null, headers);
   return { ok: res.status >= 200 && res.status < 300, status: res.status };
 }
 
+function defaultSend({ endpoint, events, hubAccessToken }) {
+  return postEvents(endpoint, { events }, { Authorization: `Bearer ${hubAccessToken}` });
+}
+
+function defaultSendToAmplitude({ endpoint, apiKey, events }) {
+  return postEvents(endpoint, { api_key: apiKey, events }, null);
+}
+
+function isPreAccount(item) {
+  const step = PRE_ACCOUNT_EVENTS[item.properties.step_name];
+  const allowed = step && step[item.eventType];
+  return !!allowed && Object.entries(item.properties)
+    .every(([key, value]) => COMMON_PROPERTIES.has(key) || (allowed.includes(key) && PRE_ACCOUNT_VALUES[key](value)));
+}
+
 function defaultHubToken() {
   const { loadAuthSession, sessionStatus } = require('./auth-session-store');
   const session = loadAuthSession();
@@ -143,7 +181,9 @@ function createFunnel({
   hubToken = defaultHubToken,
   deviceId = () => loadOrCreateDeviceId(),
   endpoint = () => require('./config').getOnboardingEventsEndpoint(),
+  amplitude = () => require('./config').getAmplitudeIngestion(),
   send = defaultSend,
+  sendToAmplitude = defaultSendToAmplitude,
   now = () => Date.now(),
   uuid = () => crypto.randomUUID(),
 } = {}) {
@@ -156,8 +196,17 @@ function createFunnel({
   let active = false;
   let mcpClient = null;
   let cachedDeviceId;
+  let begunAt = null;
+  let lastCompletedAt = null;
+  let heldFrom = null;
   const seen = new Set();
   const inflight = new Set();
+  const viewedAt = new Map();
+
+  function stepTime(stepName) {
+    const since = viewedAt.has(stepName) ? viewedAt.get(stepName) : (lastCompletedAt ?? begunAt);
+    return since === null ? undefined : Math.max(0, now() - since);
+  }
 
   function track(eventType, stepName, properties = {}) {
     if (!active || !EVENT_TYPES.includes(eventType) || !STEP_INDEX[stepName]) return false;
@@ -166,44 +215,111 @@ function createFunnel({
       if (seen.has(key)) return false;
       seen.add(key);
     }
+    const at = now();
+    const own = cleanProperties(properties);
+    if (eventType === 'onboarding_step_viewed') viewedAt.set(stepName, at);
+    if (eventType === 'onboarding_step_completed') {
+      if (own.time_on_step_ms === undefined) {
+        const elapsed = stepTime(stepName);
+        if (elapsed !== undefined) own.time_on_step_ms = elapsed;
+      }
+      lastCompletedAt = at;
+    }
+    if (heldFrom === STEP_INDEX[stepName] && (eventType === 'onboarding_step_completed' || eventType === 'onboarding_step_skipped')) heldFrom = null;
     const common = { step_name: stepName, step_index: STEP_INDEX[stepName], flow_version: FLOW_VERSION, surface };
     if (surface === 'mcp') common.mcp_client = mcpClient || 'other';
-    pending.push({ eventType, insertId: uuid(), at: now(), seq: seq++, properties: { ...cleanProperties(properties), ...common } });
+    pending.push({ eventType, insertId: uuid(), at, seq: seq++, properties: { ...own, ...common } });
     return true;
   }
 
+  function currentDeviceId() {
+    if (cachedDeviceId === undefined) cachedDeviceId = safe(deviceId);
+    return cachedDeviceId;
+  }
+
   // Funnel order, each time strictly after the previous one sent.
   function stamp(batch) {
     const ordered = [...batch].sort((a, b) => a.properties.step_index - b.properties.step_index || a.seq - b.seq);
-    const id = cachedDeviceId === undefined ? (cachedDeviceId = safe(deviceId)) : cachedDeviceId;
-    return ordered.map((e) => {
-      lastTime = Math.max(e.at, lastTime + 1);
-      return { event_type: e.eventType, insert_id: e.insertId, time: lastTime, ...(id ? { device_id: id } : {}), properties: e.properties };
+    const latest = [];
+    let next = Infinity;
+    for (let i = ordered.length - 1; i >= 0; i--) {
+      const item = ordered[i];
+      latest[i] = item.time !== undefined ? item.time : Math.min(item.at, next - 1);
+      next = latest[i];
+    }
+    return ordered.map((item, i) => {
+      if (item.time === undefined) {
+        lastTime = Math.max(latest[i], lastTime + 1);
+        item.time = lastTime;
+      }
+      return { item, time: item.time };
     });
   }
 
-  function flush() {
-    if (!ready || !pending.length) return Promise.resolve();
+  function post(stamped, toWire, deliver) {
+    const sends = [];
+    for (let i = 0; i < stamped.length; i += MAX_EVENTS_PER_REQUEST) {
+      const chunk = stamped.slice(i, i + MAX_EVENTS_PER_REQUEST);
+      sends.push(Promise.resolve()
+        .then(() => deliver(chunk.map(toWire)))
+        .then((res) => !!(res && res.ok), () => false)
+        .then((ok) => (ok ? [] : chunk.map((e) => e.item))));
+    }
+    return Promise.all(sends).then((failed) => failed.flat());
+  }
+
+  function flushAsTalent() {
     const token = safe(hubToken);
     const url = safe(endpoint);
     // Never send under another account signed in since.
     if (!token || !url || accountOf(token) !== account) return Promise.resolve();
-    const events = stamp(pending);
-    pending = [];
-    const sends = [];
-    for (let i = 0; i < events.length; i += MAX_EVENTS_PER_REQUEST) {
-      sends.push(Promise.resolve().then(() => send({ endpoint: url, events: events.slice(i, i + MAX_EVENTS_PER_REQUEST), hubAccessToken: token })).catch(() => null));
-    }
-    const done = Promise.all(sends).then(() => undefined, () => undefined);
+    const batch = heldFrom === null ? pending : pending.filter((e) => e.properties.step_index < heldFrom);
+    if (!batch.length) return Promise.resolve();
+    pending = pending.filter((e) => !batch.includes(e));
+    const id = currentDeviceId();
+    const toWire = ({ item, time }) => ({ event_type: item.eventType, insert_id: item.insertId, time, ...(id ? { device_id: id } : {}), properties: item.properties });
+    return post(stamp(batch), toWire, (events) => send({ endpoint: url, events, hubAccessToken: token })).then(() => undefined);
+  }
+
+  function flushToAmplitude() {
+    const id = currentDeviceId();
+    const target = safe(amplitude);
+    if (!id || !UUID_RE.test(id) || !target) return Promise.resolve();
+    const batch = pending.filter((e) => !e.directFailed && isPreAccount(e));
+    if (!batch.length) return Promise.resolve();
+    pending = pending.filter((e) => !batch.includes(e));
+    const at = now();
+    const stamped = stamp(batch);
+    const inWindow = ({ time }) => time >= at - MAX_EVENT_AGE_MS && time <= at + MAX_CLOCK_SKEW_MS;
+    const outOfWindow = stamped.filter((e) => !inWindow(e)).map((e) => e.item);
+    const toWire = ({ item, time }) => ({ event_type: item.eventType, device_id: id, insert_id: item.insertId, time, event_properties: item.properties });
+    return post(stamped.filter(inWindow), toWire, (events) => sendToAmplitude({ endpoint: target.endpoint, apiKey: target.apiKey, events })).then((failed) => {
+      const waiting = [...outOfWindow, ...failed];
+      if (!waiting.length) return undefined;
+      for (const e of waiting) e.directFailed = true;
+      pending.push(...waiting);
+      return ready ? flush() : undefined;
+    });
+  }
+
+  function flush() {
+    if (!pending.length) return Promise.resolve();
+    const done = (ready ? flushAsTalent() : flushToAmplitude()).then(() => undefined, () => undefined);
     inflight.add(done);
     done.then(() => inflight.delete(done));
     return done;
   }
 
+  const idle = () => Promise.all([...inflight]).then(() => undefined);
+
   return {
     surface,
     begin() {
       seen.clear();
+      viewedAt.clear();
+      lastCompletedAt = null;
+      heldFrom = null;
+      begunAt = now();
       active = true;
     },
     get active() { return active; },
@@ -212,8 +328,13 @@ function createFunnel({
     viewed: (step, props) => track('onboarding_step_viewed', step, props),
     completed: (step, props) => track('onboarding_step_completed', step, props),
     skipped: (step, props) => track('onboarding_step_skipped', step, props),
+    stepTime: (step) => (active ? stepTime(step) : undefined),
+    holdUntil(step) {
+      if (active && STEP_INDEX[step]) heldFrom = STEP_INDEX[step];
+    },
     errored: (step, reason, props = {}) => track('onboarding_step_errored', step, { error_type: errorTypeFor(reason), ...props }),
-    identified() {
+    identified({ newAccount = true } = {}) {
+      if (!newAccount) pending = pending.filter((e) => !(e.eventType === 'onboarding_step_completed' && STEP_INDEX[e.properties.step_name] <= STEP_INDEX.account_creation));
       const token = safe(hubToken);
       if (!token) return Promise.resolve();
       account = accountOf(token);
@@ -221,7 +342,14 @@ function createFunnel({
       return flush();
     },
     flush,
-    idle: () => Promise.all([...inflight]).then(() => undefined),
+    idle,
+    settle(capMs = EXIT_FLUSH_CAP_MS) {
+      heldFrom = null;
+      flush();
+      let timer;
+      const cap = new Promise((resolve) => { timer = setTimeout(resolve, capMs); });
+      return Promise.race([idle(), cap]).then(() => clearTimeout(timer));
+    },
   };
 }
 
@@ -244,10 +372,13 @@ const NOOP_FUNNEL = Object.freeze({
   viewed: () => false,
   completed: () => false,
   skipped: () => false,
+  stepTime: () => undefined,
+  holdUntil() {},
   errored: () => false,
   identified: () => Promise.resolve(),
   flush: () => Promise.resolve(),
   idle: () => Promise.resolve(),
+  settle: () => Promise.resolve(),
 });
 
 module.exports = {
@@ -259,6 +390,8 @@ module.exports = {
   SOURCE_TYPES,
   ERROR_TYPES,
   MAX_EVENTS_PER_REQUEST,
+  EXIT_FLUSH_CAP_MS,
+  PRE_ACCOUNT_EVENTS,
   DEVICE_FILE_NAME,
   NOOP_FUNNEL,
   createFunnel,

package/src/open-file.js

@@ -2,7 +2,7 @@
 
 const { spawn } = require('child_process');
 
-// Zero-dependency, best-effort "open this file in the OS default app" (ADR-016, used by the `report` command to open the generated HTML in the browser).
+// Zero-dependency, best-effort "open this file in the OS default app" (used by the `report` command to open the generated HTML in the browser).
 function openPath(target) {
   let cmd;
   let args;

package/src/osc-link.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// OSC 8 terminal hyperlink helper (talents-ai-score, user request: links were printed as plain text and could NOT be clicked in iTerm2).
+// OSC 8 terminal hyperlink helper (links were printed as plain text and could NOT be clicked in iTerm2).
 
 const OSC = '\x1b]8;;';
 const ST = '\x1b\\';

package/src/portfolio-client.js

@@ -3,7 +3,7 @@
 const { postJsonWithTimeout, postMultipartWithTimeout } = require('./backend-request');
 const { reasonForError, WORKS_CODE_TO_REASON } = require('./skills-client');
 
-// Talent-portfolio client (talents-ai-score, ADR-059 — `start`'s "Add project to portfolio" route, src/start-add-portfolio.js).
+// Talent-portfolio client (`start`'s "Add project to portfolio" route, src/start-add-portfolio.js).
 
 const DEFAULT_TIMEOUT_MS = 20000;
 
@@ -155,10 +155,20 @@ async function requestUpdatePortfolioSkills(
   return { ok: true };
 }
 
+function normalizeDomain(raw) {
+  let s = String(raw || '').trim().toLowerCase();
+  if (!s) return '';
+  s = s.replace(/^https?:\/\//, '');
+  s = s.split('/')[0].split('?')[0].split('#')[0];
+  s = s.replace(/^www\./, '');
+  return s;
+}
+
 module.exports = {
   requestListPortfolios,
   requestDeclarePortfolio,
   requestDraftDescription,
   requestUpdatePortfolioSkills,
   WORKS_CODE_TO_REASON,
+  normalizeDomain,
 };

package/src/portfolio-git-info.js

@@ -2,7 +2,7 @@
 
 const { execFileSync } = require('child_process');
 
-// Git-derived signals for the "Add project to portfolio" route (talents-ai- score, ADR-059): the remote URL (step 4) and the first/last-commit date range (auto `startDate`/`endDate`).
+// Git-derived signals for the "Add project to portfolio" route: the remote URL (step 4) and the first/last-commit date range (auto `startDate`/`endDate`).
 
 const GIT_TIMEOUT_MS = 15000;
 

package/src/profile-flow.js

@@ -62,7 +62,7 @@ async function runProfile({ io, rawOut, session, catalog, opts = {}, deps = make
   const agentsCount = aiProfile ? aiProfile.agentsOnProfile : null;
 
   if (opts.json) {
-    (rawOut || ((s) => process.stdout.write(s)))(`${JSON.stringify({
+    rawOut(`${JSON.stringify({
       ok: true, mainRole, headline, completedProfilePercentage: completion, freelanceType,
       languageCodes, skillsCount, agentsCount, availability: availabilitySummary, aiProfile, pricing,
     }, null, 2)}\n`);

package/src/profile-switch.js

@@ -1,18 +1,11 @@
 'use strict';
 
 const fs = require('fs');
-const path = require('path');
 
-const { getConfigDir } = require('./config-dir');
 const { loadConfigFile, saveConfigFile, VALID_PROFILES } = require('./config');
 const { clearAuthSession } = require('./auth-session-store');
-
-function reportStatePath(env) {
-  return path.join(getConfigDir(env), 'report-state.json');
-}
-function consentStatePath(env) {
-  return path.join(getConfigDir(env), 'consent.json');
-}
+const { consentPath } = require('./share-consent-state');
+const { statePath } = require('./report-store');
 
 // Best-effort delete: a file that doesn't exist (nothing to purge yet, e.g.
 // a superadmin who never ran `usage` in this profile) is not a failure.
@@ -35,12 +28,12 @@ function switchProfile(target, env = process.env) {
   saveConfigFile(config, env);
 
   const purged = {
-    reportState: unlinkIfExists(reportStatePath(env)),
-    consent: unlinkIfExists(consentStatePath(env)),
+    reportState: unlinkIfExists(statePath(env)),
+    consent: unlinkIfExists(consentPath(env)),
     authSession: clearAuthSession(env),
   };
 
   return { ok: true, from, to: target, purged };
 }
 
-module.exports = { switchProfile, reportStatePath, consentStatePath };
+module.exports = { switchProfile };

package/src/render-certification.js

@@ -26,7 +26,7 @@ function anyTruncated(items) {
   return (items || []).some((i) => i && i.sampling && i.sampling.truncated);
 }
 
-// ADR-024 rubric dimension order (terminal).
+// 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).
@@ -37,7 +37,7 @@ function scoreBand(score) {
   return 'low';
 }
 
-// ADR-016: named skill level (by decision power, not points) shown INSTEAD of the numeric grade.
+// 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 };
@@ -67,18 +67,18 @@ 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.
+  // 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).
+  // the per-Skill results below are visually dominant.
   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.
+  // 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,
+  // 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;
@@ -114,10 +114,10 @@ function renderCertificationTerminal(certification, lang, opts = {}) {
       continue;
     }
 
-    // ADR-016: the HEADLINE is the named level (Middle/Senior/Expert) instead of the numeric 0-100 grade.
+    // 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.
+    // 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) {
@@ -138,7 +138,7 @@ function renderCertificationTerminal(certification, lang, opts = {}) {
       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
+    // 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;
@@ -151,7 +151,7 @@ function renderCertificationTerminal(certification, lang, opts = {}) {
       }
     }
 
-    // Remediation prompt (issue 011): a clearly delimited copyable block.
+    // Remediation prompt: a clearly delimited copyable block.
     const remediation = gate.showCertifyRemediation ? buildRemediationPrompt(item, lang) : null;
     if (remediation) {
       lines.push(`${C.primary}│${C.reset}`);

package/src/render-html.js

@@ -8,7 +8,7 @@ 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.
+// TWO earlier approaches were tried and rejected before this one.
 
 function humanizeAgentName(name) {
   const spaced = String(name || '').replace(/[-_]+/g, ' ').replace(/\s+/g, ' ').trim();
@@ -38,9 +38,9 @@ function excerptForCard(text, maxLen = CARD_EXCERPT_MAX_LEN) {
   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.
 
-// 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.
 function sanitizeCardText(v) {
   return typeof v === 'string' ? sanitizeRenderText(v) : v;
 }
@@ -58,7 +58,7 @@ function buildAgentCardTree(report, t) {
   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.
+  // 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
@@ -111,7 +111,7 @@ function buildAgentCardTree(report, t) {
       symbolicName: sanitizeCardText(synth && synth.symbolicName ? synth.symbolicName : null),
       whatItDoes: sanitizeCardText(whatItDoes),
       tools: sanitizeCardList(tools),
-      // The declared LLM model (issue 089).
+      // The declared LLM model.
       model: sanitizeCardText(a.model),
       aiProduct,
       parent: sanitizeCardText(parentKey),
@@ -120,7 +120,7 @@ function buildAgentCardTree(report, t) {
         ? { ...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.
+      // The 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,
     };
   });

package/src/render-report-text.js

@@ -14,7 +14,7 @@ function renderFullReportText(report, maturity, aiProfile, { lang = 'en', gate }
   );
   let terminal = '';
   try {
-    terminal = stripAnsi(renderTerminal(report, maturity, lang, { gate: gate || reportGateForIdentity() }))
+    terminal = stripAnsi(renderTerminal(report, maturity, lang, { gate: { ...(gate || reportGateForIdentity()), showRoadmap: false } }))
       .replace(/[ \t]+$/gm, '')
       .replace(/\n{3,}/g, '\n\n')
       .trim();

package/src/render-sheet.js

@@ -21,7 +21,7 @@ function aiFluencyHtml(report, lang) {
 
 const TEMPLATE_PATH = path.join(__dirname, 'templates', 'report-sheet.html');
 let _tpl = null;
-// Issue 098: the template's comments are OURS and this document is the one the talent shares, so they are swept here — at load, before any talent data is in the string.
+// The template's comments are OURS and this document is the one the talent shares, so they are swept here — at load, before any talent data is in the string.
 function template() {
   if (_tpl == null) _tpl = stripTemplateComments(fs.readFileSync(TEMPLATE_PATH, 'utf8'));
   return _tpl;
@@ -54,7 +54,7 @@ function tierName(fp, t) {
 
 function bandClass(b) { return b === 'high' ? 'band-high' : b === 'mid' ? 'band-mid' : 'band-low'; }
 
-// Localized Setup Level label from the drawer payload (ADR-016): prefer the
+// Localized Setup Level label from the drawer payload: prefer the
 // i18n `setupLevels` catalog by key, fall back to the label baked into `fp`.
 function setupLabel(fp, t) {
   const key = (fp.setup && fp.setup.key) || 'none';
@@ -65,7 +65,7 @@ function setupLabel(fp, t) {
 function heroHtml(fp, c, t) {
   const rank = (fp.setup && typeof fp.setup.rank === 'number') ? fp.setup.rank : 0;
   const label = setupLabel(fp, t);
-  // Four pips: Not certified + S1/S2/S3, current filled (ADR-016).
+  // Four pips: Not certified + S1/S2/S3, current filled.
   const pills = Array.from({ length: 4 }, (_, i) => `<span class="${i <= rank ? 'on' : ''}"></span>`).join('');
   const chipK = esc(fp.tier.key && fp.tier.key !== 'none' ? fp.tier.key : (fp.setup && fp.setup.code) || '');
   return `<div class="card reveal">
@@ -86,7 +86,7 @@ function heroHtml(fp, c, t) {
   </div>`;
 }
 
-// The Setup Level ladder (ADR-016), with each rung's tiers and short meaning inline — meanings from the localized i18n `setupLevels` catalog (never invented).
+// The Setup Level ladder, with each rung's tiers and short meaning inline — meanings from the localized i18n `setupLevels` catalog (never invented).
 function ladderHtml(fp, c, t) {
   const cur = (fp.setup && typeof fp.setup.rank === 'number') ? fp.setup.rank : 0;
   const catalog = (t && t.setupLevels) || {};
@@ -111,7 +111,7 @@ function chipsCard(title, sub, items, withDot) {
   return `<div class="card reveal"><h3>${esc(title)}</h3><p class="sub">${esc(sub)}</p><div class="chips">${body}</div></div>`;
 }
 
-// MCP SERVICES (issue 110).
+// MCP SERVICES.
 function mcpCard(mcp, c) {
   const services = (mcp && Array.isArray(mcp.services) ? mcp.services : []);
   const unidentified = (mcp && typeof mcp.unidentified === 'number') ? mcp.unidentified : 0;
@@ -129,17 +129,17 @@ function mcpCard(mcp, c) {
   return `<div class="card reveal"><h3>${esc(c.mcpT)}</h3><p class="sub">${esc(c.mcpS)}</p><div class="chips">${chips}</div>${note}</div>`;
 }
 
-// DETECTED AGENTS, left column (issue 089).
+// DETECTED AGENTS, left column.
 function agentRow(a, c, t) {
   const cats = (t.classification && t.classification.categories) || {};
   const model = a.model ? `<span class="model">${esc(a.model)}</span>` : `<span class="model" style="opacity:.6">${esc(c.agentNoModel)}</span>`;
   // The category is the agent → catalog-seed association (per agent), not the Talent's tier.
   const catLabel = a.category ? (cats[a.category] || sanitizeRenderText(a.category)) : null;
   // ONE COLOUR PER CATEGORY (user request), and THREE distinct facts, not two: - a known catalog category -> its own colour token (`.cat-developer` …).
-  // FOUR facts now, not three (issue 120).
+  // FOUR facts now, not three.
   const coloured = !!(a.category && cats[a.category] && !isFloorCategory(a.category));
   const catClass = coloured ? `cat cat-${a.category}` : 'cat cat-none';
-  // Issue 106: the empty badge says WHICH kind of empty it is.
+  // The empty badge says WHICH kind of empty it is.
   const cls = t.classification || {};
   const emptyLabel = a.evaluationState === 'omitted'
     ? cls.agentEvalOmitted
@@ -163,7 +163,7 @@ function agentRow(a, c, t) {
 
 function agentsCard(agents, c, t) {
   const list = Array.isArray(agents) ? agents : [];
-  // SAID ONCE, VISIBLY (issue 106): if nobody was evaluated, the reason the badges are empty is that the run could not classify, not that the agents have no category.
+  // SAID ONCE, VISIBLY: if nobody was evaluated, the reason the badges are empty is that the run could not classify, not that the agents have no category.
   const noneEvaluated = list.length > 0 && list.every((a) => a.evaluated === false);
   // AND THE PARTIAL RUN, NAMED (2026-08-03).
   const omitted = list.filter((a) => a.evaluationState === 'omitted').map((a) => a.name);
@@ -196,7 +196,7 @@ function renderSheet(project, lang, gate = DEFAULT_REPORT_GATE) {
   const t = getCatalog(L);
   const c = t.sheet;
   const hasFoot = !!(project && project.footprint && project.footprint.report);
-  // `t` is passed now (issue 089): the drawer's agent rows use the catalog for the
+  // `t` is passed now: the drawer's agent rows use the catalog for the
   // description fallback and nothing else — it stays optional for the graph report.
   const fp = hasFoot ? buildFootprintDrawer(project.footprint.report, project.footprint.maturity, t) : null;
   // buildCertsPayload returns null when the project has no Skill certs — the sheet still renders both columns, so normalize to an empty list (clean state).

package/src/render-terminal.js

@@ -13,7 +13,7 @@ const {
   printRoadmap,
 } = require('./terminal-sections');
 
-// talents-ai-score: terminal parity with the HTML report.
+// Terminal parity with the HTML report.
 
 // `lang` ('es'|'en', see src/i18n.js) decides the text catalog.
 function renderTerminal(report, maturity, lang, opts = {}) {
@@ -21,10 +21,10 @@ function renderTerminal(report, maturity, lang, opts = {}) {
   const lines = [];
   const p = (s = '') => lines.push(s);
 
-  // issue 123 / ADR-044: the ONE identity gate.
+  // The ONE identity gate.
   const gate = opts.gate || DEFAULT_REPORT_GATE;
 
-  // ADR-016: Setup Level (S1-S3 / Not certified) replaces the 0-4 band label.
+  // Setup Level (S1-S3 / Not certified) replaces the 0-4 band label.
   const setupKey = (maturity.setupLevel && maturity.setupLevel.key) || 'none';
   const setupLabel = (t.setupLevels && t.setupLevels[setupKey] && t.setupLevels[setupKey].label) || setupKey;
 
@@ -47,7 +47,7 @@ function renderTerminal(report, maturity, lang, opts = {}) {
   sep(p);
   const tierName = (maturity.tierKey && t.tierNames[maturity.tierKey]) || maturity.tierName || '';
   const tierBit = maturity.tierKey ? t.terminal.tierInline(maturity.tierKey, tierName) : '';
-  // This report's ONE headline (dueño, 2026-08-11): the Setup Level IS the evaluation's main result, so it gets `accent` (lime) — and nothing else on this screen does.
+  // This report's ONE headline: the Setup Level IS the evaluation's main result, so it gets `accent` (lime) — and nothing else on this screen does.
   const setupColor = setupKey === 'none' ? c.white : c.accent;
   p(`  ${c.bold}${setupColor}${t.terminal.setupLevel(setupLabel)}${c.reset}${c.muted}${tierBit}${c.reset}`);
   p(`  ${c.primary}${bar(maturity.score)}${c.reset} ${c.dim}${maturity.score}/100${c.reset}`);
@@ -77,7 +77,7 @@ function renderTerminal(report, maturity, lang, opts = {}) {
     }
   }
 
-  // 4b. MCP services (issue 110) — ALWAYS printed, empty state included, because
+  // 4b. MCP services — ALWAYS printed, empty state included, because
   // its absence is a tier criterion the talent needs to know about.
   sep(p);
   printMcpServices(report, t, p);
@@ -105,5 +105,5 @@ function renderTerminal(report, maturity, lang, opts = {}) {
   return lines.join('\n');
 }
 
-// `wrap` is re-exported for its own unit test (issue 087): it is the one piece of the formatting with edge cases worth pinning directly.
+// `wrap` is re-exported for its own unit test: it is the one piece of the formatting with edge cases worth pinning directly.
 module.exports = { renderTerminal, wrap, printAgents };