yt-briefing 0.13.0 → 0.14.0

package/.claude/skills/yt/SKILL.md

@@ -34,7 +34,7 @@ while true:
 **On `rating_needed` — literally:**
 
 - **A.** Take `out.summary` (markdown) and `out.pending` (metadata).
-- **B.** In the same turn, as **your chat text** (NOT command output — the UI does not show it), paste `summary` **verbatim**: no paraphrase, no shortening, no comment, no "see above". The user must see it before the popup. _(If the user says "I don't see the summary" — you skipped B.)_
+- **B.** In the same turn, as **your chat text** (NOT command output — the UI does not show it), paste `summary` **verbatim**: no paraphrase, no shortening, no comment, no "see above". The user must see it before the popup. B is **unconditional** — it does not depend on there being anything else to write, so an iteration that returns no `skipped` line still opens with the pasted summary, never straight with the tool call. _(If the user says "I don't see the summary" — you skipped B. In Claude Code a PreToolUse gate blocks the popup when the pending video's id is missing from your chat text; if it fires, paste the summary and ask again.)_
 - **C.** In the same message call `AskUserQuestion` — **1 call, 1 question** (everything in one step), phrased in `output_lang`:
   - The question (e.g. "Rating?") with three options whose descriptions explain: **OK** = neutral (no effect on the filter), **Weak** = worthless (teach the filter to skip such titles), **Research** = break the loop and dig into this video's content together. The digits never appear in the popup — internally map to `--rating`: **OK → 1, Weak → 0**; Research maps to no digit, it exits the loop (see Research mode). There is **no positive rating** — keeping the channel is the implicit positive; you only down-rate noise (`0`) or steer with a comment.
   - **Other** is the comment / stop / research channel (no second question): the user types free text. If it equals `stop` (case-insensitive, trimmed) — or the popup is dismissed (✕) — **end the loop**. If it **starts with `?`**, the text after the `?` is a **research question** → Research mode. Otherwise it is a **comment**: **distill** the user's raw text into a clean, generalizable rule, and infer the rating — clearly negative → `0`, otherwise → `1`.

package/README.md

@@ -134,6 +134,28 @@ Open your project in Claude Code or Cursor and run `/yt`. If it's not listed, st
 session. To install the skills again for another tool or project, run
 `npx yt-briefing install-skill` (it installs `/yt`, `/yt-transcribe`, and `/yt-search`).
 
+## Rating gate
+
+The loop only works if you see the summary *before* you rate it, and that is the one step an
+agent can silently drop — the popup still appears, you still answer, and the rating is recorded
+against a summary nobody read. On Claude Code the installer wires a `PreToolUse` hook into your
+project's `.claude/settings.json` that refuses the rating popup unless the video's summary is in
+the chat. It merges with your existing hooks and updates itself on reinstall. If that file isn't
+valid JSON the installer leaves it alone and says so — add the entry yourself:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "AskUserQuestion",
+        "hooks": [ { "type": "command", "command": "node \"node_modules/yt-briefing/dist/yt-summary-gate.js\"" } ] }
+    ]
+  }
+}
+```
+
+Other agents have no equivalent hook, so there the instruction in `SKILL.md` is what holds.
+
 ## Providers
 
 Any OpenAI-compatible endpoint works. Gemini 2.5 Flash is the easy default. It's fast, cheap,
@@ -150,7 +172,7 @@ YT_BRIEFING_LLM_MODEL=gemini-2.5-flash
 
 Want something else? Change those three lines for OpenRouter (`https://openrouter.ai/api/v1`),
 OpenAI (`https://api.openai.com/v1`), Anthropic (`https://api.anthropic.com/v1/`,
-e.g. `claude-sonnet-4-6`), or a local Ollama (`http://localhost:11434/v1`). Set
+e.g. `claude-sonnet-5`), or a local Ollama (`http://localhost:11434/v1`). Set
 `YT_BRIEFING_LLM_BASE_URL`, `_API_KEY`, and `_MODEL` in your root `.env` (see [Setup](#setup)).
 
 ## Why an API, not the agent's native model

package/dist/bootstrap.js

@@ -18,7 +18,7 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { DATA_DIR, BASE_DIR, PKG_ROOT, CHANNELS_DIR, CHANNELS_MD, STATE_MD, CONFIG_JSON, profilePath, ROOT_ENV_PATH, } from "./lib/paths.js";
 import { loadEnv, missingEnv, REQUIRED_LLM, REQUIRED_YOUTUBE } from "./lib/env.js";
-import { AGENTS, installSkills, projectSkillsRoot, customSkillsRootDefault, isPackageDevCwd } from "./lib/skill-install.js";
+import { AGENTS, installSkills, projectSkillsRoot, customSkillsRootDefault, isPackageDevCwd, installClaudeGate, CLAUDE_CODE } from "./lib/skill-install.js";
 import { question } from "./lib/prompt.js";
 import { normalizeHandle, slugify, serializeChannels, serializeState, profileBody, baselineStateRow } from "./lib/channels.js";
 const ask = (q, def = '') => {
@@ -117,6 +117,14 @@ function main() {
             : installSkills(customDir, /* dist */ true);
         for (const t of targets)
             console.log(`    skill → ${t}`);
+        // Claude Code also gets the summary gate — the hook that refuses a rating popup for a video
+        // whose summary was never pasted into the chat. No other agent exposes PreToolUse.
+        if (agentKey === CLAUDE_CODE) {
+            const gate = installClaudeGate(process.cwd(), /* dist */ !isPackageDevCwd());
+            console.log(gate
+                ? `    gate  → ${gate}`
+                : `  ! .claude/settings.json isn't valid JSON — add the summary gate by hand (README → Rating gate).`);
+        }
     }
     catch (e) {
         console.log(`  ! Couldn't install the skills (${e.message}) — run  yt-briefing install-skill  later.`);

package/dist/install-skill.js

@@ -16,15 +16,21 @@
  * agent (Claude Code, Cursor, Codex, and 30+ others); this command just (re)places them in the
  * skills dir of whichever agent you pick.
  */
-import { AGENTS, installSkills, projectSkillsRoot, customSkillsRootDefault, isPackageDevCwd } from "./lib/skill-install.js";
+import { AGENTS, installSkills, projectSkillsRoot, customSkillsRootDefault, isPackageDevCwd, installClaudeGate, CLAUDE_CODE } from "./lib/skill-install.js";
 import { question } from "./lib/prompt.js";
 const ask = (q, def = '') => question(def ? `${q} [${def}]:` : `${q}:`).trim() || def;
-function done(targets) {
+function done(targets, gate) {
     console.log('\n  ✓ Installed:');
     for (const t of targets)
         console.log(`      ${t}`);
+    if (gate)
+        console.log(`      ${gate}  (summary gate)`);
+    if (gate === null)
+        console.log(`  ! .claude/settings.json isn't valid JSON — add the summary gate by hand (README → Rating gate).`);
     console.log('  Start a fresh agent session, then run  /yt  or  /yt-transcribe\n');
 }
+/** Claude Code only: the PreToolUse hook that blocks a rating popup with no summary in the chat. */
+const gateFor = (key, projectDir, dist) => key === CLAUDE_CODE ? installClaudeGate(projectDir, dist) : undefined;
 // 1) which agent → which skills subdir
 console.log('\n  Install the /yt + /yt-transcribe skills — which agent?\n');
 console.log('    1) Claude Code');
@@ -46,10 +52,12 @@ console.log('    1) This project (current folder) — recommended');
 console.log('    2) Another project folder\n');
 if (ask('  Where', '1') === '2') {
     // A different project → the agent's cwd won't be the package, so bake the absolute dist commands.
-    done(installSkills(projectSkillsRoot(agentKey, ask('  Project folder', process.cwd())), true));
+    const projectDir = ask('  Project folder', process.cwd());
+    done(installSkills(projectSkillsRoot(agentKey, projectDir), true), gateFor(agentKey, projectDir, true));
 }
 else {
     // Current folder: shipped `bun run src` only when developing in the package clone under Bun;
     // otherwise (incl. consuming the package as a dependency) bake the compiled dist commands.
-    done(installSkills(projectSkillsRoot(agentKey, process.cwd()), !isPackageDevCwd()));
+    const dist = !isPackageDevCwd();
+    done(installSkills(projectSkillsRoot(agentKey, process.cwd()), dist), gateFor(agentKey, process.cwd(), dist));
 }

package/dist/lib/skill-install.js

@@ -23,7 +23,7 @@
  * Mac dev box and a Linux VPS), which an absolute `process.execPath`/`<abs>/dist` baking did not.
  * (Requires `dist/` — build once with `bun run build` / `npm run build`.)
  */
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join, resolve, relative, dirname, sep } from 'node:path';
 import { PKG_ROOT, BASE_DIR, DATA_DIR } from "./paths.js";
 /** Compiled output dir — what a rewritten (dist) skill command points the runtime at. */
@@ -103,6 +103,50 @@ export function installSkills(root, dist = false) {
         return target;
     });
 }
+/** Agent key of Claude Code in AGENTS — the only agent with a PreToolUse hook to gate on. */
+export const CLAUDE_CODE = '1';
+/** Substring identifying our gate inside a settings.json hook command (used to update in place). */
+const GATE_ID = 'yt-summary-gate';
+/** How settings.json must invoke the gate — same portable form as the skill's engine commands. */
+export const gateCommand = (dist = false) => dist
+    ? `${isBun ? 'bun' : 'node'} "${toProjectRel(join(DIST_DIR, GATE_ID + '.js'))}"`
+    : `bun run src/${GATE_ID}.ts`;
+/**
+ * Put the gate into a settings object: a PreToolUse hook on AskUserQuestion. Merges — every other
+ * setting and hook is left as found, and our own entry is updated in place, so reinstalling (or
+ * moving the package, which changes the baked path) never duplicates or clobbers anything.
+ */
+export function withGateHook(settings, command) {
+    const preToolUse = ((settings.hooks ??= {}).PreToolUse ??= []);
+    const mine = preToolUse.find((e) => e.hooks?.some((h) => h.command?.includes(GATE_ID)));
+    const entry = { matcher: 'AskUserQuestion', hooks: [{ type: 'command', command }] };
+    if (mine)
+        Object.assign(mine, entry);
+    else
+        preToolUse.push(entry);
+    return settings;
+}
+/**
+ * Register the gate in a Claude Code project's `.claude/settings.json`.
+ *
+ * Returns the settings path written, or null when the file exists but isn't parseable JSON: a
+ * hand-edited config is not ours to rewrite, so the caller tells the user to add it by hand.
+ */
+export function installClaudeGate(projectDir, dist = false) {
+    const target = join(projectDir, '.claude', 'settings.json');
+    let settings = {};
+    if (existsSync(target)) {
+        try {
+            settings = JSON.parse(readFileSync(target, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, JSON.stringify(withGateHook(settings, gateCommand(dist)), null, 2) + '\n', 'utf8');
+    return target;
+}
 /** The agent's skills ROOT inside a project folder (the project you open in the agent). */
 export const projectSkillsRoot = (agentKey, projectDir) => join(projectDir, AGENTS[agentKey].sub);
 /** Suggested target for a "custom" (any other agent) install — the open `.agents` convention,

package/dist/lib/summary-gate.js

@@ -0,0 +1,40 @@
+/**
+ * Decision logic for the /yt summary gate — kept separate from the hook script so it is
+ * runtime-agnostic and unit-testable: pure functions over a payload and a transcript.
+ *
+ * See `src/yt-summary-gate.ts` for why the gate exists and how the hook wires it up.
+ */
+/**
+ * Is this the /yt rating popup? Identified by its fixed option labels, which SKILL.md pins in
+ * English across every `output_lang` (only the question text and descriptions are localised).
+ * Anything else — including /yt-search's keep/skip — is none of the gate's business.
+ */
+export function isRatingPopup(payload) {
+    const labels = (payload.tool_input?.questions ?? [])
+        .flatMap((q) => q.options ?? [])
+        .map((o) => (o.label ?? '').trim().toLowerCase());
+    return labels.includes('research') && labels.includes('weak');
+}
+/**
+ * Did the agent actually paste the summary? The summary carries the video's watch URL, so its id
+ * appears verbatim in the pasted text. Only the assistant's own text blocks count: the id also
+ * travels through tool calls and their results, and neither is shown to the user.
+ */
+export function summaryWasPasted(transcript, videoId) {
+    for (const line of transcript.split('\n')) {
+        if (!line.includes(videoId))
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (entry.message?.role !== 'assistant' || !Array.isArray(entry.message.content))
+            continue;
+        if (entry.message.content.some((b) => b.type === 'text' && b.text?.includes(videoId)))
+            return true;
+    }
+    return false;
+}

package/dist/yt-channel-pending.js

@@ -2,8 +2,11 @@
 /**
  * Usage: bun src/yt-channel-pending.ts @HANDLE
  *
- * For one channel: reads state.md pointers + last-updated date,
- * fetches the channel's videos in-process via lib/yt-api.ts (--since updated),
+ * For one channel: reads state.md pointers, fetches the channel's videos in-process via
+ * lib/yt-api.ts (--since a fixed lookback, NOT state.md's `updated` — that column is a
+ * write-timestamp, not the pointer video's publish date; using it as the fetch cutoff
+ * silently orphaned backlog videos on channels swept more than once per day, see
+ * CHANGELOG),
  * filters to videos NEWER than each type's pointer (or baseline if pointer null),
  * sorts ASC by publishedAt (process oldest first → state pointer advances monotonically),
  * outputs JSON array: [{videoId, title, publishedAt, type, is_baseline}].
@@ -28,7 +31,14 @@ if (!row) {
     console.error(`Channel ${handle} not found in state.md`);
     process.exit(1);
 }
-const since = row.updated ?? '2020-01-01';
+// `row.updated` is when state.md was last WRITTEN (stamped to today on every bump),
+// not when the pointer video was PUBLISHED — reusing it as the fetch cutoff shrinks the
+// window to "today" after the first bump of the day, so a second same-day sweep can
+// silently drop any not-yet-processed backlog between the pointer and today. A fixed
+// lookback avoids that: the pointer-cutoff logic below still does the real filtering,
+// this just has to be wide enough to always re-include the pointer video itself.
+const LOOKBACK_DAYS = 45;
+const since = new Date(Date.now() - LOOKBACK_DAYS * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
 let videos;
 try {
     videos = await fetchChannelVideos(handle, { since });

package/dist/yt-summary-gate.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * yt-summary-gate — PreToolUse gate for Claude Code: refuses the /yt rating popup until the
+ * video's summary has actually been pasted into the chat.
+ *
+ * Step B of the rating loop (paste `out.summary` verbatim, THEN ask) is the one instruction the
+ * agent can drop with no visible symptom: the popup still appears, the user still answers, and
+ * the rating is recorded against a summary nobody saw. Observed failure mode — the paste happens
+ * reliably while the sweep also returns a `skipped` list (there is other prose to write) and gets
+ * dropped in iterations that return none, where the turn can open straight with a tool call. A
+ * blind rating is worse than no rating: it teaches the title filter from noise.
+ *
+ * The engine cannot enforce this — `yt-sweep` only emits the summary, `yt-rating` only reads
+ * `pending.json`, and neither can see the conversation. The transcript is the one place the
+ * evidence exists and only the agent harness exposes it, so the check has to run as a hook.
+ *
+ * Reads the PreToolUse payload on stdin; exit 0 allows, exit 2 blocks and feeds stderr back to
+ * the agent. Anything unexpected — foreign tool, unreadable transcript, no pending video —
+ * allows: a gate that misfires on unrelated work would be worse than the bug it guards.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { isRatingPopup, summaryWasPasted } from "./lib/summary-gate.js";
+const ALLOW = 0;
+const BLOCK = 2;
+const allow = () => process.exit(ALLOW);
+let payload;
+try {
+    payload = JSON.parse(readFileSync(0, 'utf8'));
+}
+catch {
+    allow();
+}
+if (payload.tool_name !== 'AskUserQuestion' || !isRatingPopup(payload))
+    allow();
+// paths.ts derives the data dir from the cwd, which for a hook is the agent's, not ours — so the
+// import has to wait until we've moved there.
+if (payload.cwd && existsSync(payload.cwd))
+    process.chdir(payload.cwd);
+const { PENDING_FILE } = await import("./lib/paths.js");
+let pending = {};
+try {
+    pending = JSON.parse(readFileSync(PENDING_FILE, 'utf8'));
+}
+catch {
+    allow(); // no pending video (or unreadable) — nothing to gate on
+}
+if (!pending.videoId)
+    allow();
+const transcript = payload.transcript_path;
+if (!transcript || !existsSync(transcript))
+    allow();
+let seen = false;
+try {
+    seen = summaryWasPasted(readFileSync(transcript, 'utf8'), pending.videoId);
+}
+catch {
+    allow();
+}
+if (seen)
+    allow();
+process.stderr.write(`/yt step B not done: the summary for ${pending.videoId} ("${pending.title ?? '?'}") is not in your chat text.\n` +
+    `Paste out.summary verbatim as your reply first, then ask for the rating — the user rates what they can see.\n`);
+process.exit(BLOCK);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yt-briefing",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "A self-learning YouTube briefing engine: it sweeps the channels you follow, filters noise in two stages (title, then transcript), summarizes the rest in your language, and adapts to your ratings — one video at a time.",
   "type": "module",
   "bin": {