shakers-cli-beta 0.8.0-beta.0

package/src/terminal-agents.js

@@ -0,0 +1,199 @@
+'use strict';
+
+// The agents + activity blocks of the terminal report, extracted from src/render-terminal.js (structure refactor, issue 020).
+
+const { label } = require('./i18n');
+const { buildAgentCardTree } = require('./render-html');
+const { sanitizeRenderText } = require('./sanitize-network-text');
+const { MODEL_CALL, REASON, callFailed, callPartial, callTimedOut, modelCall, omittedByCall } = require('./model-call-record');
+const { isFloorCategory } = require('./agent-category');
+const { DEFAULT_REPORT_GATE } = require('./report-gating');
+const { c, wrap, summarize } = require('./terminal-format');
+const { detectedToolNames } = require('./detected-tools');
+
+// agents (ADR-016: one line per agent) As SIMPLE as possible: ONE line per agent.
+
+// AI product (from the source, e.g. Claude Code) shown in place of the LLM model.
+function agentProductLabel(card, t) {
+  if (!card.aiProduct) return '';
+  const map = (t.html && t.html.aiProducts) || {};
+  return map[card.aiProduct] || card.aiProduct;
+}
+
+function agentLine(card, depth, t) {
+  const indent = '  '.repeat(depth);
+  // Root = a filled bullet; every deeper level = that many stacked down-arrows.
+  const marker = depth === 0 ? `${c.success}●${c.reset}` : `${c.primary}${'↓'.repeat(depth)}${c.reset}`;
+  // card.symbolicName is agent-synthesis (LLM, ADR-010) content; card.name is
+  // the local, deterministic agent id — only the former needs stripping.
+  const title = card.symbolicName
+    ? `${sanitizeRenderText(card.symbolicName)} ${c.muted}(${card.name})${c.reset}`
+    : card.name;
+  // No model, no usage (user decision) — show the AI PRODUCT instead of the model.
+  const product = agentProductLabel(card, t);
+  const productBit = product ? ` ${c.dim}[${product}]${c.reset}` : '';
+  return `  ${indent}${marker} ${c.bold}${c.white}${title}${c.reset}${productBit}`;
+}
+
+// The agent's wired tools/integrations = the per-card "technologies" (user wants
+// MORE tech visible). One dim line under the agent; deduped; omitted when empty.
+function agentToolsLine(card, depth) {
+  const tools = Array.from(new Set((card.tools || []).filter((x) => typeof x === 'string' && x.trim())));
+  if (tools.length === 0) return null;
+  const indent = '  '.repeat(depth);
+  return `  ${indent}   ${c.muted}${tools.join(' · ')}${c.reset}`;
+}
+
+// A compact, dim, summarized description under each agent (frontmatter `description` via buildAgentCardTree's whatItDoes), truncated to ~90 chars on a clean boundary.
+function agentDescLine(card, depth) {
+  if (!card.whatItDoes) return null;
+  const indent = '  '.repeat(depth);
+  return `  ${indent}   ${c.dim}${summarize(sanitizeRenderText(card.whatItDoes), 90)}${c.reset}`;
+}
+
+function agentClassLine(card, depth, t) {
+  const indent = '  '.repeat(depth);
+  const cc = t.classification;
+  // FOURTH STATE (2026-08-03): the evaluation SUCCEEDED and left this agent out.
+  if (card.evaluationState === 'omitted') {
+    return `  ${indent}   ${c.warning}${cc.agentEvalOmitted}${c.reset}`;
+  }
+  // No evaluation ran for this agent → no classification line.
+  if (!card.classification) return '';
+  if (card.classification.method === 'unclassified' || !card.classification.catalogId) {
+    return `  ${indent}   ${c.muted}${cc.noCategory}${c.reset}`;
+  }
+  const { category, role, level } = card.classification;
+  const catLabel = (category && cc.categories[category]) || sanitizeRenderText(category);
+  const levelLabel = (level && cc.levels[level]) || sanitizeRenderText(level);
+  const bits = [];
+  // The FLOOR category is dimmed, not accented (issue 120).
+  const floor = isFloorCategory(category);
+  if (catLabel) {
+    bits.push(floor ? `${c.dim}${catLabel}${c.reset}` : `${c.primary}${catLabel}${c.reset}`);
+  }
+  // The floor's ROLE is dropped, and it is not a style preference.
+  if (role && !floor) bits.push(`${c.white}${sanitizeRenderText(role)}${c.reset}`);
+  if (levelLabel) bits.push(`${c.dim}${levelLabel}${c.reset}`);
+  return `  ${indent}   ${bits.join(`${c.muted} · ${c.reset}`)}`;
+}
+
+// v4 (report req 3): the "how to improve" tips, one per line under the agent.
+function agentImprovementLines(card, depth, t) {
+  const tips = Array.isArray(card.improvements) ? card.improvements : [];
+  if (tips.length === 0) return [];
+  const indent = '  '.repeat(depth);
+  const out = [`  ${indent}   ${c.dim}${t.classification.improvementsHeading}${c.reset}`];
+  for (const tip of tips) out.push(`  ${indent}     ${c.muted}- ${sanitizeRenderText(tip)}${c.reset}`);
+  return out;
+}
+
+function printActivity(report, t, p) {
+  const s = report && report.sessions ? report.sessions : null;
+  const g = report && report.gitActivity ? report.gitActivity : null;
+  const w = report && report.workStreams ? report.workStreams : null;
+  if (!s && !g && !w) return false;
+
+  const a = t.terminal.activity;
+  p(`  ${c.bold}${a.heading}${c.reset}`);
+  if (Array.isArray(report.analyzedRepos) && report.analyzedRepos.length) {
+    p(`  ${c.dim}${a.repos(report.analyzedRepos.map(sanitizeRenderText).join(', '))}${c.reset}`);
+  }
+  if (s) {
+    const sub =
+      s.subagentRunCount > 0
+        ? ` ${c.muted}·${c.reset} ${a.subagents(s.subagentRunCount)}`
+        : '';
+    p(`  ${c.success}●${c.reset} ${a.sessions(s.sessionCount)}${sub}`);
+    if (typeof s.activeHours === 'number' && s.activeHours > 0) {
+      p(`  ${c.success}●${c.reset} ${a.hours(s.activeHours)}`);
+    }
+  }
+  if (g) {
+    p(
+      `  ${c.success}●${c.reset} ${a.commits(g.authoredCommitCount, g.commitCount)} ${c.muted}·${c.reset} ${a.lines(g.linesAdded, g.linesDeleted)} ${c.muted}·${c.reset} ${a.velocity(g.velocity)}`,
+    );
+  }
+  if (w) {
+    p(
+      `  ${c.success}●${c.reset} ${a.workStreams(w.streamCount, w.multiDayStreams, w.maxStreamSpanDays)}`,
+    );
+  }
+  // Traction (ADR-039): recency-windowed signals from the local scan; agentsOnProfile
+  // is hub-only, shown only when the ai-profile preview has already been fetched.
+  const tr = tractionParts(report, s, a);
+  if (tr.length) p(`  ${c.success}●${c.reset} ${a.tractionLabel}: ${tr.join(' · ')}`);
+  return true;
+}
+
+function tractionParts(report, s, a) {
+  const parts = [];
+  if (s && typeof s.sessions90d === 'number') parts.push(a.tSessions(s.sessions90d));
+  if (s && typeof s.activeDaysPerWeek === 'number') parts.push(a.tDays(s.activeDaysPerWeek));
+  const detected = report && report.agentCounts ? report.agentCounts.agents : null;
+  const onProfile = report && report.aiWorkPreview && report.aiWorkPreview.traction
+    ? report.aiWorkPreview.traction.agentsOnProfile : null;
+  if (typeof detected === 'number') parts.push(a.tAgents(detected, typeof onProfile === 'number' ? onProfile : null));
+  const tools = detectedToolNames(report && report.tools);
+  if (tools.length) parts.push(a.tTools(tools.join(', ')));
+  return parts;
+}
+
+function printAgents(report, t, p, gate = DEFAULT_REPORT_GATE) {
+  const { childrenByParent, roots } = buildAgentCardTree(report, t);
+  // The names the evaluation left out.
+  const omittedNames = new Set(omittedByCall(report, MODEL_CALL.EVALUATION));
+  p(`  ${c.bold}${label(t.html.diagramHeading, 'Agents')}${c.reset}`);
+  if (!roots.length) {
+    p(`  ${c.muted}  ${label(t.html.agentsEmpty, 'No configured AI agents detected.')}${c.reset}`);
+    p();
+    return;
+  }
+  // THE ROOT THE AGENTS HANG FROM (issue 086 — restored, not invented).
+  p(`  ${c.muted}${label(t.html.orchestratorLabel, 'Orchestrator')}${c.reset}`);
+  const visited = new Set();
+  const walk = (card, depth) => {
+    if (visited.has(card.name)) return;
+    visited.add(card.name);
+    p(agentLine(card, depth, t));
+    const desc = agentDescLine(card, depth);
+    if (desc) p(desc);
+    const toolsLine = agentToolsLine(card, depth);
+    if (toolsLine) p(toolsLine);
+    const classLine = agentClassLine(card, depth, t);
+    if (classLine) p(classLine);
+    if (gate.showAgentSuggestions) {
+      for (const line of agentImprovementLines(card, depth, t)) p(line);
+    }
+    const children = childrenByParent.get(card.name) || [];
+    for (const child of children) walk(child, depth + 1);
+  };
+  for (const root of roots) walk(root, 0);
+  // A single note when the local usage history is unavailable, so a blank usage
+  // column reads as "no local history" rather than "never used".
+  if (report.agentUsage && report.agentUsage.available === false) {
+    p(`  ${c.dim}${t.terminal.agentUsageUnavailable}${c.reset}`);
+  }
+  // A PARTIAL RUN SAYS SO, AND BY NAME (2026-08-03).
+  if (callPartial(report, MODEL_CALL.EVALUATION)) {
+    const names = [...omittedNames].map(sanitizeRenderText).join(', ');
+    for (const line of wrap(t.classification.agentsEvalPartial(names, omittedNames.size))) p(`  ${c.dim}${line}${c.reset}`);
+  }
+  // THE CASE THAT SAID NOTHING AT ALL (issue 116).
+  if (callFailed(report, MODEL_CALL.EVALUATION)) {
+    const detected = Array.isArray(report.agents) ? report.agents.length : 0;
+    const cls = t.classification;
+    // FOUR outcomes, because they ask the talent to do different things — and ADR-042 is what made three of them distinguishable at all.
+    const record = modelCall(report, MODEL_CALL.EVALUATION);
+    const reason = record && record.reason;
+    let notice;
+    if (callTimedOut(report, MODEL_CALL.EVALUATION)) notice = cls.agentsEvalTimedOut(detected);
+    else if (reason === REASON.NETWORK) notice = cls.agentsEvalUnreachable;
+    else if (reason === REASON.HTTP) notice = cls.agentsEvalErrored;
+    else notice = cls.agentsEvalMissing;
+    for (const line of wrap(notice)) p(`  ${c.dim}${line}${c.reset}`);
+  }
+  p();
+}
+
+module.exports = { printAgents, printActivity };

