ticketlens 0.16.1 → 0.17.0

package/README.md

@@ -394,7 +394,9 @@ Save short notes to yourself — gotchas, context, decisions — and they're aut
 
 The note body is read from stdin, not a flag — this avoids shell-quoting issues with multi-line text. A note can be tied to one ticket (`--ticket=KEY`), or left general (omit `--ticket`) for onboarding-style knowledge that isn't about a specific ticket. Add `--include-attachments` to seed the note with text from that ticket's already-cached attachments (`.txt`/`.md`/`.csv`/`.json` only).
 
-Every note is scanned before saving — anything shaped like a real secret (API key, private key, token) is rejected outright, never silently redacted. Requires a Pro license.
+Every note is scanned before saving — anything shaped like a real secret (API key, private key, token) is rejected outright, never silently redacted. An empty, placeholder (`TODO`, `WIP`, …), or too-short body is rejected the same way. Requires a Pro license.
+
+**Quality loop:** inside a Claude Code session using the jtb skill, a saved note can be silently refined afterward — a generator subagent drafts a more actionable version, a validator subagent checks it against other notes on the same ticket for duplication, up to 3 rounds — and the improved draft overwrites the original via the internal `note patch` command (not typically invoked by hand). This makes zero API calls and costs zero extra tokens beyond your already-running session; it never runs for a bare shell invocation of `note add`, which is skipped silently. Known limitation: a refined draft is not re-synced to your team even if the original was — teammates who already pulled the note keep the earlier draft.
 
 **Team sync:** on a Team plan with Recall enabled for your account (owner-managed, per-tier or per-client), notes also sync to your team's shared pool — `note add` pushes in the background, `recall` pulls the team's notes (cached 4h) before searching. A team manager reviews and verifies incoming notes at `console/admin/recall` before they're marked trusted. Without Team Recall entitlement, everything stays on your machine — no network call.
 

package/bin/ticketlens.mjs

