ticketlens 0.38.44 → 0.38.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.38.44",
+  "version": "0.38.45",
   "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.42.3 -->
+<!-- jtb-skill-version: 0.42.4 -->
 ---
 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.
@@ -356,6 +356,8 @@ Example that qualifies: an undocumented schema quirk found only by reading raw D
 
 Do not capture: routine/obvious information, anything already fully covered by the ticket description or comments, or content shaped like a credential or API key — the tool rejects those outright at save time.
 
+**Length:** keep both the title and body brief — a sharp one- or two-sentence takeaway, not a paragraph. The recommended max scales with the same strictness level as the section above: 20 words (strict), 30 words (balanced, default), 50 words (loose). Going over doesn't block the save — the CLI/MCP tool prints a non-blocking warning so you can tighten it, the same way it prints warnings for a detected email address or similar low-severity secret-scan hit.
+
 Capture **at the moment you confirm the insight**, not deferred to the end of the session — don't ask the user first, just do it. It requires a Pro license; on a Free account it will no-op with an upgrade hint on stderr, which is fine to ignore. It never blocks or fails the session.
 
 Immediately before dispatching the call, say one line in your response: `🔖 Recall-flag: <one-line reason>`. This is a fixed marker some harness setups scan for to confirm captures are actually happening — always emit it right when you decide to capture, even if you go on to call `note add` in the same breath.
@@ -365,7 +367,7 @@ Immediately before dispatching the call, say one line in your response: `🔖 Re
 If your environment lets you dispatch a tool call without waiting for its result — a background task, an async subagent, a fire-and-forget job — try it **once**. If it errors for any reason, don't retry the background path — fall back to calling it synchronously immediately. It's fast and never blocks or fails your session either way, so the synchronous fallback costs nothing; repeatedly retrying a broken background mechanism only adds visible noise for no benefit.
 
 ```bash