package/src/terminal-format.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const { palette } = require('./ansi');
+const { BRAND_ANSI } = require('./brand-ansi');
+
+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,
+  muted: BRAND_ANSI.muted,
+  white: '\x1b[97m',
+});
+
+function bar(score, width = 24) {
+  const filled = Math.round((score / 100) * width);
+  return '█'.repeat(filled) + '░'.repeat(width - filled);
+}
+
+// ADR-016: a light visual break between the reordered sections — a dim rule
+// with air around it, keeping the branded ANSI look and zero deps.
+function sep(p) {
+  p();
+  p(`  ${c.muted}${'─'.repeat(46)}${c.reset}`);
+  p();
+}
+
+// WRAPPING, added for issue 087.
+const WRAP_COLS = 76;
+
+function wrap(text, width = WRAP_COLS) {
+  const s = String(text || '').trim().replace(/\s+/g, ' ');
+  if (!s) return [];
+  const out = [];
+  let line = '';
+  for (const word of s.split(' ')) {
+    if (!line) line = word;
+    else if (`${line} ${word}`.length <= width) line += ` ${word}`;
+    else { out.push(line); line = word; }
+  }
+  if (line) out.push(line);
+  return out;
+}
+
+// One step, wrapped, with its estimate.
+function printStepLines(p, marker, text, estimate) {
+  const indent = ' '.repeat(4 + marker.length + 1);
+  const width = WRAP_COLS - indent.length;
+  const lines = wrap(text, width);
+  if (lines.length === 0) return;
+  // The estimate is measured, not just appended.
+  const plain = estimate ? ` (${estimate})` : '';
+  const coloured = estimate ? ` ${c.dim}(${estimate})${c.reset}` : '';
+  const last = lines.length - 1;
+  const fits = !estimate || lines[last].length + plain.length <= width;
+  lines.forEach((line, i) => {
+    const head = i === 0 ? `    ${marker} ` : indent;
+    p(`${head}${line}${i === last && fits ? coloured : ''}`);
+  });
+  if (estimate && !fits) p(`${indent}${c.dim}(${estimate})${c.reset}`);
+}
+
+// A LABELLED BLOCK: the label on its own dim line, the value wrapped and indented under it.
+function labelledBlock(p, label, value, indent = '    ') {
+  if (!value) return;
+  p(`  ${c.dim}${label}${c.reset}`);
+  for (const line of wrap(value, WRAP_COLS - indent.length)) p(`${indent}${c.muted}${line}${c.reset}`);
+}
+
+// Terminal-SUMMARIZE (user feedback, 2026-07-16): the earlier condense (commit 465badb) over-trimmed — it left the terminal as headings + copyable prompts with the prose stripped out.
+function summarize(text, max = 140) {
+  const s = String(text || '').trim().replace(/\s+/g, ' ');
+  if (s.length <= max) return s;
+  const slice = s.slice(0, max);
+  const lastStop = slice.lastIndexOf('. ');
+  if (lastStop >= max * 0.5) return slice.slice(0, lastStop + 1);
+  const lastSpace = slice.lastIndexOf(' ');
+  return (lastSpace > 0 ? slice.slice(0, lastSpace) : slice).replace(/[\s,;:.]+$/, '') + '…';
+}
+
+module.exports = { c, bar, sep, wrap, printStepLines, labelledBlock, summarize, WRAP_COLS };

