@olegkoval/agent-skills 1.60.0 → 1.62.0

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/sa.ts

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+/*
+ * Shorts Animator: a script and a look in, an animated short out.
+ *
+ *   SA new <dir> [--look oil] [--format 9:16]   a project: short.json, scenes.js
+ *   SA looks                                     the looks, moods and voices, one line each
+ *   SA check <dir>                               finds what a render would get wrong, in a second, no browser
+ *   SA voice <dir>                               narrates every line (cached) and prints the timing
+ *   SA frames <dir>                              one painted frame per shot -> frames/sheet.jpg
+ *   SA still <dir> <shot> [at]                   one shot, full size -> frames/shot-NN.jpg
+ *   SA render <dir>                              the MP4: voice, score, every drawing -> <title>.mp4
+ *   SA set <dir> key=value...                    change short.json from the command line (JSON values)
+ *   SA doctor                                    checks the machine and renders a 3-second test
+ *
+ * SA = node <skill-dir>/scripts/sa.ts
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { check, report } from "./domain/check.ts";
+import { resolveLook, pageState } from "./domain/look.ts";
+import { parseAssignment, setPath } from "./domain/patch.ts";
+import { isJson, isMap, parseShort } from "./domain/schema.ts";
+import { timeline } from "./domain/timeline.ts";
+import type { Json, JsonMap, Result, Short, Take, Timeline } from "./domain/types.ts";
+import { fail, ok } from "./domain/types.ts";
+import type { Page } from "./edge/chrome.ts";
+import { doctor } from "./edge/doctor.ts";
+import { encoder, jpeg, mkdir, readJson, stillSheet, videoSheet, writeJson } from "./edge/media.ts";
+import { pageErrors, paintPage } from "./edge/page.ts";
+import { kitNames, probeScenes } from "./edge/probe.ts";
+import { MOODS, soundtrack } from "./edge/sound.ts";
+import { cachedTakes, narrate } from "./edge/voice.ts";
+
+const LOOKS = path.join(import.meta.dirname, "looks");
+const VOICES = "bm_george (warm British man, default), am_michael, am_adam, af_heart, af_nova, bf_emma, bf_isabella";
+const NEW_SCENES = `// One function per shot. k is the drawing kit (references/kit.md).
+window.SCENES = {
+  opening: (k) => {
+    k.sky({ stops: ["#f3ecd2", "#e9dfb7"] });
+    k.ridge({ y: 0.52, amp: 0.02, freq: 4, color: "#4f7a3a", shape: "bush" });
+    k.ground({ y: 0.52, color: "#8fbf3a", far: "#c3cf5a", stripes: 14 });
+    k.person({ x: 0.5, y: 0.7, h: 0.22, pose: "walk", facing: "front" });
+  },
+};
+`;
+
+const unwrap = <T>(r: Result<T>): T => {
+  if (!r.ok) throw new Error(r.errors.join("\n  "));
+  return r.value;
+};
+
+const slug = (s: string): string =>
+  s.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "short";
+
+const twosName = (n: number): string => (n === 1 ? "ones" : n === 2 ? "twos" : `${n}s`);
+
+const lookFiles = (): readonly string[] => fs.readdirSync(LOOKS).filter((f) => f.endsWith(".json")).toSorted();
+
+const namedLook = (name: string): Result<JsonMap> => {
+  const f = path.join(LOOKS, `${name}.json`);
+  if (!fs.existsSync(f)) return fail(`no look "${name}" (SA looks lists them)`);
+  const v = readJson(f);
+  return isMap(v) ? ok(v) : fail(`looks/${name}.json is not an object`);
+};
+
+const shortFile = (dir: string): string => path.join(dir, "short.json");
+
+function rawShort(dir: string): Json {
+  const f = shortFile(dir);
+  if (!fs.existsSync(f)) throw new Error(`no short.json in ${dir} (start one with: SA new ${dir})`);
+  const v = readJson(f);
+  if (!isJson(v)) throw new Error("short.json is not JSON");
+  return v;
+}
+
+const load = (dir: string): Short => unwrap(parseShort(rawShort(dir)));
+
+type Project = { readonly dir: string; readonly s: Short; readonly takes: readonly Take[]; readonly tl: Timeline };
+
+async function project(dir: string, quiet = false): Promise<Project> {
+  const s = load(dir);
+  const takes = await narrate(dir, s, quiet);
+  return { dir, s, takes, tl: unwrap(timeline(s, takes)) };
+}
+
+async function withPage<T>({ dir, s, tl }: Project, use: (pg: Page) => Promise<T>): Promise<T> {
+  const state = pageState(s, tl, unwrap(resolveLook(s.look, namedLook)));
+  const pg = await paintPage(dir, state, tl.W, tl.H);
+  try {
+    const out = await use(pg);
+    const errs = pageErrors(pg);
+    if (errs.length) console.log("⚠ the page said:\n  " + errs.join("\n  "));
+    return out;
+  } finally {
+    pg.close();
+  }
+}
+
+const frameName = (i: number): string => `s${String(i).padStart(3, "0")}.jpg`;
+
+/* ------------------------------------------------------------------ commands */
+
+type Args = { readonly dir: string | undefined; readonly rest: readonly string[] };
+type Command = (a: Args) => Promise<number>;
+
+const need = (dir: string | undefined, usage: string): string => {
+  if (!dir) throw new Error(usage);
+  return dir;
+};
+
+const looks: Command = async () => {
+  lookFiles().forEach((f) => {
+    const l = readJson(path.join(LOOKS, f));
+    console.log(`${f.replace(".json", "").padEnd(12)} ${isMap(l) && typeof l.about === "string" ? l.about : ""}`);
+  });
+  console.log(`\nmusic moods: ${MOODS.join(", ")} (or "none", or a path to their own track)`);
+  console.log(`voices: ${VOICES}`);
+  return 0;
+};
+
+const create: Command = async ({ dir, rest }) => {
+  const d = need(dir, "SA new <dir>");
+  mkdir(d, "assets");
+  const opt = (k: string, dflt: string): string => {
+    const i = rest.indexOf(`--${k}`);
+    return (i >= 0 ? rest[i + 1] : undefined) ?? dflt;
+  };
+  if (!fs.existsSync(shortFile(d))) {
+    writeJson(shortFile(d), {
+      title: "Untitled short", brief: "", format: opt("format", "9:16"), look: opt("look", "oil"),
+      voice: { id: "bm_george", speed: 0.92 }, music: { mood: "tender" }, captions: { style: "box" },
+      lines: [{ say: "Every story starts somewhere.", scene: "opening", move: "push" }],
+    });
+  }
+  if (!fs.existsSync(path.join(d, "scenes.js"))) fs.writeFileSync(path.join(d, "scenes.js"), NEW_SCENES);
+  console.log(`✓ ${d}\n  short.json  the script, look, voice, music\n  scenes.js   the drawings\n  assets/     anything they gave you`);
+  return 0;
+};
+
+const set: Command = async ({ dir, rest }) => {
+  const d = need(dir, "SA set <dir> key=value...");
+  const next = rest.map((a) => unwrap(parseAssignment(a))).reduce<Json>((doc, a) => setPath(doc, a.path, a.value), rawShort(d));
+  // Placeholder takes are enough to catch what only the timeline knows (an unknown format).
+  const s = unwrap(parseShort(next));
+  unwrap(timeline(s, s.lines.map(() => ({ file: null, dur: 1 }))));
+  writeJson(shortFile(d), next);
+  console.log("✓ short.json updated");
+  return 0;
+};
+
+const lookKeys = (): readonly string[] =>
+  [...new Set(lookFiles().flatMap((f) => {
+    const l = readJson(path.join(LOOKS, f));
+    return isMap(l) ? Object.keys(l) : [];
+  }))];
+
+const checkCmd: Command = async ({ dir }) => {
+  const d = need(dir, "SA check <dir>");
+  const s = load(d);
+  const tl = unwrap(timeline(s, cachedTakes(d, s)));
+  const findings = check({ short: s, timeline: tl, probes: probeScenes(d, tl), kit: kitNames(), lookKeys: lookKeys() });
+  console.log(report(findings));
+  return findings.some((f) => f.level === "error") ? 1 : 0;
+};
+
+const voice: Command = async ({ dir }) => {
+  const { tl } = await project(need(dir, "SA voice <dir>"));
+  tl.beats.forEach((b, i) => console.log(`${String(i + 1).padStart(2)}  ${b.start.toFixed(2).padStart(6)}s  ${b.dur.toFixed(2)}s  ${b.scene.padEnd(16)} ${b.say}`));
+  console.log(`total ${tl.duration.toFixed(1)}s, ${tl.beats.length} shots`);
+  return 0;
+};
+
+const frames: Command = async ({ dir }) => {
+  const p = await project(need(dir, "SA frames <dir>"), true);
+  const fdir = mkdir(p.dir, "frames");
+  fs.readdirSync(fdir).filter((f) => /^s\d+\.jpg$/.test(f)).forEach((f) => fs.rmSync(path.join(fdir, f)));
+  await withPage(p, (pg) =>
+    p.tl.beats.reduce<Promise<void>>(async (prev, _b, i) => {
+      await prev;
+      fs.writeFileSync(path.join(fdir, frameName(i)), jpeg(await pg.evaluate(`window.still(${i}, 0.6)`)));
+    }, Promise.resolve()),
+  );
+  const sheet = path.join(fdir, "sheet.jpg");
+  stillSheet(p.tl, path.join(fdir, "s%03d.jpg"), sheet);
+  console.log(`✓ ${sheet}  (${p.tl.beats.length} shots, ${p.tl.duration.toFixed(1)}s)`);
+  return 0;
+};
+
+const still: Command = async ({ dir, rest }) => {
+  const p = await project(need(dir, "SA still <dir> <shot> [at]"), true);
+  const i = Math.max(0, parseInt(rest[0] ?? "1", 10) - 1);
+  const at = parseFloat(rest[1] ?? "0.6");
+  if (i >= p.tl.beats.length) throw new Error(`shot ${i + 1}? there are ${p.tl.beats.length}`);
+  const f = path.join(mkdir(p.dir, "frames"), `shot-${String(i + 1).padStart(2, "0")}.jpg`);
+  await withPage(p, async (pg) => fs.writeFileSync(f, jpeg(await pg.evaluate(`window.still(${i}, ${at})`))));
+  console.log(`✓ ${f}`);
+  return 0;
+};
+
+/** Next free vN: one past the highest, so deleting an old render never reuses its number. */
+const nextVersion = (rdir: string): number =>
+  1 + Math.max(0, ...fs.readdirSync(rdir).flatMap((f) => /^v(\d+)\.mp4$/.exec(f)?.[1] ?? []).map(Number));
+
+async function paintAll(pg: Page, write: (b: Buffer) => Promise<void>, drawings: number): Promise<void> {
+  const step = async (d: number): Promise<void> => {
+    if (d >= drawings) return;
+    await write(jpeg(await pg.evaluate(`window.drawing(${d})`)));
+    if (d % 60 === 0) process.stdout.write(`\r· painting ${d}/${drawings} drawings`);
+    return step(d + 1);
+  };
+  await step(0);
+  process.stdout.write(`\r· painted ${drawings} drawings          \n`);
+}
+
+const render: Command = async ({ dir }) => {
+  const t0 = Date.now();
+  const p = await project(need(dir, "SA render <dir>"));
+  const { tl, s } = p;
+  console.log(`· ${tl.beats.length} shots, ${tl.duration.toFixed(1)}s at ${tl.fps} fps, drawn on ${twosName(tl.twos)}`);
+  const audio = soundtrack(p.dir, s, tl, p.takes);
+  const rdir = mkdir(p.dir, "renders");
+  const n = nextVersion(rdir);
+  const outV = path.join(rdir, `v${n}.mp4`);
+  const enc = encoder(tl, audio, outV);
+  await withPage(p, (pg) => paintAll(pg, enc.write, Math.ceil((tl.duration * tl.fps) / tl.twos)));
+  const code = await enc.done();
+  if (code !== 0) throw new Error(`ffmpeg exited ${code} while encoding`);
+  const final = path.join(p.dir, `${slug(s.title)}.mp4`);
+  fs.copyFileSync(outV, final);
+  fs.copyFileSync(shortFile(p.dir), path.join(rdir, `v${n}.json`));
+  const sheet = path.join(mkdir(p.dir, "qa"), "sheet.jpg");
+  videoSheet(tl, final, sheet);
+  console.log(`✓ ${final}\n  ${tl.duration.toFixed(1)}s · ${tl.W}×${tl.H} · ${((Date.now() - t0) / 1000).toFixed(0)}s to make · check: ${sheet}`);
+  return 0;
+};
+
+const COMMANDS: Readonly<Record<string, Command>> = {
+  looks, new: create, set, check: checkCmd, voice, frames, still, render,
+  doctor: async () => doctor(import.meta.filename),
+};
+
+const usage = (): string =>
+  fs.readFileSync(import.meta.filename, "utf8").split("\n").slice(2, 16).join("\n").replace(/^ \* ?/gm, "");
+
+// stripTypeScriptTypes is stable in practice but flagged experimental; that one notice is noise to a user.
+process.removeAllListeners("warning");
+process.on("warning", (w) => {
+  if (!(w.name === "ExperimentalWarning" && /stripTypeScriptTypes/.test(w.message))) console.error(`${w.name}: ${w.message}`);
+});
+
+const [cmd = "", dirArg, ...rest] = process.argv.slice(2);
+const command = COMMANDS[cmd];
+if (!command) {
+  console.log(usage());
+  process.exit(cmd ? 1 : 0);
+}
+command({ dir: dirArg ? path.resolve(dirArg) : undefined, rest })
+  .then((code) => process.exit(code))
+  .catch((e: unknown) => {
+    console.error("✗ " + (e instanceof Error ? e.message : String(e)));
+    process.exit(1);
+  });

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/test/domain.test.ts