-echo "The body text of the note, one or more paragraphs." | \
+echo "Retry client swallowed 429s silently; added backoff and a warning log on the third failure." | \
   ticketlens note add --title="Short title" --ticket=TICKET-KEY --tags=a,b
 ```
 

package/skills/jtb/scripts/lib/api-utils.mjs

@@ -3,7 +3,7 @@
  * Centralised here to avoid triplicating the regex and warning logic.
  */
 
-export const DEFAULT_API_BASE = 'http://api.ticketlens.test';
+export const DEFAULT_API_BASE = 'https://api.ticketlens.app';
 export const DEFAULT_SITE_BASE = 'https://ticketlens.app';
 
 // Matches localhost, 127.0.0.1, and any hostname ending in .test or .local,

package/skills/jtb/scripts/lib/mcp-tool-schemas.mjs

@@ -161,10 +161,10 @@ export const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        title: { type: 'string', description: 'Short one-line title.' },
+        title: { type: 'string', description: 'Short one-line title, ~20 (strict), 30 (balanced), or 50 (loose) words max — scales with recallStrictness — going over doesn\'t block the save, but prints a non-blocking warning.' },
         ticket: { type: 'string', description: 'Optional ticket key, e.g. PROJ-123.' },
         tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags derived from this note\'s actual content — the specific technology, error type, root cause, or affected component (e.g. "retry-backoff", "null-pointer", "auth-middleware"). Never the project name or a generic category word like "gotcha" or "bug" — those provide no search signal to someone else looking for this note later. A tag that just restates the title in different words, or one you cannot trace to a specific sentence in the body, gives that same zero signal — if you cannot point to the exact phrase that justifies it, drop it.' },
-        body: { type: 'string', description: 'The note body — one or more paragraphs.' },
+        body: { type: 'string', description: 'The note body — brief, not a paragraph. ~20 (strict), 30 (balanced), or 50 (loose) words max — scales with recallStrictness — going over doesn\'t block the save, but prints a non-blocking warning.' },
         attachments: { type: 'array', items: { type: 'string' }, description: 'Local file paths to attach (screenshots, logs, etc.), saved next to the note in the local vault. Same 10MB/file, 50MB/call, 20-file caps as ticket_comment/ticket_create for the local save. If this account is entitled and the note syncs to a team, attachments sync too — visible and downloadable from Console > Admin > Recall — but the sync path has a lower 12MB/call cap than the local save (backend request-size limit). Going over it fails the WHOLE push (note text included), not just the attachment; the note stays saved locally either way.' },
       },
       required: ['title', 'body'],
@@ -177,7 +177,7 @@ export const TOOLS = [
       type: 'object',
       properties: {
         id: { type: 'string', description: 'Note id to patch, as printed by recall_add or recall_search.' },
-        body: { type: 'string', description: 'The replacement note body.' },
+        body: { type: 'string', description: 'The replacement note body — brief, not a paragraph. ~20 (strict), 30 (balanced), or 50 (loose) words max — scales with recallStrictness — going over doesn\'t block the update, but prints a non-blocking warning.' },
         ticket: { type: 'string', description: 'Ticket key the note is about, e.g. PROJ-123. Optional — narrows the search when omitted, the vault is searched across all ticket prefixes.' },
         expectMtime: { type: 'number', description: 'The note file\'s mtime (ms) last observed by the caller. If the note changed since then, the patch is a no-op rather than an overwrite — optimistic concurrency, not a hard requirement.' },
       },

package/skills/jtb/scripts/lib/note-command.mjs

@@ -10,10 +10,10 @@ import path from 'node:path';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { isLicensed, showUpgradePrompt } from './license.mjs';
 import { scanForSecrets } from './secret-scanner.mjs';
-import { checkNoteStructure } from './note-structural-check.mjs';
+import { checkNoteStructure, checkWordCount, WORD_LIMITS } from './note-structural-check.mjs';
 import { writeNote, patchNoteBody, deleteNote, deleteNoteAnyPrefix, rebuildIndex } from './recall-vault.mjs';
 import { readCliToken } from './cli-auth.mjs';
-import { resolveProfile, loadProfileRecallTeamId } from './profile-resolver.mjs';
+import { resolveProfile, loadProfileRecallTeamId, normalizeRecallStrictness } from './profile-resolver.mjs';
 import { pushNote } from './recall-sync.mjs';
 import { enqueueNote, isRetryableFailure, maybeAutoFlush } from './recall-queue.mjs';
 import { incrementDraftKept, incrementDraftDeleted } from './activity-counter.mjs';
@@ -103,6 +103,7 @@ export async function runNoteAdd(cmdArgs, {
   readStdin = defaultReadStdin,
   isLicensedFn = isLicensed,
   checkNoteStructureFn = checkNoteStructure,
+  checkWordCountFn = checkWordCount,
   scanForSecretsFn = scanForSecrets,
   writeNoteFn = writeNote,
   readCliTokenFn = readCliToken,
@@ -153,6 +154,16 @@ export async function runNoteAdd(cmdArgs, {
     return { written: false };
   }
 
+  // Resolved once here (not just inside the push block below) so the
+  // word-count warning below can read this profile's recallStrictness
+  // regardless of whether a CLI token is configured for pushing.
+  const profile = resolveProfileFn(ticketKey || null, { configDir, cwd: process.cwd() });
+  const strictness = normalizeRecallStrictness(profile?.recallStrictness);
+  const wordCount = checkWordCountFn({ title, body }, { maxWords: WORD_LIMITS[strictness] });
+  for (const warning of wordCount.warnings) {
+    stream.write(`  Warning: ${warning}\n`);
+  }
+
   const scan = scanForSecretsFn({ title, tags, body });
   if (scan.rejected) {
     stream.write(`  Note not saved — ${scan.reasons.join(' ')}\n`);
@@ -187,7 +198,7 @@ export async function runNoteAdd(cmdArgs, {
     const warn = (s) => stream.write(s);
     // Field names match PushRequest's validation rules (external_id, tickets) —
     // the backend wire contract, not the local vault's internal camelCase shape.
-    const profile = resolveProfileFn(ticketKey || null, { configDir, cwd: process.cwd() });
+    // `profile` was already resolved above (needed there for the word-count check).
     const recallTeamId = profile ? loadProfileRecallTeamIdFn(profile.name, configDir) : null;
     const payload = { external_id: id, title, tickets: ticketKeys, tags, author, sources: [], body, captured_at: capturedAt.toISOString() };
     if (recallTeamId !== null) payload.group_id = recallTeamId;
@@ -225,6 +236,8 @@ export async function runNotePatch(cmdArgs, {
   readStdin = defaultReadStdin,
   isLicensedFn = isLicensed,
   checkNoteStructureFn = checkNoteStructure,
+  checkWordCountFn = checkWordCount,
+  resolveProfileFn = resolveProfile,
   scanForSecretsFn = scanForSecrets,
   patchNoteBodyFn = patchNoteBody,
 } = {}) {
@@ -253,6 +266,13 @@ export async function runNotePatch(cmdArgs, {
     return { patched: false };
   }
 
+  const profile = resolveProfileFn(ticketKey || null, { configDir, cwd: process.cwd() });
+  const strictness = normalizeRecallStrictness(profile?.recallStrictness);
+  const wordCount = checkWordCountFn({ body }, { maxWords: WORD_LIMITS[strictness] });
+  for (const warning of wordCount.warnings) {
+    stream.write(`  Warning: ${warning}\n`);
+  }
+
   const scan = scanForSecretsFn({ title: '', tags: [], body });
   if (scan.rejected) {
     stream.write(`  Note not updated — ${scan.reasons.join(' ')}\n`);

package/skills/jtb/scripts/lib/note-structural-check.mjs

@@ -31,3 +31,39 @@ export function checkNoteStructure({ body = '' } = {}) {
 
   return { rejected: false, reason: null };
 }
+
+// Backlog #18 — mandatory brevity cap, one entry per recallStrictness level.
+// Warning-only: a rambling note still saves, it just gets flagged so the
+// caller can tighten it, same non-blocking pattern scanForSecrets uses for
+// its `warnings` array.
+export const WORD_LIMITS = { strict: 20, balanced: 30, loose: 50 };
+
+function countWords(text) {
+  const trimmed = text.trim();
+  return trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
+}
+
+/**
+ * Warning-only companion to checkNoteStructure: flags a title/body that runs
+ * long instead of rejecting it. `maxWords` is a plain number so this stays
+ * dependency-free — the caller maps recallStrictness to a number.
+ *
+ * @param {{ title?: string, body?: string }} note
+ * @param {{ maxWords?: number }} opts
+ * @returns {{ warnings: string[] }}
+ */
+export function checkWordCount({ title = '', body = '' } = {}, { maxWords = WORD_LIMITS.balanced } = {}) {
+  const warnings = [];
+
+  const titleWords = countWords(title);
+  if (titleWords > maxWords) {
+    warnings.push(`Note title is ${titleWords} words (recommended max: ${maxWords}).`);
+  }
+
+  const bodyWords = countWords(body);
+  if (bodyWords > maxWords) {
+    warnings.push(`Note body is ${bodyWords} words (recommended max: ${maxWords}).`);
+  }
+
+  return { warnings };
+}