shakers-cli 0.15.0 → 0.17.0

package/src/usage-run-steps.js

@@ -1,60 +1,32 @@
 'use strict';
 
-const { scan, scanForRoots } = require('./scanner');
-const { classify } = require('./maturity');
 const { renderTerminal } = require('./render-terminal');
-const { reportGateForIdentity } = require('./report-gating');
 const { revealText } = require('./typewriter');
 const { persistFootprint } = require('./report-store');
 const {
   loadConsentState,
   getConsentDecision,
-  recordConsent,
-  isValidEmail,
-  normalizeEmail,
   autoShare,
   consentPath,
+  isThrottled,
 } = require('./share');
 const { runConsentPrompt } = require('./consent-flow');
 const { createStdinAsk } = require('./stdin-ask');
-const {
-  parseAgentDescriptions,
-  parseAgentOrgChartForRoots,
-  parseAgentDescriptionsForRoots,
-  parseAgentDefinitionsForRoots,
-} = require('./agent-org-chart');
-const { collectAgentUsage } = require('./agent-usage');
-const { collectSessionSignals } = require('./session-signals');
-const {
-  collectScopedGitActivity,
-  collectScopedWorkStreams,
-  collectScopedDetectionEvidence,
-} = require('./scope-signals');
-const { detectAuthorshipMismatch } = require('./authorship-mismatch');
-const { MODEL_CALL, REASON, skipped, attachModelCall } = require('./model-call-record');
-const {
-  getSynthesisEndpoint,
-  getRoadmapEndpoint,
-  getAgentEvaluationEndpoint,
-  getAiProfileEndpoint,
-} = require('./config');
+const { getAiProfileEndpoint } = require('./config');
 // "My work with AI" preview, read from the hub ai-profile (same as the front).
 const { resolveAiProfilePreview } = require('./ai-profile-preview');
 const { renderAiProfileTerminal } = require('./render-ai-fluency');
 const { ensureFreshSession } = require('./session-refresh');
 const { loadAuthSession, sessionStatus } = require('./auth-session-store');
 const { c: termColors } = require('./terminal-format');
-const { withStaticStatus, withSpinner } = require('./terminal-progress');
+const { withSpinner } = require('./terminal-progress');
 const { computeConsentSkip } = require('./consent-skip');
-const { getRoadmapEntry } = require('./roadmap-content');
-const {
-  maybeSynthesizeAgents,
-  maybeEvaluateAgents,
-  maybePersonalizeRoadmap,
-} = require('./usage-model-calls');
+const { collectIdentityAndUsage, storedAiConsent, reanchorReusedGrant } = require('./usage-scan');
 const { doBuildNextLevel } = require('./usage-oneshot-commands');
+const { uploadFacts, withoutExcluded, summaryText, explanationText } = require('./ai-usage-review');
+const { reviewCopy } = require('./signup-copy');
+const { askYesNo } = require('./consent-flow');
 
