ticketlens 0.38.31 → 0.38.33

package/README.md

@@ -453,7 +453,7 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 **Removing a note:** `ticketlens note delete --id="..." [--ticket=KEY]` removes a note from your local vault. Local only — if it was already pushed to a team, teammates who pulled it keep their copy; deleting it there too is a manager action from the Console (Admin > Recall).
 
-**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `fetch`, `triage`, `compliance`, `doctor`, `recall_add`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, `ticket_duplicates`, `ticket_link`, `ticket_update`, and `ticket_create` as native tools — any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same license gate per tool, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. `fetch` and `doctor` are Free; `triage`'s base scan is Free with some options gated Pro/Team, same as the CLI (`ticketlens triage --help`); `compliance` is Free with a 3-checks/month cap, Pro unlimited; every other tool needs Pro. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
+**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `fetch`, `triage`, `compliance`, `review`, `standup`, `pr`, `stats`, `history`, `collisions`, `doctor`, `recall_add`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, `ticket_duplicates`, `ticket_link`, `ticket_update`, and `ticket_create` as native tools — any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same license gate per tool, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. `fetch`, `doctor`, and `standup` are Free; `triage`'s base scan is Free with some options gated Pro/Team, same as the CLI (`ticketlens triage --help`); `compliance` and `pr` are Free, sharing a 3-checks/month cap on their requirements-coverage section, Pro unlimited; `review` is Free for branch/files/ticket context, with its coverage/focus section requiring Pro as a plain license check — it does not draw from that same monthly counter; `stats` is Free with a 7-day lookback cap, Pro extends it to 30 days, same split as the CLI (`ticketlens stats --help`); `history` reads local triage history only (zero network) and requires Pro; `collisions` requires `ticketlens login` (Console access) plus a Team license; every other tool needs Pro. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
 
 `note add`'s save confirmation and `recall`'s search results are styled by default in a terminal; add `--plain` to either for bare, pipe-safe output. `recall` always shows each note's file ID (e.g. `[1784135399545-fe01c4.md]`) so you can open it directly (`cat ~/.ticketlens/recall/<PREFIX>/<id>`), or pass `--full` to print the full body content inline instead. Each result shows a relative time (`2h ago`, `3d ago`) rather than a bare date — the full-precision timestamp is always in the note file's own frontmatter.
 

package/bin/ticketlens.mjs

@@ -20,7 +20,7 @@ import { deleteProfile, loadProfiles, saveCredentialKey, resolveRecallStrictness
 import { run as runCache } from '../skills/jtb/scripts/lib/cache-manager.mjs';
 import { runDoctor } from '../skills/jtb/scripts/lib/doctor-command.mjs';
 import {
-  printHelp, printProfiles, printHistoryHelp,
+  printHelp, printProfiles,
   printLoginHelp, printLogoutHelp, printSyncHelp,
   printActivateHelp, printLicenseHelp, printDeleteHelp,
   printProfilesHelp, printScheduleHelp,
@@ -142,28 +142,11 @@ switch (command) {
   }
 
   case 'history': {
-    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printHistoryHelp(); break; }
-    if (!isLicensed('pro')) { showUpgradePrompt('pro', 'ticketlens history'); break; }
-    const ticketKey = cmdArgs[0];
-    if (!ticketKey || ticketKey.startsWith('-')) {
-      process.stderr.write('Usage: ticketlens history TICKET-KEY\n');
+    const { runHistory } = await import('../skills/jtb/scripts/lib/run-history.mjs');
+    runHistory(cmdArgs).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
       process.exitCode = 1;
-      break;
-    }
-    const { queryTicketHistory } = await import('../skills/jtb/scripts/lib/triage-history.mjs');
-    const entries = queryTicketHistory(ticketKey);
-    if (entries.length === 0) {
-      process.stdout.write(`No triage history found for ${ticketKey}.\n`);
-      break;
-    }
-    const hs = createStyler({ isTTY: process.stdout.isTTY });
-    process.stdout.write(`\nHistory for ${hs.bold(ticketKey)} (${entries.length} entries)\n\n`);
-    for (const e of entries) {
-      const bounce = e.bounced ? hs.yellow(' ⟳ bounced') : '';
-      const urg = e.urgency === 'needs-response' ? hs.red(e.urgency) : e.urgency === 'aging' ? hs.yellow(e.urgency) : hs.green(e.urgency);
-      process.stdout.write(`  ${hs.dim(e.date)}  [${e.profile}]  ${urg}${bounce}  ${hs.dim(e.reason)}\n`);
-    }
-    process.stdout.write('\n');
+    });
     break;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.38.31",