@@ -0,0 +1,107 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { captionChunks, chunks, words } from "../domain/captions.ts";
+import { check, report, type Facts, type Probe } from "../domain/check.ts";
+import { resolveLook } from "../domain/look.ts";
+import { parseAssignment, setPath } from "../domain/patch.ts";
+import { parseShort } from "../domain/schema.ts";
+import { timeline } from "../domain/timeline.ts";
+import type { Json, Result, Short, Take, Timeline } from "../domain/types.ts";
+import { fail, ok } from "../domain/types.ts";
+
+const value = <T>(r: Result<T>): T => {
+  if (!r.ok) throw new Error(r.errors.join("; "));
+  return r.value;
+};
+
+const RAW = {
+  title: "test", voice: "none", music: "none",
+  lines: [
+    { say: "A bright and open morning, out on the hills.", scene: "day", move: "push" },
+    { say: "Night comes down over the city.", scene: "night" },
+  ],
+};
+const short = (patch: object = {}): Short => value(parseShort({ ...RAW, ...patch }));
+const silent = (s: Short): readonly Take[] => s.lines.map(() => ({ file: null, dur: 2 }));
+const tl = (s: Short): Timeline => value(timeline(s, silent(s)));
+
+test("words drops the writer's emphasis and pause marks", () => {
+  assert.deepEqual(words("a *bright* | morning"), ["a", "bright", "morning"]);
+});
+
+test("chunks are balanced, not greedy", () => {
+  assert.deepEqual(chunks("one two three four five six seven", 5).map((c) => c.split(" ").length), [4, 3]);
+  assert.deepEqual(chunks("short line", 5), ["short line"]);
+});
+
+test("a slash in the caption forces the break", () => {
+  assert.deepEqual(captionChunks({ say: "Everyone, every pose.", caption: "Everyone, / every pose.", shots: [] }, 5), ["Everyone,", "every pose."]);
+});
+
+test("parseShort fills defaults and rejects a script with no lines", () => {
+  const s = short();
+  assert.equal(s.format, "9:16");
+  assert.equal(s.fps, 24);
+  assert.equal(s.voice.kind, "none");
+  assert.equal(parseShort({ title: "x" }).ok, false);
+  assert.equal(parseShort([]).ok, false);
+});
+
+test("timeline lays beats end to end and rejects an unknown format", () => {
+  const t = tl(short());
+  assert.equal(t.beats.length, 2);
+  assert.equal(t.W, 1080);
+  const [a, b] = t.beats;
+  assert.ok(a && b && Math.abs(a.start + a.dur - b.start) < 1e-9);
+  assert.ok(t.duration >= b.start + b.dur);
+  const bad = timeline(short({ format: "3:2" }), silent(short()));
+  assert.equal(bad.ok, false);
+});
+
+test("parseAssignment reads JSON values and falls back to text", () => {
+  assert.deepEqual(value(parseAssignment("lines.0.hold=0.8")), { path: ["lines", "0", "hold"], value: 0.8 });
+  assert.deepEqual(value(parseAssignment("look=watercolor")), { path: ["look"], value: "watercolor" });
+  assert.equal(parseAssignment("nokey").ok, false);
+  assert.equal(parseAssignment("a..b=1").ok, false);
+});
+
+test("setPath returns a new document and leaves the old one alone", () => {
+  const doc: Json = { lines: [{ say: "hi" }], music: { mood: "tender" } };
+  const before = JSON.stringify(doc);
+  const next = setPath(setPath(doc, ["lines", "0", "hold"], 1), ["music", "mood"], "night");
+  assert.equal(JSON.stringify(doc), before);
+  assert.deepEqual(next, { lines: [{ say: "hi", hold: 1 }], music: { mood: "night" } });
+});
+
+test("resolveLook merges a named base under the overrides", () => {
+  const named = (n: string): Result<{ readonly [k: string]: Json }> => (n === "oil" ? ok({ grain: 0.3, edge: 1 }) : fail(`no look "${n}"`));
+  const look = value(resolveLook({ base: "oil", grain: 0.5 }, named));
+  assert.equal(look.grain, 0.5);
+  assert.equal(look.edge, 1);
+  assert.equal(resolveLook("nope", named).ok, false);
+});
+
+const facts = (probes: readonly Probe[], s = short()): Facts => ({ short: s, timeline: tl(s), probes, kit: ["sky", "person"], lookKeys: ["grain"] });
+
+test("check flags missing scenes, unknown kit calls and throwing scenes as errors", () => {
+  const found = check(facts([{ scene: "day", calls: [{ fn: "skyy", opts: {} }] }, { scene: "other", calls: [], error: "boom" }]));
+  const errors = found.filter((f) => f.level === "error").map((f) => f.msg);
+  assert.ok(errors.some((m) => m.includes('no scene "night"')));
+  assert.ok(errors.some((m) => m.includes("k.skyy is not in the kit")));
+  assert.ok(errors.some((m) => m.includes("throws: boom")));
+});
+
+test("check warns when a person stands in the caption band, unless captions are off", () => {
+  const probes: readonly Probe[] = [
+    { scene: "day", calls: [{ fn: "person", opts: { y: 0.82, h: 0.28 } }] },
+    { scene: "night", calls: [{ fn: "person", opts: { y: 0.5, h: 0.2 } }] },
+  ];
+  const band = (s: Short) => check(facts(probes, s)).filter((f) => f.msg.includes("caption line"));
+  assert.deepEqual(band(short()).map((f) => f.where), ['scene "day"']);
+  assert.deepEqual(band(short({ captions: { style: "none" } })), []);
+});
+
+test("report is one line per finding, or clean", () => {
+  assert.equal(report([]), "check: clean");
+  assert.equal(report([{ level: "error", where: "x", msg: "y" }]), "ERROR x: y");
+});

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "lib": ["es2023"],
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "types": ["node"],
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true
+  },
+  "include": ["*.ts", "domain", "edge", "audio", "test"]
+}

