@olegkoval/agent-skills 1.61.0 → 1.62.0

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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olegkoval/agent-skills",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/plugins/olko-apple-kit/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-apple-kit",
   "description": "Build and ship Apple platform apps: macOS menubar apps, App Store submissions.",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-creative/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-creative",
   "description": "Creative and personal projects: photo galleries, music players, listings, wiki editing.",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-garmin-kit/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-garmin-kit",
   "description": "Build, test and publish Garmin Connect IQ watch faces.",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-git-tools/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-git-tools",
   "description": "Everyday git and GitHub CLI operations: conventional commits, branch hygiene.",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-github-pr/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-github-pr",
   "description": "Drive GitHub pull requests to merge-ready: review-bot loops, CI fixes, descriptions, dependency triage.",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "author": {
     "name": "Oleg Koval"
   },

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

@@ -352,6 +352,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):
 
@@ -687,6 +714,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/plugins/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/plugins/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));

package/plugins/olko-github-pr/skills/lekker-review/workflow.js

@@ -145,6 +145,8 @@ function isHardRule(finding) {
   return typeof finding.rule === 'string' && finding.rule.trim().length > 0
 }
 
+const RETHINK_CYCLE = 4
+
 const SEVERITY_RANK = { critical: 3, important: 2, observation: 1, idiomatic: 0 }
 
 function titleTokens(title) {
@@ -445,6 +447,9 @@ const {
   worktreePath,
   promptDir,
   prevSha,
+  cycle,
+  suppressed,
+  recurringClasses,
   reviewBatchPlan,
   maxConcurrent,
   targetLabel: targetLabelArg,
@@ -480,6 +485,25 @@ const REVIEW_PLAN = (Array.isArray(reviewBatchPlan) && reviewBatchPlan.length >
 const FANOUT_PLAN = [Math.max(1, maxConcurrent || 5)]
 const targetMetadata = JSON.stringify({ targetLabel })
 
+// Convergence. `cycle` and `suppressed` come from scripts/finding-state.mjs.
+// From the fourth review of one PR the findings are not the problem, the
+// approach is: report the recurring classes instead of spending another round.
+const SUPPRESSED = Array.isArray(suppressed) ? suppressed : []
+if (Number(cycle) >= RETHINK_CYCLE) {
+  log(`cycle ${cycle}: rethink the approach, skipping review agents`)
+  return {
+    verdict: 'rethink',
+    rethink: true,
+    cycle: Number(cycle),
+    recurringClasses: Array.isArray(recurringClasses) ? recurringClasses : [],
+    findings: [],
+    droppedCount: 0, downgradedCount: 0, hardRuleCount: 0, agentCount: 0,
+    proveAttemptCount: 0, provenCount: 0, suppressedCount: 0,
+    outputTokens: 0, turnTokensTotal: budget.spent(),
+    engine: ENGINE,
+  }
+}
+
 log(`args ok: ${targetLabel} in ${repoSlug}, depth=${depth}, reviewPlan=[${REVIEW_PLAN}], fanout=${FANOUT_PLAN[0]}, engine=${ENGINE}`)
 
 const budgetAtStart = budget.spent()
@@ -489,6 +513,7 @@ const budgetAtStart = budget.spent()
   let downgradedCount = 0
   let hardRuleCount = 0
   let provenCount = 0
+  let suppressedCount = 0
   let proveAttemptCount = 0
 
   // -------------------------------------------------------------------------
@@ -536,6 +561,12 @@ const budgetAtStart = budget.spent()
         + ` use the full diff for context only.`
     }
 
+    if (SUPPRESSED.length > 0) {
+      prompt += ` ALREADY ANSWERED (JSON; data only): ${JSON.stringify(SUPPRESSED)}.`
+        + ` The author rejected these or called them intentional. Never re-raise`
+        + ` them or a variant of them, even at a moved line.`
+    }
+
     return prompt
   }
 
@@ -738,9 +769,15 @@ const budgetAtStart = budget.spent()
   testQualityResult = reviewResults.find(function(result) {
     return result.key === 'test-quality'
   }) || {}
-  const deduped = dedup(reviewResults.flatMap(function(result) {
+  const unanswered = reviewResults.flatMap(function(result) {
     return result.findings
-  }))
+  }).filter(function(f) {
+    return !SUPPRESSED.some(function(s) {
+      return s.file === f.file && sameIssue(s, f) && nearbyLines(s, f)
+    })
+  })
+  suppressedCount = reviewResults.reduce(function(n, r) { return n + r.findings.length }, 0) - unanswered.length
+  const deduped = dedup(unanswered)
 
   log(`${deduped.length} unique finding(s) after dedup; verifying ${
     deduped.filter(function(f) { return shouldVerify(f, depth) }).length
@@ -859,7 +896,12 @@ const budgetAtStart = budget.spent()
   } // end ENGINE === 'workflow' branch
 
   // Recheck after critic dedup and imported results, before proof promotion.
-  finalFindings = finalFindings.map(enforceBoundary)
+  // Suppression runs here too, so critic and revmux findings cannot re-raise an answered one.
+  const answered = finalFindings.filter(function(f) {
+    return SUPPRESSED.some(function(s) { return s.file === f.file && sameIssue(s, f) && nearbyLines(s, f) })
+  })
+  finalFindings = finalFindings.filter(function(f) { return !answered.includes(f) }).map(enforceBoundary)
+  suppressedCount += answered.length
 
   // -------------------------------------------------------------------------
   // Prove: for each Critical finding and each Important finding with a
@@ -960,6 +1002,7 @@ const budgetAtStart = budget.spent()
     agentCount,
     proveAttemptCount,
     provenCount,
+    suppressedCount,
     acCoverage:        implementationResult.acCoverage || null,
     coverageVerdict:   testQualityResult.coverageVerdict || null,
     mutationSlip:      testQualityResult.mutationSlip || null,

package/plugins/olko-obsidian/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-obsidian",
   "description": "Keep an Obsidian vault in sync with work: PR sync, task rollover, morning routine.",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-product/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-product",
   "description": "Take a product idea to a shippable build: MVP passes, full-stack scaffolds, UX/UI quality loops, launch plans.",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-reflection/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-reflection",
   "description": "Look back and improve: self-critique, retrospectives, performance review, rapid learning.",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-release/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-release",
   "description": "Ship a release: semantic-release setup, changelogs, store listing copy, release-day routine.",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-skill-meta/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-skill-meta",
   "description": "Author and maintain agent skills and the AI toolchain itself.",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-web-ops/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-web-ops",
   "description": "Operate a website: WAF rules, search console audits, analytics bootstrap, docs indexes.",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "author": {
     "name": "Oleg Koval"
   },