+  "version": "0.38.33",
   "description": "Jira CLI for developers — fetch ticket context, triage your queue, and stop tab-switching. Zero dependencies, all local.",
   "type": "module",
   "bin": {

package/skills/jtb/SKILL.md

@@ -1,4 +1,4 @@
-<!-- jtb-skill-version: 0.36.0 -->
+<!-- jtb-skill-version: 0.38.0 -->
 ---
 name: jtb
 description: Fetch a Jira ticket's full context (description, comments, linked issues, code references) and assemble a structured TicketBrief for implementation planning. Use when user types /jtb, mentions a Jira ticket key, or wants to plan work from a Jira ticket.
@@ -125,6 +125,103 @@ Requires a Team license and at least one teammate in the same group. Compares yo
 
 Display the script's stdout directly. No plan mode. Stop here.
 
+If this harness has TicketLens's MCP server configured (a tool named `collisions` — often shown as `mcp__ticketlens__collisions` — visible in your tool list), prefer it over the bash form: same Team-license gate, same `ticketlens login` requirement, no shell command to construct. It accepts `json`/`plain`.
+
+---
+
+### Stats subcommand
+
+If the first argument is `stats`:
+
+Run:
+```bash
+ticketlens stats $EXTRA_ARGS
+```
+
+Where `$EXTRA_ARGS` are any flags passed (e.g. `--days=14 --format=json --profile=acme`).
+
+Shows response-time and triage-cadence metrics from local triage history: avg/median response time, clear rate, triage run count, current urgency breakdown. Read-only, entirely local — no network call. `--days=N` (default 7; Free silently caps at 7, Pro allows up to 30); `--format=plain` (default, human-readable table) or `--format=json` (scripting).
+
+Display the script's stdout directly. No plan mode. Stop here.
+
+If this harness has TicketLens's MCP server configured (a tool named `stats` — often shown as `mcp__ticketlens__stats` — visible in your tool list), prefer it over the bash form: same Free/Pro day-cap split, no shell command to construct. It accepts `profile`/`days`/`format`.
+
+---
+
+### History subcommand
+
+If the first argument is `history`:
+
+Run:
+```bash
+ticketlens history TICKET-KEY
+```
+
+Requires a ticket key as the first positional argument. Requires a Pro license.
+
+Shows the ticket's urgency timeline from local triage history — every prior triage scan that surfaced it, with the urgency level and reason computed at that point in time. Read-only, entirely local — no network call, no other flags.
+
+Display the script's stdout directly. No plan mode. Stop here.
+
+If this harness has TicketLens's MCP server configured (a tool named `history` — often shown as `mcp__ticketlens__history` — visible in your tool list), prefer it over the bash form: same Pro gate, no shell command to construct. It accepts `ticket`.
+
+---
+
+### Standup subcommand
+
+If the first argument is `standup`:
+
+Run:
+```bash
+ticketlens standup $EXTRA_ARGS
+```
+
+Where `$EXTRA_ARGS` are any flags passed (e.g. `--since=48 --format=pr --profile=acme`).
+
+Summarizes recent git commits grouped by linked ticket key. `--since=N` (hours, default 24) or a git-compatible date expression (`--since="3 days ago"`); `--format=standup` (default) renders a per-ticket standup update, `--format=pr` renders the same grouped commits as PR-body-style markdown. Read-only, fully free tier — no license gate on any option.
+
+Display the script's stdout directly. No plan mode. Stop here.
+
+If this harness has TicketLens's MCP server configured (a tool named `standup` — often shown as `mcp__ticketlens__standup` — visible in your tool list), prefer it over the bash form: same output, no license gate, no shell command to construct. It accepts `since`/`format`/`profile`.
+
+---
+
+### PR subcommand
+
+If the first argument is `pr`:
+
+Run:
+```bash
+ticketlens pr PROJ-123 $EXTRA_ARGS
+```
+
+Where `$EXTRA_ARGS` are any flags passed (e.g. `--profile=acme`). Requires a ticket key as the first positional argument.
+
+Assembles a ready-to-paste PR description: what changed (from commits linked to the ticket), linked tickets, and — if the ticket has acceptance criteria — a requirements-coverage section. Read-only. The requirements-coverage section reuses the same Free-tier 3-checks/month counter as `--compliance`/`ticketlens compliance` — running `pr` on a ticket with acceptance criteria counts against that shared monthly limit; Pro removes the cap.
+
+Display the script's stdout directly. No plan mode. Stop here.
+
+If this harness has TicketLens's MCP server configured (a tool named `pr` — often shown as `mcp__ticketlens__pr` — visible in your tool list), prefer it over the bash form: same output, same shared compliance-counter caveat, no shell command to construct. It accepts `ticket`/`profile`.
+
+---
+
+### Review subcommand
+
+If the first argument is `review`:
+
+Run:
+```bash
+ticketlens review $EXTRA_ARGS
+```
+
+Where `$EXTRA_ARGS` are any flags passed (e.g. `--base=develop --profile=acme`). No required positional argument — operates on the current branch.
+
+Assembles PR review context from the current git branch: changed files, linked-ticket summaries from commits/branch name, and (Pro) a requirements-coverage / review-focus section extracted from the diff against acceptance criteria. `--base=BRANCH` (or its alias `--branch=BRANCH`) sets the diff base, auto-detecting `main`/`master`/`develop` when omitted. Read-only — never modifies the tracker or the repo. Free tier gets branch info, changed files, and ticket context; Pro adds the requirements-coverage and review-focus sections — same split as `--compliance`.
+
+Display the script's stdout directly. No plan mode. Stop here.
+
+If this harness has TicketLens's MCP server configured (a tool named `review` — often shown as `mcp__ticketlens__review` — visible in your tool list), prefer it over the bash form: same tier gate (Free: branch/files/tickets, Pro: +coverage/focus), no shell command to construct. It accepts `base`/`branch`/`profile` — `base` and `branch` are aliases; if both are given, `base` wins.
+
 ---
 
 ### Fetch ticket workflow (default)

package/skills/jtb/hooks/recall-nudge-lib.mjs

@@ -99,6 +99,50 @@ export function hasRecentCapture(cwd, now = Date.now()) {
   return lastCaptureAt > 0 && (now - lastCaptureAt) < CAPTURE_FRESHNESS_MS;
 }
 
+/**
+ * Cross-session NAG marker (backlog #14) — same shape as lastCapturePath/
+ * readLastCaptureAt/writeLastCaptureAt/hasRecentCapture above, but records
+ * "we already blocked once for this directory" instead of "a note was
+ * added". Closes a gap those functions never covered: they bridge a
+ * session_id rollover only when a REAL capture landed, but a dismissed nag
+ * ("genuinely nothing qualified" — the hook's own suggested response) was
+ * never remembered anywhere. Since compaction/resume mints a brand-new
+ * session_id (see recall-nudge-stop.mjs's docstring), and that resets the
+ * per-session_id stopChecked gate, one long working session with several
+ * compaction cycles could get nagged repeatedly for the same still-ongoing
+ * work — a real, reported friction source (backlog #14), not hypothetical.
+ * Deliberately a separate marker file from lastCapture (not folded into
+ * it): a nag and a capture are different facts, and conflating them would
+ * make hasRecentCapture's "a real capture landed" guarantee ambiguous.
+ * Reuses CAPTURE_FRESHNESS_MS rather than a second magic number — the same
+ * 2-hour window is a reasonable proxy for "still the same working session"
+ * in both cases, and a distinct constant isn't justified by anything
+ * observed so far.
+ */
+export function lastNagPath(cwd) {
+  const hash = crypto.createHash('sha256').update(cwd || 'unknown').digest('hex').slice(0, 16);
+  return path.join(privateTmpDir(), `lastnag-${hash}.json`);
+}
+
+export function readLastNagAt(cwd) {
+  try {
+    return JSON.parse(fs.readFileSync(lastNagPath(cwd), 'utf8')).lastNagAt ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+export function writeLastNagAt(cwd, timestamp) {
+  try {
+    fs.writeFileSync(lastNagPath(cwd), JSON.stringify({ lastNagAt: timestamp }));
+  } catch { /* best-effort — losing this marker only costs one extra nag next rollover */ }
+}
+
+export function hasRecentNag(cwd, now = Date.now()) {
+  const lastNagAt = readLastNagAt(cwd);
+  return lastNagAt > 0 && (now - lastNagAt) < CAPTURE_FRESHNESS_MS;
+}
+
 /**
  * Reads the transcript (JSONL) and returns simple booleans about what
  * happened this session. Best-effort: any read/parse failure returns all

package/skills/jtb/hooks/recall-nudge-stop.mjs

@@ -15,7 +15,12 @@
  * survive a compaction/resume event — that hands this hook a brand-new
  * session_id, a blank dedup state, AND a blank transcript file, so a real
  * earlier capture becomes invisible. The cross-session lastCapture marker
- * (keyed by cwd, not session_id) is what actually bridges that boundary.
+ * (keyed by cwd, not session_id) is what actually bridges that boundary
+ * for a genuine capture. The parallel lastNag marker (backlog #14) bridges
+ * the same boundary for a DISMISSED nag: without it, a session that already
+ * got its one nag and was told "genuinely nothing qualified" would nag
+ * again after the next compaction/resume rollover, since that dismissal
+ * was never recorded anywhere — only a real capture was.
  *
  * Which of the two cases above actually blocks is governed by the active
  * profile's recallStrictness — see recall-nudge-lib.mjs's shouldNag() doc
@@ -30,7 +35,7 @@
  * profile, same as before (backlog #12, design spec §6).
  */
 
-import { readStdinJson, readState, writeState, scanTranscript, hasRecentCapture, writeLastCaptureAt, shouldNag } from './recall-nudge-lib.mjs';
+import { readStdinJson, readState, writeState, scanTranscript, hasRecentCapture, writeLastCaptureAt, hasRecentNag, writeLastNagAt, shouldNag } from './recall-nudge-lib.mjs';
 import { resolveProfile, normalizeRecallStrictness } from '../scripts/lib/profile-resolver.mjs';
 
 const input = readStdinJson();
@@ -61,8 +66,13 @@ if (hasRecentCapture(cwd)) {
   process.exit(0); // a real capture landed recently in this same directory, just under a different session_id
 }
 
+if (hasRecentNag(cwd)) {
+  process.exit(0); // already nagged recently in this same directory, just under a different session_id — a compaction/resume rollover, not a fresh session (backlog #14)
+}
+
 state.stopChecked = true;
 writeState(sessionId, state);
+writeLastNagAt(cwd, Date.now());
 
 if (sawRecallFlag) {
   process.stderr.write(

package/skills/jtb/scripts/fetch-ticket.mjs

@@ -336,17 +336,20 @@ async function countRecallInjection(recallNotes, configDir, opts) {
   }
 }
 
-function makeSpinner(s) {
-  // setInterval won't fire while spawnSync blocks the event loop, so we draw
-  // synchronously on update() and only use setInterval during async fetch phases.
-  if (!process.stderr.isTTY) return { update: () => {}, startAnim: () => {}, done: () => {} };
+// setInterval won't fire while spawnSync blocks the event loop, so we draw
+// synchronously on update() and only use setInterval during async fetch phases.
+// Both callers pass run()'s errStream, so the spinner shares the same isTTY and
+// write target as everything else the command emits: the real process.stderr for
+// a CLI user, the captured printErr under MCP (where the draws must not leak).
+function makeSpinner(s, { isTTY, write }) {
+  if (!isTTY) return { update: () => {}, startAnim: () => {}, done: () => {} };
   const frames = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'];
   let fi = 0, msg = '', lastW = 0, timerId = null, finished = false;
 
   const draw = () => {
     const raw = `  ${s.brand(frames[fi % frames.length])} ${s.dim(msg)}`;
     const vis = raw.replace(/\x1b\[[0-9;]*m/g, '');
-    process.stderr.write(`\r${raw}${' '.repeat(Math.max(0, lastW - vis.length))}`);
+    write(`\r${raw}${' '.repeat(Math.max(0, lastW - vis.length))}`);
     lastW = vis.length;
   };
 
@@ -360,7 +363,7 @@ function makeSpinner(s) {
       if (finished) return;
       finished = true;
       if (timerId) { clearInterval(timerId); timerId = null; }
-      process.stderr.write('\r\x1b[2K');
+      write('\r\x1b[2K');
     },
   };
 }
@@ -485,10 +488,10 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   }
 
   const printFn = opts.print ?? ((chunk) => process.stdout.write(chunk));
-  // Mirrors printFn above — only the bare ticket-fetch path (from `const ticketKey =
-  // args.find(...)` onward) uses this; pr/ledger/compliance/review/standup/install-hooks
-  // above still write directly to the real process.stderr (out of scope for this change,
-  // each gets the same treatment when its own MCP tool is built).
+  // Mirrors printFn above — the bare ticket-fetch, compliance, pr, review, and standup
+  // paths all use this now (each has an MCP tool). `ledger` above still writes directly
+  // to the real process.stderr (no MCP tool yet); `install-hooks` is CLI-only and never
+  // gets one.
   const printErrFn = opts.printErr ?? ((chunk) => process.stderr.write(chunk));
   // Reused on every recursive self-call in the bare-fetch path (profile-prompt retries)
   // so an injected print/printErr survives the retry instead of silently reverting to
@@ -508,7 +511,9 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   const errStream = { write: printErrFn, isTTY };
 
   if (args.includes('--help') || args.includes('-h')) {
-    printFetchHelp();
+    // stdout's own isTTY, not the `isTTY` above (that one is documented as
+    // reflecting process.stderr.isTTY for the stderr-bound helpers below).
+    printFetchHelp({ stream: { write: printFn, isTTY: process.stdout.isTTY } });
     return;
   }
 
@@ -549,12 +554,12 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     const { assemblePr } = await import('./lib/pr-assembler.mjs');
     const ticketKeyArg = args[1];
     if (!ticketKeyArg) {
-      process.stderr.write('Error: "pr" requires a ticket key. Usage: ticketlens pr PROJ-123\n');
+      printErrFn('Error: "pr" requires a ticket key. Usage: ticketlens pr PROJ-123\n');
       process.exitCode = 1;
       return;
     }
     if (!TICKET_KEY_PATTERN.test(ticketKeyArg)) {
-      process.stderr.write(`Error: "${ticketKeyArg}" is not a valid ticket key. Expected format: PROJ-123\n`);
+      printErrFn(`Error: "${ticketKeyArg}" is not a valid ticket key. Expected format: PROJ-123\n`);
       process.exitCode = 1;
       return;
     }
@@ -568,27 +573,33 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       configDir: resolvedConfigDir,
       profileName: profileNamePr,
       cwd: process.cwd(),
-      onWarning: (w) => process.stderr.write(w + '\n'),
+      onWarning: (w) => printErrFn(w + '\n'),
       onProfileNotFound: () => {},
     });
 
     const hasAuthPr = connPr.pat || (connPr.email && connPr.apiToken);
     if (!connPr.baseUrl || !hasAuthPr) {
-      process.stderr.write('Error: No Jira credentials found. Run \'ticketlens init\' or set JIRA_BASE_URL + JIRA_API_TOKEN.\n');
+      printErrFn('Error: No Jira credentials found. Run \'ticketlens init\' or set JIRA_BASE_URL + JIRA_API_TOKEN.\n');
       process.exitCode = 1;
       return;
     }
 
     const adapterPr = resolveAdapter(connPr, { fetcher });
+    const complianceRunnerPr = opts.runComplianceCheck ?? runComplianceCheck;
 
     try {
       const md = await assemblePr(ticketKeyArg, {
         configDir: resolvedConfigDir,
         fetchTicketFn: (key, fOpts = {}) => adapterPr.fetchTicket(key, fOpts),
+        // assemblePr's own runComplianceCheckFn default has no stream override
+        // (compliance-checker.mjs's `stream = process.stderr`), so the Pro-gate
+        // upgrade prompt would leak to real stderr unless threaded here — same
+        // treatment as the compliance dispatch block above (`stream: errStream`).
+        runComplianceCheckFn: (o) => complianceRunnerPr({ ...o, stream: errStream }),
       });
       printFn(md + '\n');
     } catch (err) {
-      process.stderr.write(`Error: ${err.message}\n`);
+      printErrFn(`Error: ${err.message}\n`);
       process.exitCode = 1;
     }
     return;
@@ -710,7 +721,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     const execFn = opts.execFn ?? spawnSync;
     const cwd = process.cwd();
 
-    const sErr = createStyler({ isTTY: process.stderr.isTTY });
+    const sErr = createStyler({ isTTY });
 
     // Validate flags before any git work
     const reviewFlags = args.slice(1);
@@ -721,28 +732,28 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       // Detect --profile-NAME typo (dash instead of =)
       const profileDashM = flag.match(/^--profile-(.+)$/);
       if (profileDashM) {
-        process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--profile=${profileDashM[1]}`)}?\n`);
+        printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--profile=${profileDashM[1]}`)}?\n`);
         process.exitCode = 1;
         return;
       }
       const baseDashM = flag.match(/^--base-(.+)$/);
       if (baseDashM) {
-        process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--base=${baseDashM[1]}`)}?\n`);
+        printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--base=${baseDashM[1]}`)}?\n`);
         process.exitCode = 1;
         return;
       }
       const branchDashM = flag.match(/^--branch-(.+)$/);
       if (branchDashM) {
-        process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--branch=${branchDashM[1]}`)}?\n`);
+        printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--branch=${branchDashM[1]}`)}?\n`);
         process.exitCode = 1;
         return;
       }