package/adapters/claude/olko-creative/skills/shorts-animator/scripts/tts.py

@@ -0,0 +1,20 @@
+"""The narrator: Kokoro-82M on this computer, every line of a short in one go.
+
+  python tts.py <model.onnx> <voices.bin> <voice> <speed> < jobs.json
+
+jobs.json is [[text, out.wav], ...]. Loads the model once, writes one WAV per line,
+prints one line per file. Apache-2.0 model, no account, nothing leaves the machine.
+"""
+import json
+import sys
+
+import soundfile as sf
+from kokoro_onnx import Kokoro
+
+model, voices, voice, speed = sys.argv[1], sys.argv[2], sys.argv[3], float(sys.argv[4])
+lang = {"a": "en-us", "b": "en-gb", "e": "es", "f": "fr-fr", "h": "hi", "i": "it", "j": "ja", "p": "pt-br", "z": "cmn"}.get(voice[0], "en-us")
+k = Kokoro(model, voices)
+for text, out in json.load(sys.stdin):
+    samples, rate = k.create(text, voice=voice, speed=speed, lang=lang)
+    sf.write(out, samples, rate)
+    print(out, flush=True)

package/adapters/claude/olko-github-pr/skills/lekker-review/SKILL.md

@@ -353,6 +353,33 @@ treat as a full review and leave PREV_SHA unset. Also grep the same file for
 - Step 3.5 reuses that exact URL or local path so the artifact stays a living
 page for this PR.
 