@@ -610,18 +610,28 @@ switch (command) {
 
   case 'note': {
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printNoteHelp(); break; }
-    if (cmdArgs[0] !== 'add') {
-      process.stderr.write('Usage: ticketlens note add --title="..." [--ticket=KEY] [--tags=a,b]\n');
-      process.exitCode = 1;
+    if (cmdArgs[0] === 'add') {
+      const { runNoteAdd } = await import('../skills/jtb/scripts/lib/note-command.mjs');
+      runNoteAdd(cmdArgs.slice(1)).then(({ written }) => {
+        if (!written) process.exitCode = 1;
+      }).catch(err => {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exitCode = 1;
+      });
       break;
     }
-    const { runNoteAdd } = await import('../skills/jtb/scripts/lib/note-command.mjs');
-    runNoteAdd(cmdArgs.slice(1)).then(({ written }) => {
-      if (!written) process.exitCode = 1;
-    }).catch(err => {
-      process.stderr.write(`Error: ${err.message}\n`);
-      process.exitCode = 1;
-    });
+    if (cmdArgs[0] === 'patch') {
+      const { runNotePatch } = await import('../skills/jtb/scripts/lib/note-command.mjs');
+      runNotePatch(cmdArgs.slice(1)).then(({ patched }) => {
+        if (!patched) process.exitCode = 1;
+      }).catch(err => {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exitCode = 1;
+      });
+      break;
+    }
+    process.stderr.write('Usage: ticketlens note add --title="..." [--ticket=KEY] [--tags=a,b]\n');
+    process.exitCode = 1;
     break;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "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.16.1 -->
+<!-- jtb-skill-version: 0.17.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.
@@ -219,6 +219,27 @@ echo "The body text of the note, one or more paragraphs." | \
 
 To search saved notes directly (outside of automatic brief injection): `ticketlens recall "<query>"`.
 
+### Quality loop (Pro, in-session only)
+
+Only when `note add` above was dispatched *by you, inside this skill*, and it printed a saved note id (e.g. `Saved note "Retry gotcha" (1784135399545-fe01c4.md)`) — never for a note a user typed directly into a bare shell, which has no Task/Agent tool available. If there's no such tool in your environment, skip this whole section silently: no warning, no degraded fallback, the note is already saved and that's a complete, correct outcome on its own.
+
+When it does apply, run up to 3 rounds:
+
+1. **Capture the current state** before dispatching anything: get the note file's (`~/.ticketlens/recall/<PREFIX-or-_general>/<id>`) current mtime in epoch **milliseconds** — the shell `stat` command reports seconds on both macOS and Linux, which is the wrong unit and will make every patch silently no-op. Use `node -e "console.log(require('fs').statSync('PATH').mtimeMs)"` instead (Node is already required to run `ticketlens`). Also read the note's current body.
+2. **Generator** — a subagent drafts an improved body: concrete file/line references over vague prose, no invented facts not already established this session.
+3. **Validator** — a separate subagent scores the draft against two criteria: **actionability** (does it read like something a future session could act on directly?) and **non-duplication** (run `ticketlens recall "<query>" --ticket=TICKET-KEY` against the ticket this note is about — reject/rescore a draft that's a near-duplicate of an existing note).
+4. If the draft scores as a genuine improvement, write it back:
+   ```bash
+   echo "The improved body text." | \
+     ticketlens note patch --id="THE-ID-PRINTED-ABOVE" --ticket=TICKET-KEY --expect-mtime="THE-MTIME-FROM-STEP-1"
+   ```
+   `--expect-mtime` is what keeps this safe: if the file changed since step 1 (the user hand-edited it while you were drafting), the patch silently no-ops and prints "not found or already changed" — the user's own edit always wins, never gets clobbered by a stale background draft.
+5. Repeat from step 1 (re-capture mtime/body fresh each round) up to 3 total rounds. If no round ever produces a fully-passing draft, patch in whichever round scored highest across all attempts, and let the "not found or already changed" message stand if that patch itself loses a late race — don't retry past round 3.
+
+This never calls any external API or bills any tokens beyond the session you already have open — the generator and validator are subagents inside your own Claude Code session, not a TicketLens server call.
+
+**Known limitation:** `note patch` only updates the local vault copy. If `note add` already pushed the original draft to a team (Team Recall enabled), a later refinement from this loop is *not* re-pushed — teammates who already pulled the note keep the original draft until this is addressed in a future iteration.
+
 ### Privacy
 Recall notes are stored locally at `~/.ticketlens/recall/`. On a Free/Pro account with no Team Recall entitlement, they never leave the machine — no network calls. On a Team account with Recall enabled (owner-managed, may vary per user), notes also sync to the team's shared pool in the background so teammates can benefit from them too; a team manager reviews and verifies each incoming note before it's marked trusted.
 

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

@@ -511,6 +511,13 @@ export function printNoteHelp({ stream = process.stdout } = {}) {
     '',
     `    ${s.dim('$')} echo "Retry needs exponential backoff" | ticketlens note add --title="Retry gotcha" --ticket=PROD-123 --tags=bug`,
     '',
+    `  ${s.bold('ticketlens note patch')} ${s.dim('--id="..." [--ticket=KEY]')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Overwrites an existing note's body with a better draft, read from stdin.`,
+    `  Internal mechanism used by the jtb skill's note quality loop inside a Claude`,
+    `  Code session — not typically invoked by hand. Every note it writes gets the`,
+    `  same structural and secret-scan checks ${s.brand('note add')} applies to user input.`,
+    '',
   ];
   stream.write(lines.join('\n') + '\n');
 }

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

@@ -10,7 +10,8 @@ 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 { writeNote } from './recall-vault.mjs';
+import { checkNoteStructure } from './note-structural-check.mjs';
+import { writeNote, patchNoteBody } from './recall-vault.mjs';
 import { readCliToken } from './cli-auth.mjs';
 import { pushNote } from './recall-sync.mjs';
 import { incrementDraftKept, incrementDraftDeleted } from './activity-counter.mjs';
@@ -66,6 +67,7 @@ export async function runNoteAdd(cmdArgs, {
   stream = process.stderr,
   readStdin = defaultReadStdin,
   isLicensedFn = isLicensed,
+  checkNoteStructureFn = checkNoteStructure,
   scanForSecretsFn = scanForSecrets,
   writeNoteFn = writeNote,
   readCliTokenFn = readCliToken,
@@ -103,6 +105,13 @@ export async function runNoteAdd(cmdArgs, {
     body += gatherAttachmentExcerpts(configDir, ticketKey, listAttachmentsFn, extractTextFn);
   }
 
+  const structural = checkNoteStructureFn({ body });
+  if (structural.rejected) {
+    stream.write(`  Note not saved — ${structural.reason}\n`);
+    incrementDraftDeletedFn(configDir);
+    return { written: false };
+  }
+
   const scan = scanForSecretsFn({ title, tags, body });
   if (scan.rejected) {
     stream.write(`  Note not saved — ${scan.reasons.join(' ')}\n`);
@@ -132,3 +141,65 @@ export async function runNoteAdd(cmdArgs, {
 
   return { written: true };
 }
+
+/**
+ * Implements `tl note patch` — overwrites an existing note's body with a
+ * better draft. Internal plumbing for the jtb skill's quality loop (never
+ * meant to be typed by hand): the loop's generator subagent produces a body,
+ * SKILL.md's orchestration pipes it through this command, and the new body
+ * gets exactly the same structural and secret gates a user-typed body gets —
+ * there is no weaker path here for AI-authored content.
+ *
+ * @param {string[]} cmdArgs
+ * @returns {Promise<{ patched: boolean }>}
+ */
+export async function runNotePatch(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stderr,
+  readStdin = defaultReadStdin,
+  isLicensedFn = isLicensed,
+  checkNoteStructureFn = checkNoteStructure,
+  scanForSecretsFn = scanForSecrets,
+  patchNoteBodyFn = patchNoteBody,
+} = {}) {
+  if (!isLicensedFn('pro', configDir)) {
+    showUpgradePrompt('pro', 'ticketlens note', { stream });
+    return { patched: false };
+  }
+
+  const id = parseFlag(cmdArgs, 'id');
+  if (!id) {
+    stream.write('Usage: ticketlens note patch --id="..." [--ticket=KEY]\n');
+    return { patched: false };
+  }
+
+  const ticketKey = parseFlag(cmdArgs, 'ticket');
+  if (ticketKey && !TICKET_KEY_PATTERN.test(ticketKey)) {
+    stream.write(`  Invalid --ticket value "${ticketKey}" — expected a ticket key like PROJ-123.\n`);
+    return { patched: false };
+  }
+
+  const body = await readStdin();
+
+  const structural = checkNoteStructureFn({ body });
+  if (structural.rejected) {
+    stream.write(`  Note not updated — ${structural.reason}\n`);
+    return { patched: false };
+  }
+
+  const scan = scanForSecretsFn({ title: '', tags: [], body });
+  if (scan.rejected) {
+    stream.write(`  Note not updated — ${scan.reasons.join(' ')}\n`);
+    return { patched: false };
+  }
+  for (const warning of scan.warnings) {
+    stream.write(`  Warning: ${warning}\n`);
+  }
+
+  const ticketKeys = ticketKey ? [ticketKey] : [];
+  const expectMtimeArg = parseFlag(cmdArgs, 'expect-mtime');
+  const expectedMtimeMs = expectMtimeArg !== undefined ? Number(expectMtimeArg) : undefined;
+  const { patched } = patchNoteBodyFn({ id, ticketKeys, body, expectedMtimeMs }, { configDir });
+  stream.write(patched ? `  Updated note (${id})\n` : `  Note not updated — (${id}) not found or already changed.\n`);
+  return { patched };
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Deterministic, dependency-free structural gate for a Recall note's body —
+ * catches empty, placeholder, or too-thin content before it's ever written
+ * to the vault. Separate concern from secret-scanner.mjs: this never judges
+ * sensitivity, only whether there's real content here at all.
+ */
+
+const MIN_BODY_LENGTH = 10;
+
+const PLACEHOLDER_BODIES = new Set([
+  'todo', 'test', 'n/a', 'na', 'tbd', 'wip', 'placeholder',
+  'xxx', 'asdf', 'fixme', 'fix me', '.', '-',
+]);
+
+/**
+ * @param {{ body?: string }} note
+ * @returns {{ rejected: boolean, reason: string|null }}
+ */
+export function checkNoteStructure({ body = '' } = {}) {
+  const trimmed = body.trim();
+
+  if (trimmed.length === 0) {
+    return { rejected: true, reason: 'Note body is empty.' };
+  }
+  if (PLACEHOLDER_BODIES.has(trimmed.toLowerCase())) {
+    return { rejected: true, reason: `Note body "${trimmed}" looks like a placeholder, not real content.` };
+  }
+  if (trimmed.length < MIN_BODY_LENGTH) {
+    return { rejected: true, reason: `Note body is too short to be useful (minimum ${MIN_BODY_LENGTH} characters).` };
+  }
+
+  return { rejected: false, reason: null };
+}

package/skills/jtb/scripts/lib/recall-vault.mjs

@@ -164,6 +164,59 @@ export function deleteNote({ external_id: externalId, tickets = [] }, { configDi
   return { deleted: true, prefix };
 }
 
+/**
+ * Overwrites an existing local note's body in place — used by the jtb skill's
+ * generator/validator quality loop to swap in a better draft after `note add`
+ * already saved the original. Patch-only: never creates a note, and every
+ * frontmatter field except body is carried over unchanged, so this can never
+ * become a covert way to retitle/retag/re-tie a note to a different ticket.
+ *
+ * Guards, same failure-mode split as deleteNote: a malformed id or ticket key
+ * is a caller bug (throw); a missing file, an externalId that doesn't match
+ * what's on disk, or a body that changed since the caller last observed it
+ * (expectedMtimeMs) are all best-effort no-ops, not errors — the original
+ * note is always left exactly as-is on any of these.
+ *
+ * @param {{ id: string, ticketKeys?: string[], body: string, expectedMtimeMs?: number }} params
+ * @param {{ configDir?: string }} [opts]
+ * @returns {{ patched: boolean, path: string|null }}
+ */
+export function patchNoteBody({ id, ticketKeys = [], body, expectedMtimeMs }, { configDir = DEFAULT_CONFIG_DIR } = {}) {
+  if (!EXTERNAL_ID_PATTERN.test(id)) {
+    throw new Error(`Invalid note id: "${id}"`);
+  }
+
+  const prefix = resolvePrefix(ticketKeys[0]);
+  const notePath = path.join(prefixDir(configDir, prefix), id);
+
+  if (!fs.existsSync(notePath)) {
+    return { patched: false, path: null };
+  }
+  if (expectedMtimeMs !== undefined && fs.statSync(notePath).mtimeMs !== expectedMtimeMs) {
+    return { patched: false, path: notePath };
+  }
+
+  const existing = readNote(notePath);
+  if (!existing || existing.externalId !== id) {
+    return { patched: false, path: notePath };
+  }
+
+  const data = {
+    title: existing.title,
+    aliases: existing.aliases,
+    tickets: existing.tickets,
+    tags: existing.tags,
+    author: existing.author,
+    created: existing.created,
+    status: existing.status,
+    sources: existing.sources,
+    externalId: existing.externalId,
+  };
+
+  writeFileAtomically(notePath, serializeFrontmatter(data, body));
+  return { patched: true, path: notePath };
+}
+
 /**
  * Reads one note file. Never trusts the file completely — a note can be
  * hand-edited (README documents them as plain markdown, readable in any