-      process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Usage: ${sErr.cyan('ticketlens review [--base=BRANCH] [--branch=BRANCH] [--profile=NAME]')}\n`);
+      printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Usage: ${sErr.cyan('ticketlens review [--base=BRANCH] [--branch=BRANCH] [--profile=NAME]')}\n`);
       process.exitCode = 1;
       return;
     }
 
-    const spinner = makeSpinner(sErr);
+    const spinner = makeSpinner(sErr, errStream);
     const stderrNotes = [];
 
     // Resolve base branch: --base=BRANCH or auto-detect main/master/develop
@@ -756,7 +767,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       const verifyR = execFn('git', ['rev-parse', '--verify', baseBranch], { encoding: 'utf8', cwd, timeout: 5_000 });
       if (verifyR.status !== 0) {
         spinner.done();
-        process.stderr.write(`${sErr.red('✖')} Branch "${baseBranch}" not found in this repository.\n`);
+        printErrFn(`${sErr.red('✖')} Branch "${baseBranch}" not found in this repository.\n`);
         process.exitCode = 1;
         return;
       }
@@ -794,10 +805,10 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       const profiles = loadProfiles(resolvedConfigDir);
       if (!profiles?.profiles?.[profileNameR]) {
         spinner.done();
-        process.stderr.write(`${sErr.red('✖')} Profile "${profileNameR}" not found.\n`);
+        printErrFn(`${sErr.red('✖')} Profile "${profileNameR}" not found.\n`);
         const names = Object.keys(profiles?.profiles ?? {});
-        if (names.length > 0) process.stderr.write(`  ${sErr.dim('Available:')} ${names.join(', ')}\n`);
-        else process.stderr.write(`  Run ${sErr.cyan('ticketlens init')} to configure a profile.\n`);
+        if (names.length > 0) printErrFn(`  ${sErr.dim('Available:')} ${names.join(', ')}\n`);
+        else printErrFn(`  Run ${sErr.cyan('ticketlens init')} to configure a profile.\n`);
         process.exitCode = 1;
         return;
       }