+**Convergence state (every PR, first review included):** the review file
+records only the last head sha, so finding status lives in
+`scripts/finding-state.mjs` (one JSON file per PR under
+`~/.local/state/lekker-review/findings/`). In `pr` mode, on a re-review, first
+fetch the PR's review threads into `<scratchpad>/threads.json` as
+`{ "prAuthor": <login>, "threads": [{ path, line, body, isResolved, isOutdated,
+replies: [{ author, body }] }] }` (`gh api graphql` over `reviewThreads`; `body`
+is the first comment, `replies` the later ones). Then run
+`node "${CLAUDE_PLUGIN_ROOT}/skills/lekker-review/scripts/finding-state.mjs" begin --repo <REPO_SLUG> --target <TARGET_SLUG> --run <RUN_ID> [--threads <scratchpad>/threads.json]`.
+`RUN_ID` is one id per review attempt, saved to `<scratchpad>/finding-run-id`
+and reused when that attempt is retried, so a retry does not count as a new
+cycle. In Codex, replace the quoted script path with the absolute path to
+`scripts/finding-state.mjs` beside the selected `SKILL.md`, as for run-log. Pass
+its `cycle`, `suppressed` and `recurringClasses` to the workflow. A
+finding is `fixed` when its thread is outdated, `intentional` when the author
+replied "by design" and nothing changed, `rejected` when the author dismissed it
+or the thread was resolved with no code change. The workflow never re-raises a
+`suppressed` (rejected or intentional) finding. From `cycle` 4 the workflow
+returns `verdict: "rethink"` with the recurring finding classes and runs no
+agents: skip Steps 2 to 4, render the verdict as `RETHINK THE APPROACH: this PR
+has been reviewed N times; the same classes keep coming back: <classes>`, and
+suggest the author and reviewer agree the approach before another round.
+Run `finding-state.mjs record --run <RUN_ID> --repo ... --target ... --findings <findings.json>`
+before the review is published or the artifact is updated, so a stop after
+publishing cannot lose what was raised. `--run` files the findings under this
+attempt's cycle even when another review of the PR started in the meantime.
+
 **Open the run log** once mode, depth and engine are settled (see
 `references/traces.md` for where every trace of a run lives):
 