-// Automatic, silent PERSISTING once consent is `granted` (ADR-007, gating revised by ADR-011: consent controls persistence only, never what's shown).
 async function maybeAutoShare(report, maturity, root, catalog, { bypassThrottle = false } = {}) {
   try {
     const result = await autoShare(report, maturity, { root, bypassThrottle });
@@ -82,35 +54,17 @@ function sendStatusColor(reason) {
   return SEND_WARN_REASONS.has(reason) ? termColors.warning : termColors.danger;
 }
 
-function performScan({ opts, catalog }) {
-  const root = opts.root;
-  const report = withStaticStatus(catalog.cli.scanningLabel, () => scan({ root }));
-  // `let`, not `const`: this is the cwd tier.
-  const maturity = classify(report);
-
-  if (Array.isArray(report.agents) && report.agents.length > 0) {
-    report.agentDescriptions = parseAgentDescriptions(root || process.cwd());
-  }
-
-  return { report, maturity, root, rootDir: root || process.cwd() };
-}
-
 // The identity gate + local (no-network, no-LLM) agent-usage signal.
 function prepareIdentityAndUsage({ report, catalog, quiet = false }) {
-  const hasAgents = Array.isArray(report.agents) && report.agents.length > 0;
-  const gate = reportGateForIdentity();
-
+  const identity = collectIdentityAndUsage({ report });
   // --json owns stdout: one parseable document, and the MCP's JSON-RPC channel.
-  if (gate.showFrameworkIntro && !quiet) process.stdout.write(`\n  ${catalog.cli.frameworkIntroUsage}\n`);
-
-  // Local, no network, no LLM: how often each detected agent was invoked in the local Claude Code history.
-  if (hasAgents) report.agentUsage = collectAgentUsage(report.agents);
-
-  return { gate, hasAgents };
+  if (identity.gate.showFrameworkIntro && !quiet) process.stdout.write(`\n  ${catalog.cli.frameworkIntroUsage}\n`);
+  return identity;
 }
 
 async function resolveAiConsent({ opts, catalog, gate, injectedAsk }) {
-  // CONSENT GATE, MOVED TO BEFORE ANY AI/EGRESS CALL (talents-ai-score, ADR-051 — explicit product decision that AMENDS ADR-010/011/003 on purpose, not a bug fix).
+  // CONSENT GATE, MOVED TO BEFORE ANY AI/EGRESS CALL (explicit product decision, not a bug fix).
+  if (opts.json) return storedAiConsent({ gate });
   const state = loadConsentState();
   const decision = getConsentDecision(state);
   const consentSkip = computeConsentSkip({
@@ -122,143 +76,90 @@ async function resolveAiConsent({ opts, catalog, gate, injectedAsk }) {
   });
 
   let aiConsentGranted;
-  // A REUSED grant (skip/--json) carries a stale consent email; a fresh prompt re-anchors itself.
+  // A REUSED grant (skip) carries a stale consent email; a fresh prompt re-anchors itself.
   let reusedStoredConsent = false;
-  if (opts.json) {
-    // `--json` never had an interactive prompt — its whole point is a single parseable stdout document, and it does not gain one now.
-    aiConsentGranted = decision === 'granted' && (!state || state.emailVerified !== false);
+  if (consentSkip.message) {
+    process.stdout.write(`\n  ${consentSkip.message}\n`);
+  }
+  if (consentSkip.skip) {
+    // A TERMINAL decision already exists (a prior run's explicit grant or
+    // denial) — never re-asked.
+    aiConsentGranted = decision === 'granted';
     reusedStoredConsent = true;
   } else {
-    if (consentSkip.message) {
-      process.stdout.write(`\n  ${consentSkip.message}\n`);
-    }
-    if (consentSkip.skip) {
-      // A TERMINAL decision already exists (a prior run's explicit grant or
-      // denial) — never re-asked, per ADR-007/011.
-      aiConsentGranted = decision === 'granted';
-      reusedStoredConsent = true;
-    } else {
-      const ask = injectedAsk || createStdinAsk();
-      let result;
-      try {
-        result = await runConsentPrompt({
-          ask, catalog, loggedIn: gate.loggedIn, sessionEmail: gate.email, profile: gate.profile,
-        });
-      } finally {
-        if (!injectedAsk) ask.close();
-      }
-      aiConsentGranted = result === 'granted';
-    }
-    if (!aiConsentGranted) {
-      // No early return (reverted 8867450's wall): the local report still renders further down, same as ADR-011 always promised.
-      process.stdout.write(`\n  ${termColors.warning}${catalog.consent.noReportWithoutConsent}${termColors.reset}\n\n`);
+    const ask = injectedAsk || createStdinAsk();
+    let result;
+    try {
+      result = await runConsentPrompt({
+        ask, catalog, loggedIn: gate.loggedIn, sessionEmail: gate.email, profile: gate.profile,
+      });
+    } finally {
+      if (!injectedAsk) ask.close();
     }
+    aiConsentGranted = result === 'granted';
   }
-  // Re-anchor a reused grant to the session's login-proven email (ADR-006): else a stale consent email ingests the report under another account and this session's AI profile never populates.
-  if (reusedStoredConsent && aiConsentGranted && gate.loggedIn
-    && isValidEmail(gate.email) && state && state.email !== normalizeEmail(gate.email)) {
-    recordConsent('granted', gate.email, { verified: true });
+  if (!aiConsentGranted) {
+    // No early return: the local report still renders further down.
+    process.stdout.write(`\n  ${termColors.warning}${catalog.consent.noReportWithoutConsent}${termColors.reset}\n\n`);
   }
+  if (reusedStoredConsent && aiConsentGranted) reanchorReusedGrant({ gate, state });
   return aiConsentGranted;
 }
 
-function runAggregation({ report, scope, consentEmail, agentRoots, root, catalog }) {
-  withStaticStatus(catalog.cli.aggregatingLabel, () => {
-    report.gitActivity = collectScopedGitActivity(scope.toplevels, consentEmail);
-    // Display-only transparency warning (never feeds scoring, see authorship-mismatch.js).
-    report.authorshipMismatch = detectAuthorshipMismatch(scope.toplevels, consentEmail, report.gitActivity);
-    const sessionSignals = collectSessionSignals(process.env, scope.selectedCwds);
-    report.sessions = sessionSignals.sessions;
-    report.workStreams = collectScopedWorkStreams(scope.toplevels);
-    report.steering = sessionSignals.steering;
-    report.decisions = sessionSignals.decisions;
-    report.detectionEvidence = collectScopedDetectionEvidence(
-      scope.toplevels,
-      consentEmail,
-      report,
-    );
-
-    const scoped = scanForRoots(agentRoots, { root });
-    report.tools = scoped.tools;
-    report.summary = scoped.summary;
-    report.technologies = scoped.technologies;
-    report.mcp = scoped.mcp;
-    report.memory = scoped.memory;
-    report.automations = scoped.automations;
-    report.browserTools = scoped.browserTools;
-    report.agentCounts = scoped.agentCounts;
-    report.environment = scoped.environment;
-
-    report.agents = parseAgentOrgChartForRoots(agentRoots);
-    report.agentCounts.agents = report.agents.length;
-    if (report.agents.length > 0) {
-      report.agentDescriptions = parseAgentDescriptionsForRoots(agentRoots);
-      report.agentDefinitions = parseAgentDefinitionsForRoots(agentRoots);
-      report.agentUsage = collectAgentUsage(report.agents);
-    }
-  });
+function matchNames(raw, known) {
+  const wanted = String(raw || '').split(',').map((x) => x.trim()).filter(Boolean);
+  const byLower = new Map(known.map((name) => [name.toLowerCase(), name]));
+  return {
+    matched: wanted.map((w) => byLower.get(w.toLowerCase())).filter(Boolean),
+    unknown: wanted.filter((w) => !byLower.has(w.toLowerCase())),
+  };
 }
 
-async function runModelCalls({
-  report, maturity, aiConsentGranted, opts, gate, hasAgents, agentRoots, rootDir, lang, catalog,
-}) {
-  // Which of the three will genuinely be ATTEMPTED.
-  const willAttemptSynthesis = aiConsentGranted && hasAgents && !!getSynthesisEndpoint();
-  const willAttemptEvaluation = aiConsentGranted && hasAgents && !!getAgentEvaluationEndpoint();
-  const roadmapEntryForTier = maturity.tierKey ? getRoadmapEntry(maturity.tierKey, lang) : null;
-  const willAttemptRoadmapPersonalization =
-    aiConsentGranted
-    && gate.showRoadmap
-    && !!roadmapEntryForTier && !roadmapEntryForTier.maxTier
-    && !!getRoadmapEndpoint();
-
-  // THE THREE MODEL CALLS RUN ONE AFTER ANOTHER, NOT IN PARALLEL (issue 116).
-  const runPhase = (willAttempt, label, call) => (willAttempt ? withSpinner(label, call) : call());
-
-  // talents-ai-score, ADR-051: `aiConsentGranted` is `false` whenever consent for this run was declined, denied in the past, or (on `--json`) simply never granted.
-  let synthesis = null;
-  let evaluation = null;
-  let roadmapPersonalization = null;
-  if (aiConsentGranted && !opts.noAi) {
-    synthesis = await runPhase(
-      willAttemptSynthesis,
-      catalog.cli.synthesizingLabel,
-      () => maybeSynthesizeAgents(report, rootDir),
-    );
-    evaluation = hasAgents
-      ? await runPhase(
-        willAttemptEvaluation,
-        catalog.cli.evaluatingAgentsLabel,
-        () => maybeEvaluateAgents(report, agentRoots, lang),
-      )
-      : null;
-    // issue 123 / ADR-044: `runPhase` runs `call()` whether or not a spinner is shown, so gating the roadmap CANNOT be done by flipping `willAttempt` — that only hides the spinner.
-    roadmapPersonalization = gate.showRoadmap
-      ? await runPhase(
-        willAttemptRoadmapPersonalization,
-        catalog.cli.personalizingRoadmapLabel,
-        () => maybePersonalizeRoadmap(report, maturity, lang),
-      )
-      : null;
-  } else {
-    const skipReason = aiConsentGranted ? REASON.NOT_APPLICABLE : REASON.NO_CONSENT;
-    attachModelCall(report, MODEL_CALL.SYNTHESIS, skipped(skipReason));
-    attachModelCall(report, MODEL_CALL.EVALUATION, skipped(skipReason));
-    attachModelCall(report, MODEL_CALL.ROADMAP, skipped(skipReason));
+async function askExcludedAgents(ask, c, known, out) {
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const { matched, unknown } = matchNames(await ask(c.cliExcludeAgents), known);
+    if (unknown.length === 0) return matched;
+    out.write(`  ${c.cliUnknownAgents(unknown.join(', '), known.join(', '))}\n`);
   }
+  return null;
+}
 
-  if (synthesis) report.agentSynthesis = synthesis;
-  if (evaluation) report.agentEvaluation = evaluation;
-  if (roadmapPersonalization) report.roadmapPersonalization = roadmapPersonalization;
+async function reviewUpload({ report, maturity, repos = [], lang, catalog, injectedAsk = null, out = process.stdout, bypassThrottle = false }) {
+  const state = loadConsentState();
+  if (getConsentDecision(state) !== 'granted' || !state || state.emailVerified === false || !state.email || (!bypassThrottle && isThrottled(state))) {
+    return { approved: true, report, maturity };
+  }
+  const c = reviewCopy(lang);
+  const facts = uploadFacts({ report, maturity, repos });
+  out.write(`\n${summaryText(lang, facts)}\n\n${explanationText(lang)}\n\n`);
+  if (facts.repos.length > 1) out.write(`${c.cliRepoHint}\n\n`);
+  const ask = injectedAsk || createStdinAsk();
+  try {
+    const approved = await askYesNo(ask, c.cliQuestion, catalog, { defaultNo: true });
+    if (!approved) {
+      out.write(`  ${c.declined}\n`);
+      return { approved: false };
+    }
+    const agents = facts.agents.length > 0 ? await askExcludedAgents(ask, c, facts.agents, out) : [];
+    if (agents === null) {
+      out.write(`  ${c.declined}\n`);
+      return { approved: false };
+    }
+    const hasExcerpts = facts.conversationExcerpts + facts.commandExcerpts > 0;
+    const excerpts = hasExcerpts ? (await askYesNo(ask, c.cliIncludeExcerpts, catalog, { defaultYes: true })) === true : true;
+    return { approved: true, ...withoutExcluded(report, { agents, excerpts }) };
+  } finally {
+    if (!injectedAsk) ask.close();
+  }
 }
 
-async function renderAndFinalize({ report, maturity, lang, opts, root, gate, catalog, bypassThrottle = false }) {
+async function renderAndFinalize({ report, maturity, lang, opts, root, gate, catalog, bypassThrottle = false, repos = [], injectedAsk = null }) {
   if (opts.json) {
     process.stdout.write(JSON.stringify({ report, maturity }, null, 2) + '\n');
     return;
   }
 
-  // Issue 103: revealed by SECTIONS instead of landing in one write.
+  // Revealed by SECTIONS instead of landing in one write.
   if (gate.sessionStatus === 'expired') {
     process.stdout.write(`\n  ${termColors.warning}${catalog.terminal.sessionExpiredNotice}${termColors.reset}\n`);
   }
@@ -276,14 +177,16 @@ async function renderAndFinalize({ report, maturity, lang, opts, root, gate, cat
     }
   }
 
-  // "Construir el siguiente nivel ahora" (issue 021): optional, only when
+  // "Construir el siguiente nivel ahora": optional, only when
   // explicitly requested — never part of a normal run otherwise.
   if (opts.buildNextLevel) {
     doBuildNextLevel(root, maturity, opts.force, catalog);
   }
 
-  // Auto-send at the end (bypassThrottle only true on the register path).
-  const shareResult = await maybeAutoShare(report, maturity, root, catalog, { bypassThrottle });
+  const reviewed = await reviewUpload({ report, maturity, repos, lang, catalog, injectedAsk, bypassThrottle });
+  if (!reviewed.approved) return;
+  const shareResult = await maybeAutoShare(reviewed.report, reviewed.maturity, root, catalog, { bypassThrottle });
+  if (shareResult && shareResult.ok) process.stdout.write(`\n  ${reviewCopy(lang).afterwards}\n`);
 
   // "My work with AI" preview, best-effort after the send; never blocks/breaks the run.
   await maybeRenderAiProfile({ report, maturity, lang, root, save: opts.save, submitOk: !!(shareResult && shareResult.ok), catalog });
@@ -343,11 +246,9 @@ async function maybeRenderAiProfile({ report, maturity, lang, root, save, submit
 }
 
 module.exports = {
-  performScan,
+  reviewUpload,
   prepareIdentityAndUsage,
   resolveAiConsent,
-  runAggregation,
-  runModelCalls,
   renderAndFinalize,
   shouldRenderAiProfile,
   maybeRenderAiProfile,

package/src/usage-scan.js

@@ -0,0 +1,235 @@
+'use strict';
+
+const { scan, scanForRoots } = require('./scanner');
+const { classify } = require('./maturity');
+const { reportGateForIdentity } = require('./report-gating');
+const {
+  loadConsentState,
+  getConsentDecision,
+  recordConsent,
+  isValidEmail,
+  normalizeEmail,
+} = require('./share');
+const {
+  parseAgentDescriptions,
+  parseAgentOrgChartForRoots,
+  parseAgentDescriptionsForRoots,
+  parseAgentDefinitionsForRoots,
+} = require('./agent-org-chart');
+const { collectAgentUsage } = require('./agent-usage');
+const { collectSessionSignals } = require('./session-signals');
+const {
+  collectScopedGitActivity,
+  collectScopedWorkStreams,
+  collectScopedDetectionEvidence,
+} = require('./scope-signals');
+const { detectAuthorshipMismatch } = require('./authorship-mismatch');
+const { MODEL_CALL, REASON, skipped, attachModelCall } = require('./model-call-record');
+const {
+  getSynthesisEndpoint,
+  getRoadmapEndpoint,
+  getAgentEvaluationEndpoint,
+} = require('./config');
+const { withStaticStatus, withSpinner } = require('./terminal-progress');
+const { getRoadmapEntry } = require('./roadmap-content');
+const {
+  maybeSynthesizeAgents,
+  maybeEvaluateAgents,
+  maybePersonalizeRoadmap,
+} = require('./usage-model-calls');
+const { parseArgs } = require('./cli-args');
+const { detectReportLang, getCatalog } = require('./i18n');
+const { prefetchGitLogs } = require('./git-log-prefetch');
+const { GIT_ACTIVITY_LOG_ARGS } = require('./git-activity');
+const { WORK_STREAMS_LOG_ARGS } = require('./work-streams');
+const { AUTHORSHIP_LOG_ARGS } = require('./authorship');
+const { resolveRepoScope } = require('./repo-scope');
+
+function performScan({ opts, catalog }) {
+  const root = opts.root;
+  const report = withStaticStatus(catalog.cli.scanningLabel, () => scan({ root }));
+  // `let`, not `const`: this is the cwd tier.
+  const maturity = classify(report);
+
+  if (Array.isArray(report.agents) && report.agents.length > 0) {
+    report.agentDescriptions = parseAgentDescriptions(root || process.cwd());
+  }
+
+  return { report, maturity, root, rootDir: root || process.cwd() };
+}
+
+function collectIdentityAndUsage({ report }) {
+  const hasAgents = Array.isArray(report.agents) && report.agents.length > 0;
+  const gate = reportGateForIdentity();
+  if (hasAgents) report.agentUsage = collectAgentUsage(report.agents);
+  return { gate, hasAgents };
+}
+
+// Re-anchor a reused grant to the session's login-proven email: else a stale consent email ingests the report under another account and this session's AI profile never populates.
+function reanchorReusedGrant({ gate, state }) {
+  if (gate.loggedIn && isValidEmail(gate.email) && state && state.email !== normalizeEmail(gate.email)) {
+    recordConsent('granted', gate.email, { verified: true });
+  }
+}
+
+// `--json` never had an interactive prompt — its whole point is a single parseable stdout document, and it does not gain one now.
+function storedAiConsent({ gate }) {
+  const state = loadConsentState();
+  const granted = getConsentDecision(state) === 'granted' && (!state || state.emailVerified !== false);
+  if (granted) reanchorReusedGrant({ gate, state });
+  return granted;
+}
+
+function runAggregation({ report, scope, consentEmail, agentRoots, root, catalog }) {
+  withStaticStatus(catalog.cli.aggregatingLabel, () => {
+    report.gitActivity = collectScopedGitActivity(scope.toplevels, consentEmail);
+    // Display-only transparency warning (never feeds scoring, see authorship-mismatch.js).
+    report.authorshipMismatch = detectAuthorshipMismatch(scope.toplevels, consentEmail, report.gitActivity);
+    const sessionSignals = collectSessionSignals(process.env, scope.selectedCwds);
+    report.sessions = sessionSignals.sessions;
+    report.workStreams = collectScopedWorkStreams(scope.toplevels);
+    report.steering = sessionSignals.steering;
+    report.decisions = sessionSignals.decisions;
+    report.detectionEvidence = collectScopedDetectionEvidence(
+      scope.toplevels,
+      consentEmail,
+      report,
+    );
+
+    const scoped = scanForRoots(agentRoots, { root });
+    report.tools = scoped.tools;
+    report.summary = scoped.summary;
+    report.technologies = scoped.technologies;
+    report.mcp = scoped.mcp;
+    report.memory = scoped.memory;
+    report.automations = scoped.automations;
+    report.browserTools = scoped.browserTools;
+    report.agentCounts = scoped.agentCounts;
+    report.environment = scoped.environment;
+
+    report.agents = parseAgentOrgChartForRoots(agentRoots);
+    report.agentCounts.agents = report.agents.length;
+    if (report.agents.length > 0) {
+      report.agentDescriptions = parseAgentDescriptionsForRoots(agentRoots);
+      report.agentDefinitions = parseAgentDefinitionsForRoots(agentRoots);
+      report.agentUsage = collectAgentUsage(report.agents);
+    }
+  });
+}
+
+async function runModelCalls({
+  report, maturity, aiConsentGranted, opts, gate, hasAgents, agentRoots, rootDir, lang, catalog,
+}) {
+  // Which of the three will genuinely be ATTEMPTED.
+  const willAttemptSynthesis = aiConsentGranted && hasAgents && !!getSynthesisEndpoint();
+  const willAttemptEvaluation = aiConsentGranted && hasAgents && !!getAgentEvaluationEndpoint();
+  const roadmapEntryForTier = maturity.tierKey ? getRoadmapEntry(maturity.tierKey, lang) : null;
+  const roadmapRequested = opts.roadmap === true && gate.showRoadmap;
+  const willAttemptRoadmapPersonalization =
+    aiConsentGranted
+    && roadmapRequested
+    && !!roadmapEntryForTier && !roadmapEntryForTier.maxTier
+    && !!getRoadmapEndpoint();
+
+  // THE THREE MODEL CALLS RUN ONE AFTER ANOTHER, NOT IN PARALLEL.
+  const runPhase = (willAttempt, label, call) => (willAttempt ? withSpinner(label, call) : call());
+
+  // `aiConsentGranted` is `false` whenever consent for this run was declined, denied in the past, or (on `--json`) simply never granted.
+  let synthesis = null;
+  let evaluation = null;
+  let roadmapPersonalization = null;
+  if (aiConsentGranted && !opts.noAi) {
+    synthesis = await runPhase(
+      willAttemptSynthesis,
+      catalog.cli.synthesizingLabel,
+      () => maybeSynthesizeAgents(report, rootDir),
+    );
+    evaluation = hasAgents
+      ? await runPhase(
+        willAttemptEvaluation,
+        catalog.cli.evaluatingAgentsLabel,
+        () => maybeEvaluateAgents(report, agentRoots, lang),
+      )
+      : null;
+    // `runPhase` runs `call()` whether or not a spinner is shown, so gating the roadmap CANNOT be done by flipping `willAttempt` — that only hides the spinner.
+    roadmapPersonalization = roadmapRequested
+      ? await runPhase(
+        willAttemptRoadmapPersonalization,
+        catalog.cli.personalizingRoadmapLabel,
+        () => maybePersonalizeRoadmap(report, maturity, lang),
+      )
+      : null;
+  } else {
+    const skipReason = aiConsentGranted ? REASON.NOT_APPLICABLE : REASON.NO_CONSENT;
+    attachModelCall(report, MODEL_CALL.SYNTHESIS, skipped(skipReason));
+    attachModelCall(report, MODEL_CALL.EVALUATION, skipped(skipReason));
+    attachModelCall(report, MODEL_CALL.ROADMAP, skipped(skipReason));
+  }
+
+  if (synthesis) report.agentSynthesis = synthesis;
+  if (evaluation) report.agentEvaluation = evaluation;
+  if (roadmapPersonalization) report.roadmapPersonalization = roadmapPersonalization;
+}
+
+// Steps 1-6 of a run: scan, scope, aggregate, classify; nothing is rendered or sent.
+async function computeUsage({
+  opts,
+  catalog,
+  lang,
+  inRegistration = false,
+  prepareIdentity = collectIdentityAndUsage,
+  resolveConsent = storedAiConsent,
+  resolveScope = resolveRepoScope,
+}) {
+  // 1. Local scan + classify (always computed and shown).
+  const { report, root, rootDir } = performScan({ opts, catalog });
+
+  // 2. Identity gate + local agent-usage signal.
+  const { gate: identityGate } = prepareIdentity({ report, catalog, quiet: opts.json === true });
+  const gate = (inRegistration && identityGate.showRoadmap)
+    ? { ...identityGate, showRoadmap: false }
+    : identityGate;
+
+  // 3. Consent gate before any AI/egress call; a decline still renders.
+  const aiConsentGranted = await resolveConsent({ opts, catalog, gate });
+
+  // 4. Repo scoping (exclude client work).
+  const scope = await resolveScope({ opts, cwd: rootDir, catalog });
+  const consentEmail = (loadConsentState() || {}).email || null;
+  const agentRoots = scope.toplevels;
+
+  // 5. Aggregate scoped signals + rebuild scan/org-chart over the selection, re-classify.
+  await prefetchGitLogs(agentRoots, [GIT_ACTIVITY_LOG_ARGS, WORK_STREAMS_LOG_ARGS, AUTHORSHIP_LOG_ARGS]);
+  runAggregation({ report, scope, consentEmail, agentRoots, root, catalog });
+  const maturity = classify(report);
+  const hasAgents = Array.isArray(report.agents) && report.agents.length > 0;
+  report.analyzedRepos =
+    scope.mode === 'all'
+      ? null
+      : scope.toplevels.map((tl) => tl.split(/[/\\]/).pop() || tl);
+
+  // 6. The three ephemeral model calls, serialized and gated by consent.
+  await runModelCalls({
+    report, maturity, aiConsentGranted, opts, gate, hasAgents, agentRoots, rootDir, lang, catalog,
+  });
+  return { report, maturity, root, gate, repos: scope.toplevels };
+}
+
+// The MCP's scan: same steps, returned instead of printed, since stdout is its JSON-RPC channel.
+async function scanUsage(argv) {
+  const opts = { ...parseArgs(argv), roadmap: false };
+  const lang = opts.lang || detectReportLang();
+  const { report, maturity, repos } = await computeUsage({ opts, catalog: getCatalog(lang), lang });
+  return { report, maturity, repos };
+}
+
+module.exports = {
+  performScan,
+  collectIdentityAndUsage,
+  reanchorReusedGrant,
+  storedAiConsent,
+  runAggregation,
+  runModelCalls,
+  computeUsage,
+  scanUsage,
+};

package/src/work-streams.js

@@ -4,7 +4,7 @@ const { execFileSync } = require('child_process');
 const { isGitRepo } = require('./git-activity');
 const { takePrefetchedGitLog } = require('./git-log-prefetch');
 
-// Deterministic WORK-STREAM structure for the project where `shakers ai-usage` runs (hybrid evaluation, Slice 2).
+// Deterministic WORK-STREAM structure for the project where `shakers ai-usage` runs.
 
 const GIT_TIMEOUT_MS = 15000;
 const SESSION_GAP_SECONDS = 4 * 3600;