@@ -839,8 +850,8 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     }
 
     spinner.done();
-    for (const note of stderrNotes) process.stderr.write(note + '\n');
-    if (stderrNotes.length > 0) process.stderr.write('\n');
+    for (const note of stderrNotes) printErrFn(note + '\n');
+    if (stderrNotes.length > 0) printErrFn('\n');
 
     const isLic = opts.isLicensedFn ?? ((tier) => isLicensed(tier, resolvedConfigDir));
     const assembleFn = opts.assemblePrReviewFn ?? assemblePrReview;
@@ -867,7 +878,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     const resolvedConfigDir = configDir ?? (await import('./lib/config.mjs')).DEFAULT_CONFIG_DIR;
     const execFn = opts.execFn ?? spawnSync;
     const cwd = process.cwd();
-    const sErr = createStyler({ isTTY: process.stderr.isTTY });
+    const sErr = createStyler({ isTTY });
 
     const standupFlags = args.slice(1);
 
@@ -878,29 +889,29 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
 
       const sinceDashM = flag.match(/^--since-(.+)$/);
       if (sinceDashM) {
-        process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--since=${sinceDashM[1]}`)}?\n`);
+        printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--since=${sinceDashM[1]}`)}?\n`);
         process.exitCode = 1;
         return;
       }
       const formatDashM = flag.match(/^--format-(.+)$/);
       if (formatDashM) {
-        process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--format=${formatDashM[1]}`)}?\n`);
+        printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--format=${formatDashM[1]}`)}?\n`);
         process.exitCode = 1;
         return;
       }
       const profileDashM = flag.match(/^--profile-(.+)$/);
       if (profileDashM) {
-        process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--profile=${profileDashM[1]}`)}?\n`);
+        printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--profile=${profileDashM[1]}`)}?\n`);
         process.exitCode = 1;
         return;
       }
       const formatValueM = flag.match(/^--format=(.+)$/);
       if (formatValueM) {
-        process.stderr.write(`${sErr.red('✖')} Invalid --format value: "${formatValueM[1]}". Expected: standup or pr\n`);
+        printErrFn(`${sErr.red('✖')} Invalid --format value: "${formatValueM[1]}". Expected: standup or pr\n`);
         process.exitCode = 1;
         return;
       }