@@ -688,6 +715,9 @@ args: {
   worktreePath: <null for scan, else from worktree.json>,
   promptDir:   "${SKILL_ROOT}/references/agents",
   prevSha:     <null unless re-review>,
+  cycle,             // finding-state.mjs begin output; omit when unknown
+  suppressed,        // rejected/intentional findings never to re-raise
+  recurringClasses,  // shown in the rethink verdict
   testRunner:  <worktree.json testRunner, null for scan>
 }
 ```

package/adapters/claude/olko-github-pr/skills/lekker-review/references/context-gathering.md

@@ -142,6 +142,9 @@ Collect into `EXISTING_REVIEWS`. Purpose:
 - **Deduplication**: if an existing review already raised a finding at a
   specific `file:line`, skip that finding in your output and note
   `(already raised by <reviewer>)` internally in your deduplication pass.
+- **Answered findings**: file:line dedup is not enough across re-reviews. A finding the
+  author rejected or called intentional is carried in `suppressed` from
+  `scripts/finding-state.mjs` (SKILL.md, Convergence state) and is never re-raised.
 - **Design decisions**: if the author replied to a review comment explaining
   an intentional choice, that context informs whether a pattern is a bug or
   a deliberate trade-off.

package/adapters/claude/olko-github-pr/skills/lekker-review/scripts/finding-state.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+// Per-PR finding state for lekker-review, so re-reviews converge.
+//
+// A re-review used to know only the last head sha and dedupe by file:line, so a
+// finding the author had already rejected came back every round. This keeps one
+// small JSON file per PR next to the run ledger (${LEKKER_STATE_DIR:-
+// ~/.local/state/lekker-review}/findings/) holding each finding's status and the
+// number of review cycles.
+//
+// Statuses: open | fixed | rejected | intentional. A finding is
+//   fixed       when GitHub marks its thread outdated (the line changed)
+//   intentional when the author replied "by design" and the code did not change
+//   rejected    when the author replied with another dismissal, or the thread
+//               was resolved without a code change and the PR author is known
+//
+// Usage:
+//   node finding-state.mjs begin  --repo <slug> --target <pr-N> [--threads <threads.json>]
+//       Folds thread outcomes into the stored statuses, counts the cycle, and
+//       prints {cycle, rethink, suppressed, recurringClasses} for workflow.js.
+//   node finding-state.mjs record --repo <slug> --target <pr-N> --findings <findings.json>
+//       Stores this run's findings as open (an already-known finding keeps its status).
+//   node finding-state.mjs show   --repo <slug> --target <pr-N>
+//
+// threads.json: { prAuthor, threads: [{ path, line, title?, body, isResolved, isOutdated,
+// replies: [{ author, body }] }] }, where `body` is lekker's comment and only
+// replies by `prAuthor` count as the author's answer. A bare array is accepted
+// when the author is unknown; it can then only yield fixed (outdated) threads.
+// When title is absent, the first nonempty comment line supplies the title.
+
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const RETHINK_CYCLE = 4;
+const INTENT = /\b(intentional(ly)?|by design|on purpose|deliberate(ly)?|as designed|expected behaviou?r)\b/i;
+const DISMISS = /\b(won'?t fix|wontfix|not a (bug|problem|concern)|false positive|disagree|n\/a|not applicable|out of scope|ignor(e|ing)|nit)\b/i;
+
+export function titleTokens(title) {
+  return (String(title || '').toLowerCase().match(/[a-z0-9]+/g) || []).filter((w) => w.length > 2);
+}
+
+export function sameIssue(a, b) {
+  const normalize = (title) => String(title || '').trim().replace(/\s+/g, ' ').toLowerCase();
+  const title = normalize(a.title);
+  return title !== '' && title === normalize(b.title);
+}
+
+export function sameFinding(a, b) {
+  // Status reuse requires the same anchor and title; word overlap is only a
+  // class signal, never proof that two findings identify the same issue.
+  return Boolean(a.file) && a.file === b.file && a.line === b.line && sameIssue(a, b);
+}
+
+// Group key for "the same kind of finding came back again".
+export function findingClass(f) {
+  return f.bugClass || titleTokens(f.title).slice(0, 4).sort().join('-') || 'unclassified';
+}
+
+const NEGATOR = /\b(not|no|never|nor|isn'?t|aren'?t|wasn'?t|don'?t|doesn'?t|won'?t|cannot)\b/i;
+
+// Check only the three words before each keyword in its clause for negation.
+function mentions(pattern, text) {
+  return [...text.matchAll(new RegExp(pattern.source, 'gi'))]
+    .some((match) => {
+      const before = text.slice(0, match.index).split(/[.!?;:,\n-]/).pop();
+      return !NEGATOR.test(before.trim().split(/\s+/).slice(-3).join(' '));
+    });
+}
+
+export function classifyThread(thread, prAuthor) {
+  const authorReplies = (thread.replies || []).filter((r) => r.author && r.author === prAuthor);
+  const text = authorReplies.map((r) => r.body).join('\n');
+  if (thread.isOutdated) return 'fixed';
+  if (mentions(INTENT, text)) return 'intentional';
+  if (mentions(DISMISS, text)) return 'rejected';
+  if (thread.isResolved && prAuthor) return 'rejected';
+  return 'open';
+}
+
+export function applyThreads(findings, threads, prAuthor) {
+  return findings.map((f) => {
+    const thread = threads.find((t) => {
+      const title = t.title?.trim() || String(t.body || '').split(/\r?\n/).find((line) => line.trim())
+        ?.trim().replace(/^#{1,6}\s+/, '').replace(/^(\*\*|__)(.*?)\1[.:]?$/, '$2');
+      return sameFinding(f, { file: t.path, line: t.line, title });
+    });
+    if (!thread) return f;
+    const status = classifyThread(thread, prAuthor);
+    return f.status === status ? f : { ...f, status };
+  });
+}
+
+export function mergeFindings(prior, found, cycle) {
+  const added = found
+    .filter((f) => !prior.some((p) => sameFinding(p, f)))
+    .map((f) => ({ file: f.file, line: f.line, title: f.title, class: findingClass(f), status: 'open', cycles: [cycle] }));
+  const seen = prior.map((p) => (found.some((f) => sameFinding(p, f)) && !p.cycles.includes(cycle)
+    ? { ...p, cycles: [...p.cycles, cycle] }
+    : p));
+  return seen.concat(added);
+}
+
+export function recurringClasses(findings) {
+  const byClass = findings.reduce((acc, f) => {
+    const cycles = new Set([...(acc[f.class] || []), ...f.cycles]);
+    return { ...acc, [f.class]: [...cycles] };
+  }, {});
+  return Object.entries(byClass)
+    .filter(([, cycles]) => cycles.length >= 2)
+    .map(([cls, cycles]) => ({ class: cls, cycles: cycles.length }))
+    .sort((a, b) => b.cycles - a.cycles);
+}
+
+export function suppressedFindings(findings) {
+  return findings
+    .filter((f) => f.status === 'rejected' || f.status === 'intentional')
+    .map(({ file, line, title, status }) => ({ file, line, title, status }));
+}
+
+// A run id makes begin idempotent: a retry of the same run reuses its cycle instead of inflating the count.
+export function begin(state, threads, prAuthor, run = null) {
+  const findings = applyThreads(state.findings, threads, prAuthor);
+  const known = run === null ? undefined : state.runs?.[run];
+  const cycle = known ?? state.cycle + 1;
+  const runs = run === null || known !== undefined ? state.runs : { ...state.runs, [run]: cycle };
+  return {
+    state: { ...state, cycle: Math.max(state.cycle, cycle), findings, ...(runs && { runs }) },
+    summary: {
+      cycle,
+      rethink: cycle >= RETHINK_CYCLE,
+      suppressed: suppressedFindings(findings),
+      recurringClasses: recurringClasses(findings),
+    },
+  };
+}
+
+const STATE_DIR = process.env.LEKKER_STATE_DIR || join(homedir(), '.local', 'state', 'lekker-review');
+// Hash the tuple so punctuation, case and repo/target boundaries stay distinct.
+const statePath = (repo, target) => join(STATE_DIR, 'findings',
+  `${createHash('sha256').update(JSON.stringify([repo, target])).digest('hex')}.json`);
+
+function load(path) {
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { cycle: 0, findings: [] };
+    throw error;
+  }
+  const state = JSON.parse(raw);
+  if (!state || typeof state !== 'object' || Array.isArray(state)
+    || !Number.isSafeInteger(state.cycle) || state.cycle < 0 || !Array.isArray(state.findings)) {
+    throw new Error(`Invalid finding state: ${path}`);
+  }
+  if (state.runs !== undefined && (!state.runs || typeof state.runs !== 'object' || Array.isArray(state.runs)
+    || !Object.values(state.runs).every((c) => Number.isSafeInteger(c) && c >= 1))) {
+    throw new Error(`Invalid finding state runs: ${path}`);
+  }
+  return state;
+}
+
+function save(path, state) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, JSON.stringify(state, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    renameSync(temporary, path);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+function main(argv) {
+  const flag = (name) => { const i = argv.indexOf('--' + name); return i === -1 ? null : argv[i + 1]; };
+  const repo = flag('repo');
+  const target = flag('target');
+  if (!repo || !target) { console.log(JSON.stringify({ error: '--repo and --target are required' })); process.exit(2); }
+  const path = statePath(repo, target);
+  const state = load(path);
+  const cmd = argv[0];
+  if (cmd === 'begin') {
+    const raw = flag('threads') ? JSON.parse(readFileSync(flag('threads'), 'utf8')) : [];
+    const threads = Array.isArray(raw) ? raw : raw.threads || [];
+    const prAuthor = Array.isArray(raw) ? null : raw.prAuthor || null;
+    const next = begin(state, threads, prAuthor, flag('run') ?? null);
+    save(path, next.state);
+    console.log(JSON.stringify(next.summary));
+  } else if (cmd === 'record') {
+    const raw = JSON.parse(readFileSync(flag('findings'), 'utf8'));
+    const found = Array.isArray(raw) ? raw : raw.findings || [];
+    const run = flag('run') ?? null;
+    // A late record for an earlier run keeps that run's cycle; the current cycle stays as it was.
+    const cycle = run === null ? Math.max(state.cycle, 1) : state.runs?.[run];
+    if (cycle === undefined) { console.log(JSON.stringify({ error: `unknown --run ${run}; call begin --run first` })); process.exit(2); }
+    save(path, { ...state, cycle: Math.max(state.cycle, 1), findings: mergeFindings(state.findings, found, cycle) });
+    console.log(JSON.stringify({ recorded: found.length, cycle }));
+  } else if (cmd === 'show') {
+    console.log(JSON.stringify(state, null, 2));
+  } else {
+    console.log(JSON.stringify({ error: 'usage: begin|record|show' }));
+    process.exit(2);
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(2));