package/src/terminal-progress.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const TICK_MS = 80;
+
+function isInteractive(stream) {
+  return !!(stream && stream.isTTY);
+}
+
+const ERASE_LINE = '\r\x1b[2K\r';
+
+// Runs a SYNCHRONOUS `fn` while showing `label` as a static status line.
+// Never animates (see header note: a blocking call can't yield ticks).
+function withStaticStatus(label, fn, stream = process.stderr) {
+  if (!isInteractive(stream)) {
+    stream.write(`  ${label}\n`);
+    return fn();
+  }
+  stream.write(`  ${label}`);
+  try {
+    return fn();
+  } finally {
+    stream.write(ERASE_LINE);
+  }
+}
+
+// Runs an ASYNC `task` (a zero-arg function returning a Promise) while showing an animated spinner with `label`.
+async function withSpinner(label, task, stream = process.stderr) {
+  if (!isInteractive(stream)) {
+    stream.write(`  ${label}\n`);
+    return task();
+  }
+  let frame = 0;
+  stream.write(`\r  ${FRAMES[0]} ${label}`);
+  const timer = setInterval(() => {
+    frame = (frame + 1) % FRAMES.length;
+    stream.write(`\r  ${FRAMES[frame]} ${label}`);
+  }, TICK_MS);
+  try {
+    return await task();
+  } finally {
+    clearInterval(timer);
+    stream.write(ERASE_LINE);
+  }
+}
+
+// Manual spinner for a wait whose END isn't a single awaitable (e.g. streaming:
+// spin until the FIRST token arrives). Returns an idempotent `stop()` that
+// clears the line. On a non-TTY it prints the label once and `stop()` is a no-op.
+function startSpinner(label, stream = process.stderr) {
+  if (!isInteractive(stream)) {
+    stream.write(`  ${label}\n`);
+    return () => {};
+  }
+  let frame = 0;
+  stream.write(`\r  ${FRAMES[0]} ${label}`);
+  const timer = setInterval(() => {
+    frame = (frame + 1) % FRAMES.length;
+    stream.write(`\r  ${FRAMES[frame]} ${label}`);
+  }, TICK_MS);
+  let stopped = false;
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(timer);
+    stream.write(ERASE_LINE);
+  };
+}
+
+const PHASE_MS = 8000;
+
+// Pure: which phase index is active after `elapsedMs`.
+function phaseAt(phaseCount, elapsedMs, phaseMs = PHASE_MS) {
+  if (!(phaseCount > 0)) return 0;
+  if (!(elapsedMs > 0) || !(phaseMs > 0)) return 0;
+  const i = Math.floor(elapsedMs / phaseMs);
+  return i >= phaseCount ? phaseCount - 1 : i;
+}
+
+async function withPhasedSpinner(phases, task, { stream = process.stderr, phaseMs = PHASE_MS, tickMs = TICK_MS } = {}) {
+  const list = (Array.isArray(phases) ? phases : [phases]).filter((s) => typeof s === 'string' && s.length > 0);
+  const first = list[0] || '';
+  if (!isInteractive(stream)) {
+    if (first) stream.write(`  ${first}\n`);
+    return task();
+  }
+  const start = Date.now();
+  let frame = 0;
+  let maxLen = 0;
+  const render = () => {
+    const copy = list[phaseAt(list.length, Date.now() - start, phaseMs)] || first;
+    const line = `  ${FRAMES[frame]} ${copy}`;
+    maxLen = Math.max(maxLen, line.length);
+    stream.write(`\r${line.padEnd(maxLen)}`); // padEnd clears a longer previous phase's tail
+  };
+  render();
+  const timer = setInterval(() => { frame = (frame + 1) % FRAMES.length; render(); }, tickMs);
+  try {
+    return await task();
+  } finally {
+    clearInterval(timer);
+    stream.write(ERASE_LINE);
+  }
+}
+
+module.exports = { withStaticStatus, withSpinner, startSpinner, withPhasedSpinner, phaseAt, isInteractive };