-      process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Usage: ${sErr.cyan('ticketlens standup [--since=N] [--format=standup|pr] [--profile=NAME]')}\n`);
+      printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Usage: ${sErr.cyan('ticketlens standup [--since=N] [--format=standup|pr] [--profile=NAME]')}\n`);
       process.exitCode = 1;
       return;
     }
@@ -921,16 +932,16 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     if (profileNameS) {
       const profiles = loadProfiles(resolvedConfigDir);
       if (!profiles?.profiles?.[profileNameS]) {
-        process.stderr.write(`${sErr.red('✖')} Profile "${profileNameS}" not found.\n`);
+        printErrFn(`${sErr.red('✖')} Profile "${profileNameS}" not found.\n`);
         const names = Object.keys(profiles?.profiles ?? {});
-        if (names.length > 0) process.stderr.write(`  ${sErr.dim('Available:')} ${names.join(', ')}\n`);
-        else process.stderr.write(`  Run ${sErr.cyan('ticketlens init')} to configure a profile.\n`);
+        if (names.length > 0) printErrFn(`  ${sErr.dim('Available:')} ${names.join(', ')}\n`);
+        else printErrFn(`  Run ${sErr.cyan('ticketlens init')} to configure a profile.\n`);
         process.exitCode = 1;
         return;
       }
     }
 
-    const spinner = makeSpinner(sErr);
+    const spinner = makeSpinner(sErr, errStream);
     const stderrNotes = [];
 
     spinner.update('Scanning git log…');
@@ -977,8 +988,8 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     }
 
     spinner.done();
-    for (const note of stderrNotes) process.stderr.write(note + '\n');
-    if (stderrNotes.length > 0) process.stderr.write('\n');
+    for (const note of stderrNotes) printErrFn(note + '\n');
+    if (stderrNotes.length > 0) printErrFn('\n');
 
     const isPlain = standupFlags.includes('--plain');
     const assembleStandupFn = opts.assembleStandupFn ?? assembleStandup;

package/skills/jtb/scripts/lib/help.mjs

@@ -645,17 +645,25 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
     `  ${s.bold(s.brand('ticketlens'))} ${s.bold('mcp')}`,
     '',
     `  Start an MCP (Model Context Protocol) stdio server exposing CLI actions as`,
-    `  native tools — ${s.cyan('fetch')}, ${s.cyan('triage')}, ${s.cyan('compliance')}, ${s.cyan('doctor')}, ${s.cyan('recall_add')}, ${s.cyan('recall_search')}, ${s.cyan('ticket_comment')},`,
-    `  ${s.cyan('ticket_transition')}, ${s.cyan('ticket_assign')}, ${s.cyan('ticket_duplicates')}, ${s.cyan('ticket_link')}, ${s.cyan('ticket_update')}, ${s.cyan('ticket_create')} — for any`,
+    `  native tools — ${s.cyan('fetch')}, ${s.cyan('triage')}, ${s.cyan('compliance')}, ${s.cyan('review')}, ${s.cyan('standup')}, ${s.cyan('pr')}, ${s.cyan('stats')}, ${s.cyan('history')},`,
+    `  ${s.cyan('collisions')}, ${s.cyan('doctor')}, ${s.cyan('recall_add')}, ${s.cyan('recall_search')}, ${s.cyan('ticket_comment')}, ${s.cyan('ticket_transition')},`,
+    `  ${s.cyan('ticket_assign')}, ${s.cyan('ticket_duplicates')}, ${s.cyan('ticket_link')}, ${s.cyan('ticket_update')}, ${s.cyan('ticket_create')} — for any`,
     `  MCP-compatible AI harness, not just Claude Code. Thin adapter over the same`,