package/src/terminal-sections.js

@@ -0,0 +1,219 @@
+'use strict';
+
+// The MCP-services, tier-analysis, progression-ladder and tier-roadmap sections of the terminal report, extracted from src/render-terminal.js (structure refactor, issue 020).
+
+const { getRoadmapEntry } = require('./roadmap-content');
+const { analyzeTier, buildLadder } = require('./tier-analysis');
+const { mergeRoadmapPersonalization } = require('./roadmap-personalization');
+const { buildImplementationPrompt } = require('./roadmap-prompt');
+const { sanitizeRenderText } = require('./sanitize-network-text');
+const { callFailed, MODEL_CALL } = require('./model-call-record');
+const { projectNextTier } = require('./tier-projection');
+const { c, sep, wrap, summarize, labelledBlock, printStepLines } = require('./terminal-format');
+
+function printMcpServices(report, t, p) {
+  const mcp = report && report.mcp ? report.mcp : null;
+  const services = mcp && Array.isArray(mcp.services) ? mcp.services : [];
+  const unidentified = mcp && typeof mcp.unidentified === 'number' ? mcp.unidentified : 0;
+
+  p(`  ${c.bold}${t.html.mcpHeading}${c.reset}`);
+  if (services.length === 0 && unidentified === 0) {
+    for (const line of wrap(t.html.mcpEmpty)) p(`  ${c.muted}${line}${c.reset}`);
+    p();
+    return;
+  }
+  if (services.length) {
+    const shown = services.map((s) => `${sanitizeRenderText(s.label)}${s.count > 1 ? ` ×${s.count}` : ''}`);
+    p(`  ${c.primary}${shown.join(`${c.reset}${c.muted} · ${c.reset}${c.primary}`)}${c.reset}`);
+  }
+  // Stated, never omitted: the list has to account for every server the tier
+  // counted, or the screen shows two different numbers for one set (issue 096).
+  if (unidentified > 0) {
+    for (const line of wrap(t.html.mcpUnidentified(unidentified))) p(`  ${c.dim}${line}${c.reset}`);
+  }
+  p();
+}
+
+// tier analysis: why this tier (summarized) Same deterministic source (src/tier-analysis.js) as the HTML report.
+
+function printTierAnalysis(report, t, p) {
+  const analysis = analyzeTier(report, t);
+  const tt = t.tierAnalysis;
+
+  p(`  ${c.bold}${tt.heading}${c.reset}`);
+  // Keep the first sentence of the intro ("Your current tier is X (Name).") —
+  // the rest explains the engine mechanics at length, which stays HTML-only.
+  const introFull = tt.intro(analysis.tierKey, analysis.tierName);
+  const firstStop = introFull.indexOf('. ');
+  const intro = firstStop >= 0 ? introFull.slice(0, firstStop + 1) : introFull;
+  p(`  ${c.muted}${intro}${c.reset}`);
+
+  // Summarized met-criteria checklist (reintroduced 2026-07-16): the criteria
+  // already satisfied, one concise line each. Full-length wording stays in HTML.
+  if (Array.isArray(analysis.metCriteria) && analysis.metCriteria.length) {
+    p(`  ${c.dim}${tt.metHeading}${c.reset}`);
+    analysis.metCriteria.forEach((m) => p(`    ${c.success}✓${c.reset} ${c.muted}${summarize(m.text, 110)}${c.reset}`));
+  }
+
+  if (analysis.blockingCriterion) {
+    p(`  ${c.bold}${c.warning}${tt.blockingLabel}${c.reset}`);
+    p(`  ${c.white}${analysis.blockingCriterion}${c.reset}`);
+  } else {
+    p(`  ${c.white}${tt.maxTierNote}${c.reset}`);
+  }
+  p();
+}
+
+function ladderMark(status) {
+  if (status === 'done') return `${c.success}✓${c.reset}`;
+  if (status === 'current') return `${c.primary}${c.bold}●${c.reset}`;
+  return `${c.muted}○${c.reset}`;
+}
+
+function printLadder(report, t, p) {
+  const ld = t.ladder;
+  const { setupLevels } = buildLadder(report, t);
+  const allTiers = setupLevels.flatMap((lvl) => lvl.tiers);
+  const done = allTiers.filter((x) => x.status === 'done').length;
+  const current = allTiers.filter((x) => x.status === 'current').length;
+  const pending = allTiers.filter((x) => x.status === 'pending').length;
+
+  p(`  ${c.bold}${ld.setupHeading}${c.reset}`);
+  p(`  ${c.muted}${ld.setupIntro}${c.reset}`);
+  p(`  ${c.dim}${ld.legend(done, current, pending)}${c.reset}`);
+  p();
+  // NESTED (ADR-016): each SETUP LEVEL, then its tiers indented beneath.
+  for (const lvl of setupLevels) {
+    const nameStyle = lvl.status === 'pending' ? c.muted : `${c.bold}${c.white}`;
+    const keys = lvl.tierKeys.length ? ` ${c.muted}— [${lvl.tierKeys.join(', ')}]${c.reset}` : '';
+    // "You are here" lives ONLY on the current TIER, not the level header (user request).
+    p(`  ${ladderMark(lvl.status)} ${nameStyle}${lvl.emoji} ${lvl.label}${c.reset}${keys}`);
+    p(`      ${c.dim}${lvl.description}${c.reset}`);
+    for (const tier of lvl.tiers) {
+      const tierNameStyle = tier.status === 'pending' ? c.muted : c.white;
+      const tierBadge = tier.status === 'current' ? `  ${c.primary}${ld.currentLabel}${c.reset}` : '';
+      p(`        ${ladderMark(tier.status)} ${c.bold}${tier.tierKey}${c.reset} ${tierNameStyle}${tier.name}${c.reset}${tierBadge}`);
+      p(`            ${c.dim}${tier.description}${c.reset}`);
+      if (tier.unlock) {
+        p(`            ${c.muted}${ld.unlockLabel}: ${tier.unlock}${c.reset}`);
+      }
+    }
+    p();
+  }
+}
+
+// One side of the before/after, in the SAME format for both — the comparison is the feature, so a second formatter here would defeat it.
+function projectionLine(side, t) {
+  const name = (t.tierNames && t.tierNames[side.tierKey]) || side.tierKey;
+  const setup = (t.setupLevels && t.setupLevels[side.setupLevelKey] && t.setupLevels[side.setupLevelKey].label)
+    || side.setupLevelKey;
+  return `${side.tierKey} · ${name} · ${setup} · ${side.score}/100`;
+}
+
+function printProjection(report, t, p) {
+  const projection = projectNextTier(report);
+  if (!projection) return;
+
+  p();
+  p(`  ${c.dim}${t.html.roadmapNowLabel}${c.reset}`);
+  p(`  ${c.white}${projectionLine(projection.current, t)}${c.reset}`);
+  p();
+  // The tag rides ON the heading, not in a footnote: a reader who skims the two
+  // numbers must still see that the second one is a projection.
+  p(`  ${c.dim}${t.html.roadmapProjectionLabel}${c.reset}  ${c.warning}[${t.html.roadmapProjectionTag}]${c.reset}`);
+  p(`  ${c.white}${projectionLine(projection.projected, t)}${c.reset}`);
+  for (const line of wrap(t.html.roadmapProjectionNote)) p(`  ${c.dim}${line}${c.reset}`);
+}
+
+function printRoadmap(report, maturity, t, lang, p) {
+  const tierKey = maturity && maturity.tierKey;
+  const curatedEntry = tierKey ? getRoadmapEntry(tierKey, lang) : null;
+
+  if (!curatedEntry) {
+    const nextStep = t.nextSteps[maturity.level] || maturity.next;
+    p(`  ${c.bold}${c.warning}${t.terminal.nextStep}${c.reset}`);
+    p(`  ${c.white}${nextStep}${c.reset}`);
+    p();
+    return;
+  }
+
+  p(`  ${c.bold}${c.warning}${t.html.roadmapHeading}${c.reset}`);
+  // Issue 083: the register, stated before the content.
+  // Wrapped like every other prose line in this block (issue 087): it was the one line still running past the 80th column, which is the shape the squad read as a dump.
+  for (const line of wrap(t.html.roadmapSubheading)) p(`  ${c.dim}${line}${c.reset}`);
+
+  if (curatedEntry.contentUnavailable) {
+    p(`  ${c.white}${t.html.roadmapContentUnavailable}${c.reset}`);
+    if (!curatedEntry.maxTier) p(`  ${c.dim}${t.cli.buildNextLevelHint}${c.reset}`);
+    p();
+    return;
+  }
+
+  const personalization = report && report.roadmapPersonalization;
+  const entry = mergeRoadmapPersonalization(curatedEntry, personalization);
+
+  // Issue 087: the jump title gets air and its own line, and everything below it hangs off it.
+  // THE BEFORE AND THE AFTER (issue 084), above the steps and not below them.
+  printProjection(report, t, p);
+
+  p();
+  p(`  ${c.white}${c.bold}${sanitizeRenderText(entry.title)}${c.reset}`);
+  p();
+
+  // Issue 109: whether this roadmap is YOURS or the template, said out loud.
+  if (personalization) {
+    p(`  ${c.dim}${t.html.roadmapPersonalizedNotice}${c.reset}`);
+    p();
+  } else if (callFailed(report, MODEL_CALL.ROADMAP)) {
+    for (const line of wrap(t.html.roadmapNotPersonalizedNotice)) p(`  ${c.dim}${line}${c.reset}`);
+    p();
+  }
+
+  if (entry.maxTier) {
+    // ADR-008 (skill-code-certification): T7 is NOT a dead end.
+    if (entry.whatRemains) {
+      for (const line of wrap(sanitizeRenderText(entry.whatRemains))) p(`  ${c.muted}${line}${c.reset}`);
+      p();
+    }
+    if (Array.isArray(entry.consolidationSteps) && entry.consolidationSteps.length) {
+      p(`  ${c.dim}${t.html.roadmapConsolidationLabel}:${c.reset}`);
+      entry.consolidationSteps.forEach((step) => printStepLines(p, `${c.success}•${c.reset}`, sanitizeRenderText(step), null));
+    }
+  } else {
+    labelledBlock(p, t.html.roadmapUpgradeWhenLabel, sanitizeRenderText(entry.upgradeWhen));
+    if (entry.upgradeWhen) p();
+    labelledBlock(p, `${t.html.roadmapUnlocksLabel}:`, sanitizeRenderText(entry.unlocks));
+    if (entry.unlocks) p();
+    if (Array.isArray(entry.steps) && entry.steps.length) {
+      p(`  ${c.dim}${t.html.roadmapStepsLabel}:${c.reset}`);
+      // Numbered, wrapped, and with the estimate on the same line as the step it belongs to.
+      const width = String(entry.steps.length).length;
+      entry.steps.forEach((step, i) => {
+        const marker = `${String(i + 1).padStart(width)}.`;
+        printStepLines(p, marker, sanitizeRenderText(step.text), sanitizeRenderText(step.estimate));
+      });
+    }
+  }
+
+  {
+    const promptText = buildImplementationPrompt(entry, report, maturity, lang);
+    if (promptText) {
+      // Issue 087: THE wall of text.
+      sep(p);
+      p(`  ${c.bold}${t.html.implementationPromptHeading}${c.reset}`);
+      for (const line of wrap(t.html.implementationPromptHint)) p(`  ${c.dim}${line}${c.reset}`);
+      p();
+      const rule = `${'─'.repeat(48)}`;
+      p(`  ${c.muted}${rule}${c.reset}`);
+      for (const line of promptText.split('\n')) p(`  ${sanitizeRenderText(line)}`);
+      p(`  ${c.muted}${rule}${c.reset}`);
+    }
+  }
+
+  // --build-next-level (issue 021) is now a SECONDARY, opt-in alternative to the prompt above — never when already at the terminal T7 entry (there is nothing left to build).
+  if (!entry.maxTier) p(`  ${c.dim}${t.cli.buildNextLevelHint}${c.reset}`);
+
+  p();
+}
+
+module.exports = { printMcpServices, printTierAnalysis, printLadder, printRoadmap };