-    `  code as ${s.cyan('TICKET-KEY')}/${s.cyan('doctor')}/${s.cyan('triage')}/${s.cyan('compliance')}/${s.cyan('note add')}/${s.cyan('recall')}/${s.cyan('comment')}/${s.cyan('transition')}/${s.cyan('assign')}/${s.cyan('duplicates')}/${s.cyan('link')}/${s.cyan('update')}/${s.cyan('create')}`,
-    `  above. ${s.cyan('fetch')} and ${s.cyan('doctor')} are Free; ${s.cyan('triage')} is Free with some Pro/Team-gated`,
-    `  options (see ${s.cyan('ticketlens triage --help')}); ${s.cyan('compliance')} is Free with a 3-checks/month cap,`,
-    `  Pro unlimited; every other tool needs Pro. ${s.cyan('ticket_transition')} is`,
-    `  destructive when called with \`target\`+\`confirm: true\`; ${s.cyan('ticket_assign')} is currently`,
-    `  self-assign only; ${s.cyan('ticket_duplicates')} is read-only; ${s.cyan('ticket_link')} on GitHub closes the`,
-    `  source issue as a duplicate — different semantics than Jira/Linear's relationship-only`,
-    `  add; ${s.cyan('ticket_update')} has no priority field on GitHub and can partially succeed;`,
+    `  code as ${s.cyan('TICKET-KEY')}/${s.cyan('doctor')}/${s.cyan('triage')}/${s.cyan('compliance')}/${s.cyan('review')}/${s.cyan('standup')}/${s.cyan('pr')}/${s.cyan('stats')}/${s.cyan('history')}/${s.cyan('collisions')}/`,
+    `  ${s.cyan('note add')}/${s.cyan('recall')}/${s.cyan('comment')}/${s.cyan('transition')}/${s.cyan('assign')}/${s.cyan('duplicates')}/${s.cyan('link')}/${s.cyan('update')}/${s.cyan('create')} above.`,
+    `  ${s.cyan('fetch')}, ${s.cyan('doctor')}, and ${s.cyan('standup')} are Free; ${s.cyan('triage')} is Free with some Pro/Team-gated`,
+    `  options (see ${s.cyan('ticketlens triage --help')}); ${s.cyan('compliance')} and ${s.cyan('pr')} are Free, sharing a`,
+    `  3-checks/month cap on their requirements-coverage section, Pro unlimited;`,
+    `  ${s.cyan('review')} is Free for branch/files/ticket context — its coverage/focus section`,
+    `  requires Pro as a plain license check, not a draw on that same counter;`,
+    `  ${s.cyan('stats')} is Free with a 7-day lookback, Pro extends it to 30 days, same split`,
+    `  as ${s.cyan('ticketlens stats --help')}; ${s.cyan('history')} is entirely local and requires Pro;`,
+    `  ${s.cyan('collisions')} requires ${s.cyan('ticketlens login')} (Console access) plus a Team license — every`,
+    `  other tool needs Pro. ${s.cyan('ticket_transition')} is destructive when called with`,
+    `  \`target\`+\`confirm: true\`; ${s.cyan('ticket_assign')} is currently self-assign only;`,
+    `  ${s.cyan('ticket_duplicates')} is read-only; ${s.cyan('ticket_link')} on GitHub closes the source issue as a`,
+    `  duplicate — different semantics than Jira/Linear's relationship-only add;`,
+    `  ${s.cyan('ticket_update')} has no priority field on GitHub and can partially succeed;`,
     `  ${s.cyan('ticket_create')} has no ticket key to target — --profile/the default profile picks the`,
     `  tracker, and it fabricates a real item, the highest blast radius of this family.`,
     `  Long-running — exits when the client closes stdin.`,