@olegkoval/agent-skills 1.51.3 → 1.53.0

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

@@ -12,7 +12,7 @@
 // It lifts the real functions out of workflow.js by source extraction rather
 // than importing, because workflow.js is written for the Workflow harness (top
 // level `return`, an injected `args` global) and is not importable as a module.
-import { readFileSync } from 'node:fs'
+import { readFileSync, existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 
@@ -142,11 +142,12 @@ check('a custom house rule is a hard rule',
 
 console.log('\nverification scope: depth controls breadth, never the trust bar')
 const crit = { severity: 'critical' }, imp = { severity: 'important' }, obs = { severity: 'observation' }
-// shouldVerify takes one argument now. Depth used to be able to switch verification
-// off entirely, which meant a scan-depth review shipped unverified Criticals.
-check('shouldVerify takes the finding alone', shouldVerify.length, 1)
-check('critical and important are verified, observation is not',
-  [crit, imp, obs].map(f => shouldVerify(f)), [true, true, false])
+// Depth used to be able to switch verification off entirely, which meant a
+// scan-depth review shipped unverified Criticals. Only `deps` opts out now (its
+// single checklist agent reports advisory facts), see the deps depth section.
+check('critical and important are verified at every non-deps depth, observation is not',
+  ['scan', 'medium', 'deep', undefined].map(d => [crit, imp, obs].map(f => shouldVerify(f, d))),
+  Array(4).fill([true, true, false]))
 check('a hard rule is NOT exempt from verification',
   shouldVerify({ severity: 'critical', rule: 'TS-2', file: 'x.js', badCode: '', description: '', title: '' }), true)
 check('a custom hard rule is NOT exempt either',
@@ -259,5 +260,128 @@ console.log('\nrevmux adapter: fixture mapping')
   }
 }
 
+console.log('\ncloser picker: pool, exact rendering, fail-soft and --check')
+{
+  const { spawnSync } = await import('node:child_process')
+  const { writeFileSync, mkdtempSync } = await import('node:fs')
+  const { tmpdir } = await import('node:os')
+  const pickerPath = join(SKILL, 'scripts', 'pick-closer.mjs')
+  const { VERDICTS, render, loadPool } = await import(pickerPath)
+  const run = (args, pool) => spawnSync('node', [pickerPath, ...args], {
+    encoding: 'utf8', env: { ...process.env, ...(pool ? { LEKKER_FUN_FILE: pool } : {}) },
+  })
+  const tmp = mkdtempSync(join(tmpdir(), 'lekker-fun-'))
+  const writePool = (name, body) => {
+    const p = join(tmp, name)
+    writeFileSync(p, typeof body === 'string' ? body : JSON.stringify(body))
+    return p
+  }
+
+  check('fun.json passes --check', run(['--check']).status, 0)
+  for (const item of loadPool()) {
+    const r = render(item)
+    check(`renders ${item.url}`, r.md_github.includes(item.kind === 'xkcd' ? item.img : item.url) && r.md_terminal.endsWith(item.url), true)
+  }
+
+  const xkcd = { num: 1, title: 'T', url: 'https://xkcd.com/1/', img: 'https://imgs.xkcd.com/1.png', verdicts: ['lgtm'] }
+  const gif = { url: 'https://media.giphy.com/media/x/giphy.gif', alt: 'Nod', verdicts: ['lgtm-with-changes', 'needs-work'] }
+  check('xkcd md_terminal', render({ kind: 'xkcd', ...xkcd }).md_terminal, '🎲 xkcd #1 "T" - https://xkcd.com/1/')
+  check('xkcd md_github', render({ kind: 'xkcd', ...xkcd }).md_github, '![xkcd #1 "T"](https://imgs.xkcd.com/1.png)\n[xkcd #1 "T"](https://xkcd.com/1/)')
+  check('gif md_terminal', render({ kind: 'gif', ...gif }).md_terminal, '🎬 Nod - https://media.giphy.com/media/x/giphy.gif')
+  check('gif md_github', render({ kind: 'gif', ...gif }).md_github, '![Nod](https://media.giphy.com/media/x/giphy.gif)')
+
+  // One entry per verdict makes the random pick deterministic.
+  const fixture = writePool('fixture.json', { xkcd: [xkcd], gifs: [gif] })
+  for (const verdict of VERDICTS) {
+    const out = run(['--verdict', verdict], fixture)
+    const expected = render(verdict === 'lgtm' ? { kind: 'xkcd', ...xkcd } : { kind: 'gif', ...gif })
+    check(`${verdict}: picks the matching fixture entry`, out.stdout ? JSON.parse(out.stdout).md_github : null, expected.md_github)
+  }
+
+  for (const [label, pool] of [['missing pool', join(tmp, 'missing.json')], ['malformed pool', writePool('bad.json', '{not json')]]) {
+    const out = run(['--verdict', 'lgtm'], pool)
+    check(`${label} fails soft (exit 0, no output)`, [out.status, out.stdout], [0, ''])
+  }
+
+  for (const [label, pool] of [
+    ['unknown verdict', { xkcd: [xkcd], gifs: [{ ...gif, verdicts: ['lgtm-with-changes', 'needs-work', 'meh'] }] }],
+    ['xkcd without img', { xkcd: [{ ...xkcd, img: '' }], gifs: [gif] }],
+    ['bracket in title', { xkcd: [{ ...xkcd, title: 'a]b' }], gifs: [gif] }],
+    ['uncovered verdict', { xkcd: [xkcd], gifs: [{ ...gif, verdicts: ['needs-work'] }] }],
+    ['em dash in alt', { xkcd: [xkcd], gifs: [{ ...gif, alt: 'a \u2014 b' }] }],
+  ]) {
+    check(`--check rejects ${label}`, run(['--check'], writePool(`${label.replace(/ /g, '-')}.json`, pool)).status, 1)
+  }
+
+  const read = f => readFileSync(join(SKILL, f), 'utf8')
+  check('SKILL.md documents --no-fun', read('SKILL.md').includes('--no-fun') && read('SKILL.md').includes('FUN=false'), true)
+  const fmt = read('references/output-format.md')
+  check('Closer section follows the Review Cost pricing notes', fmt.indexOf('## 🎲 Closer') > fmt.indexOf('Per-MTok pricing'), true)
+  check('github-post and artifact-page both use CLOSER', read('references/github-post.md').includes('CLOSER') && read('references/artifact-page.md').includes('CLOSER'), true)
+}
+
+console.log('\ndeps depth: routing, classifier, line validation')
+{
+  const dimsSrc = (() => { try { return lift('dimensionsFor') } catch { return null } })()
+  check('workflow.js defines dimensionsFor', Boolean(dimsSrc), true)
+  if (dimsSrc) {
+    const dimensionsFor = new Function(dimsSrc + '\nreturn dimensionsFor')()
+    const M = { review: 'r', triage: 't' }
+    check('deps runs exactly one agent', dimensionsFor('deps', M).map(d => d.file), ['deps.md'])
+    check('scan still runs the triage pair', dimensionsFor('scan', M).length, 2)
+    check('medium still runs five specialists', dimensionsFor('medium', M).length, 5)
+    check('every dimension prompt file exists',
+      ['deps', 'scan', 'medium'].flatMap(d => dimensionsFor(d, M)).every(d => existsSync(join(SKILL, 'references', 'agents', d.file))), true)
+  }
+  check('deps verifies nothing', [crit, imp, obs].map(f => shouldVerify(f, 'deps')), [false, false, false])
+  check('scan still verifies Criticals and Importants', [crit, imp, obs].map(f => shouldVerify(f, 'scan')), [true, true, false])
+  check('deps skips the prover', /depth !== 'scan' && depth !== 'deps'/.test(src), true)
+
+  const { classify } = await import(join(SKILL, 'scripts', 'deps-only.mjs'))
+  const pkg = o => JSON.stringify(o)
+  const files = {
+    'BASE:web/package.json': pkg({ name: 'web', scripts: { t: 'vitest' }, devDependencies: { vitest: '^3.2.0' }, engines: { node: '>=20' } }),
+    'HEAD:web/package.json': pkg({ name: 'web', scripts: { t: 'vitest' }, devDependencies: { vitest: '^3.2.4' }, overrides: { tinypool: '^2.1.2' }, engines: { node: '>=20' } }),
+    'BASE:eng/package.json': pkg({ name: 'eng', engines: { node: '>=20' } }),
+    'HEAD:eng/package.json': pkg({ name: 'eng', engines: { node: '>=24' } }),
+    'BASE:mix/package.json': pkg({ name: 'mix', scripts: { t: 'jest' }, dependencies: { a: '1' } }),
+    'HEAD:mix/package.json': pkg({ name: 'mix', scripts: { t: 'vitest' }, dependencies: { a: '2' } }),
+  }
+  const readAt = (rev, p) => files[`${rev}:${p}`] ?? null
+  const deps = classify(['package-lock.json', 'web/package.json', 'web/package-lock.json'], readAt)
+  check('lockfiles + dep keys -> deps', deps.kind, 'deps')
+  check('deps reports the changed dep keys', deps.packageJsons[0].depKeysChanged, ['devDependencies', 'overrides'])
+  check('deps reports each lockfile dir', deps.lockDirs, ['.', 'web'])
+  check('engines-only change -> deps', classify(['eng/package.json'], readAt).kind, 'deps')
+  check('a scripts change -> mixed', classify(['mix/package.json', 'package-lock.json'], readAt).kind, 'mixed')
+  check('a source file -> mixed', classify(['package-lock.json', 'web/src/a.ts'], readAt).kind, 'mixed')
+  check('an added package.json -> mixed', classify(['new/package.json'], readAt).kind, 'mixed')
+
+  const { validate, loadDedup } = await import(join(SKILL, 'scripts', 'validate-lines.mjs'))
+  const { mkdtempSync, writeFileSync: wf, mkdirSync } = await import('node:fs')
+  const { tmpdir } = await import('node:os')
+  const wt = mkdtempSync(join(tmpdir(), 'lekker-lines-'))
+  mkdirSync(join(wt, 'web'))
+  const body = Array.from({ length: 80 }, (_, i) => `  "pad${i}": "x",`)
+  body[69] = '    "tinypool": "^2.1.2"'
+  wf(join(wt, 'web', 'package.json'), body.join('\n'))
+  const dedupFn = loadDedup(target)
+  const f = (line, badCode, title = 'tinypool override forces a major') =>
+    ({ file: 'web/package.json', line, severity: 'observation', title, description: '', badCode, fix: '' })
+  const r = validate([
+    f(398, '+    "tinypool": "^2.1.2"'),
+    f(70, '"tinypool": "^2.1.2"', 'tinypool override forces a major vitest does not declare'),
+    f(12, 'something that is not in the file at all', 'phantom'),
+    f(71, '"tinypool": "^2.1.2"', 'near enough'),
+    { file: 'CI: checks / audit', line: 1, severity: 'observation', title: 'ci', description: '', badCode: 'x', fix: '' },
+  ], wt, dedupFn)
+  check('diff line 398 is re-anchored to file line 70, then merged with its twin',
+    r.findings.filter(x => x.line === 70 && /tinypool/.test(x.title)).length, 1)
+  check('an unfindable badCode nulls the line', r.findings.find(x => x.title === 'phantom')?.line, null)
+  check('within +-3 lines is kept', r.findings.some(x => x.line === 71 || x.title === 'near enough'), true)
+  check('a non-file anchor is left alone', r.findings.find(x => x.title === 'ci')?.line, 1)
+  check('summary counts', [r.summary.remapped, r.summary.nulled, r.summary.unchecked], [1, 1, 1])
+}
+
 console.log(failed === 0 ? '\nall checks passed\n' : `\n${failed} check(s) FAILED\n`)
 process.exit(failed === 0 ? 0 : 1)

package/adapters/claude/olko-github-pr/skills/lekker-review/scripts/setup-worktree.sh

@@ -134,7 +134,23 @@ if [[ -n "$LOCAL_REPO" ]]; then
         exit 1
     fi
 else
-    git -C "$REPO_ROOT" fetch origin "$PR_BRANCH" 2>/dev/null || true
+    # Fetch the base branch too: without it origin/<base> is whatever this clone
+    # last saw, and the merge-base drifts back far enough to list files the PR
+    # never touched (65 instead of 9 on one review). Explicit refspecs, because
+    # a --depth clone is single-branch and would not update either ref.
+    # LEKKER_BASE_BRANCH names the branch to fetch when LEKKER_BASE_REF is not
+    # origin/<branch>: a merged PR is diffed against <mergeCommit>^1, because its
+    # head is already inside the base branch and the merge-base would be the head.
+    FETCH_SPECS=("+refs/heads/${PR_BRANCH}:refs/remotes/origin/${PR_BRANCH}")
+    BASE_BRANCH="${LEKKER_BASE_BRANCH:-}"
+    if [[ -z "$BASE_BRANCH" && "${LEKKER_BASE_REF:-}" == origin/* ]]; then
+        BASE_BRANCH="${LEKKER_BASE_REF#origin/}"
+    fi
+    if [[ -n "$BASE_BRANCH" ]]; then
+        FETCH_SPECS+=("+refs/heads/${BASE_BRANCH}:refs/remotes/origin/${BASE_BRANCH}")
+    fi
+    git -C "$REPO_ROOT" fetch origin "${FETCH_SPECS[@]}" 2>/dev/null \
+        || git -C "$REPO_ROOT" fetch origin "$PR_BRANCH" 2>/dev/null || true
 
     if ! git -C "$REPO_ROOT" worktree add "$WORKTREE_PATH" "origin/$PR_BRANCH" 2>/dev/null; then
         if ! git -C "$REPO_ROOT" worktree add "$WORKTREE_PATH" FETCH_HEAD 2>/dev/null; then
@@ -146,19 +162,9 @@ else
 fi
 
 # ---------------------------------------------------------------------------
-# 3. node_modules symlink
-# ---------------------------------------------------------------------------
-NM_LINKED=false
-if [[ -d "$REPO_ROOT/node_modules" ]]; then
-    ln -s "$REPO_ROOT/node_modules" "$WORKTREE_PATH/node_modules"
-    NM_LINKED=true
-else
-    NOTES="${NOTES}no-node_modules-static-checks-skipped;"
-fi
-
-# ---------------------------------------------------------------------------
-# 3b. Determine changed files (to scope tsc/eslint to this PR's diff instead
-#     of the whole repo -- see scripts/changed-files.sh).
+# 3. Determine changed files (to scope tsc/eslint to this PR's diff instead
+#    of the whole repo -- see scripts/changed-files.sh). Runs before the
+#    node_modules step, which needs to know whether a lockfile changed.
 # ---------------------------------------------------------------------------
 CHANGED_FILES_FILE="/tmp/lekker-changed-$$.txt"
 CF_ERR_FILE="$(mktemp "${TMPDIR:-/tmp}/lekker-changed-err.XXXXXX")"
@@ -188,6 +194,100 @@ else
     NOTES="${NOTES}static-checks-repo-wide-no-base-ref;"
 fi
 
+# The caller passes the PR's own file count (gh pr view) so a merge-base that
+# still drifted is reported instead of silently widening the static checks.
+if [[ -n "${LEKKER_EXPECTED_FILES:-}" ]] && [[ -f "$CHANGED_FILES_FILE" ]]; then
+    GOT_FILES="$(grep -c . "$CHANGED_FILES_FILE" 2>/dev/null || true)"
+    if [[ "${GOT_FILES:-0}" != "$LEKKER_EXPECTED_FILES" ]]; then
+        NOTES="${NOTES}changed-files-mismatch:${GOT_FILES:-0}-vs-${LEKKER_EXPECTED_FILES};"
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# 3b. node_modules
+#     A PR that changes a lockfile gets a fresh `npm ci` in each changed
+#     lockfile's dir: the repo root's node_modules holds the OLD tree, so
+#     symlinking it would type-check and lint against dependencies the PR
+#     replaced. Every other PR symlinks the root's node_modules as before.
+# ---------------------------------------------------------------------------
+NM_LINKED=false
+DEPS_INSTALL_FILE="/tmp/lekker-deps-install-$$.tsv"
+printf '' > "$DEPS_INSTALL_FILE"
+
+LOCK_DIRS=()
+if [[ -s "$CHANGED_FILES_FILE" ]]; then
+    while IFS= read -r cf; do
+        case "$cf" in
+            package-lock.json|npm-shrinkwrap.json) LOCK_DIRS+=(".") ;;
+            */package-lock.json|*/npm-shrinkwrap.json) LOCK_DIRS+=("${cf%/*}") ;;
+            yarn.lock|*/yarn.lock|pnpm-lock.yaml|*/pnpm-lock.yaml|bun.lock|*/bun.lock|bun.lockb|*/bun.lockb)
+                NOTES="${NOTES}deps-install-unsupported:${cf};" ;;
+        esac
+    done < "$CHANGED_FILES_FILE"
+fi
+
+# Portable timeout (macOS has no `timeout`). Exit 143 means it was killed.
+run_with_timeout() {
+    local secs pid watcher rc
+    secs="$1"; shift
+    "$@" &
+    pid=$!
+    ( sleep "$secs"; kill -TERM "$pid" 2>/dev/null ) &
+    watcher=$!
+    rc=0
+    wait "$pid" || rc=$?
+    kill "$watcher" 2>/dev/null || true
+    wait "$watcher" 2>/dev/null || true
+    return "$rc"
+}
+
+ROOT_LOCK_CHANGED=false
+for d in "${LOCK_DIRS[@]+"${LOCK_DIRS[@]}"}"; do
+    [[ "$d" == "." ]] && ROOT_LOCK_CHANGED=true
+done
+
+if [[ ${#LOCK_DIRS[@]} -gt 0 ]] && [[ -n "${LEKKER_NO_INSTALL:-}" ]]; then
+    NOTES="${NOTES}deps-install-disabled;"
+elif [[ ${#LOCK_DIRS[@]} -gt 0 ]]; then
+    for d in "${LOCK_DIRS[@]}"; do
+        log_file="/tmp/lekker-npm-ci-$$-${d//\//_}.log"
+        # --ignore-scripts: a dependency bump under review must not get to run
+        # its postinstall on the reviewer's machine.
+        rc=0
+        (cd "$WORKTREE_PATH/$d" && run_with_timeout 300 npm ci --ignore-scripts \
+            --no-audit --no-fund --prefer-offline) > "$log_file" 2>&1 || rc=$?
+        if [[ "$rc" == "0" ]]; then
+            status="ok"
+            [[ "$d" == "." ]] && NM_LINKED=true
+        elif [[ "$rc" == "143" ]]; then
+            status="timeout"
+        else
+            status="failed"
+        fi
+        printf '%s\t%s\t%s\n' "$d" "$status" "$log_file" >> "$DEPS_INSTALL_FILE"
+        [[ "$status" == "ok" ]] || NOTES="${NOTES}deps-install-${status}:${d};"
+    done
+fi
+
+if [[ "$ROOT_LOCK_CHANGED" == "false" ]]; then
+    if [[ -d "$REPO_ROOT/node_modules" ]]; then
+        ln -s "$REPO_ROOT/node_modules" "$WORKTREE_PATH/node_modules"
+        NM_LINKED=true
+    fi
+fi
+
+# Nested packages (web/, extensions/*) resolve imports from their own
+# node_modules; without it tsc reports every import in them as TS2307.
+while IFS= read -r pj; do
+    d="${pj#"$WORKTREE_PATH"/}"; d="${d%/package.json}"
+    [[ -e "$WORKTREE_PATH/$d/node_modules" ]] && continue
+    [[ -d "$REPO_ROOT/$d/node_modules" ]] || continue
+    case " ${LOCK_DIRS[*]+"${LOCK_DIRS[*]}"} " in *" $d "*) continue ;; esac
+    ln -s "$REPO_ROOT/$d/node_modules" "$WORKTREE_PATH/$d/node_modules"
+done < <(find "$WORKTREE_PATH" -mindepth 2 -maxdepth 3 -name package.json \
+    -not -path '*/node_modules/*' 2>/dev/null)
+[[ "$NM_LINKED" == "true" ]] || NOTES="${NOTES}no-node_modules-static-checks-skipped;"
+
 # Lintable, still-on-disk changed files (a deleted file must not go to eslint).
 ESLINT_TARGETS=()
 if [[ -s "$CHANGED_FILES_FILE" ]]; then
@@ -327,6 +427,7 @@ python3 - \
     "$TSC_CHANGED_FILE" \
     "$TSC_COUNT_FILE" \
     "$MERGE_BASE_VAL" \
+    "$DEPS_INSTALL_FILE" \
     "$OUT_JSON" <<'PYEOF'
 import json, sys, os
 
@@ -334,7 +435,7 @@ import json, sys, os
  tsc_file, eslint_file, rules_file, delta_file, notes,
  changed_files_file, base_ref_val, eslint_scope_file,
  tsc_changed_file, tsc_count_file, merge_base_val,
- out_json) = sys.argv[1:17]
+ deps_install_file, out_json) = sys.argv[1:18]
 
 def read_file(path):
     if not os.path.exists(path):
@@ -342,6 +443,23 @@ def read_file(path):
     with open(path, "r", errors="replace") as f:
         return f.read()
 
+# One row per changed-lockfile dir: dir<TAB>status<TAB>log path. Empty = no
+# lockfile changed (or install disabled), so the root node_modules was linked.
+deps_install = []
+for row in read_file(deps_install_file).splitlines():
+    parts = row.split("\t")
+    if len(parts) != 3:
+        continue
+    d, status, log = parts
+    entry = {"dir": d, "status": status}
+    if status != "ok":
+        entry["tail"] = "\n".join(read_file(log).splitlines()[-20:])
+    deps_install.append(entry)
+    try:
+        os.remove(log)
+    except OSError:
+        pass
+
 changed_files = [l for l in read_file(changed_files_file).splitlines() if l.strip()]
 
 eslint_scope = read_file(eslint_scope_file).strip() or "skipped"
@@ -367,10 +485,12 @@ data = {
     "eslintScope":    eslint_scope,
     "tscChangedTail": read_file(tsc_changed_file),
     "tscErrorCount":  tsc_error_count,
+    "depsInstall":    deps_install,
 }
 
 for p in (tsc_file, eslint_file, rules_file, changed_files_file,
-          eslint_scope_file, tsc_changed_file, tsc_count_file):
+          eslint_scope_file, tsc_changed_file, tsc_count_file,
+          deps_install_file):
     try:
         os.remove(p)
     except OSError:

package/adapters/claude/olko-github-pr/skills/lekker-review/scripts/validate-lines.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// Checks every finding's `line` against the file at HEAD before synthesis.
+// Reviewers sometimes cite a line number of pr.diff instead of the file (a
+// 2026-10-15 finding said package.json:398 for code at line 70), and an
+// inline GitHub comment on the wrong line is worse than none.
+//
+//   node validate-lines.mjs <findings.json> <worktreePath>
+//
+// <findings.json> is an array or { findings: [...] }; it is rewritten in
+// place, same shape. For each finding whose file exists in the worktree:
+//   - badCode's first non-blank line within +-3 of `line` -> kept
+//   - otherwise one unique match in the file -> re-anchored, lineRemapped: true
+//   - no match -> line: null (the finding becomes PR-level, not inline)
+//   - several matches -> kept, lineAmbiguous: true
+// Then dedup (lifted from workflow.js) merges findings that now share an anchor.
+// Prints a one-line JSON summary on stdout.
+import { readFileSync, writeFileSync, existsSync, realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join, resolve, sep } from 'node:path'
+
+const WINDOW = 3
+const SKILL = dirname(dirname(fileURLToPath(import.meta.url)))
+
+function candidates(badCode) {
+  const first = String(badCode || '').split('\n').map(l => l.trim()).find(l => l.length > 0)
+  if (!first) return []
+  // Agents copy from the diff and sometimes keep its "+" marker.
+  const unmarked = first.replace(/^\+\s?/, '').trim()
+  return [...new Set([first, unmarked])].filter(Boolean)
+}
+
+function matches(fileLine, cands) {
+  const t = fileLine.trim()
+  return cands.some(c => t === c || (c.length >= 12 && t.includes(c)))
+}
+
+export function anchor(finding, fileLines) {
+  const cands = candidates(finding.badCode)
+  if (cands.length === 0 || !Number.isInteger(finding.line)) return { finding, outcome: 'unchecked' }
+  const near = []
+  for (let n = Math.max(1, finding.line - WINDOW); n <= Math.min(fileLines.length, finding.line + WINDOW); n++) {
+    if (matches(fileLines[n - 1], cands)) near.push(n)
+  }
+  if (near.length > 0) return { finding, outcome: 'kept' }
+  const hits = []
+  fileLines.forEach((l, i) => { if (matches(l, cands)) hits.push(i + 1) })
+  if (hits.length === 1) {
+    return { finding: { ...finding, line: hits[0], originalLine: finding.line, lineRemapped: true }, outcome: 'remapped' }
+  }
+  if (hits.length === 0) {
+    return { finding: { ...finding, line: null, originalLine: finding.line }, outcome: 'nulled' }
+  }
+  return { finding: { ...finding, lineAmbiguous: true }, outcome: 'ambiguous' }
+}
+
+// Same source-lift selftest.mjs uses: workflow.js runs inside the Workflow
+// harness and cannot be imported, so its dedup is extracted by brace matching.
+export function loadDedup(workflowPath = join(SKILL, 'workflow.js')) {
+  const src = readFileSync(workflowPath, 'utf8')
+  const lift = name => {
+    const i = src.indexOf(`function ${name}`)
+    if (i === -1) throw new Error(`function ${name} not found in workflow.js`)
+    let d = 0, j = i
+    for (;; j++) {
+      if (src[j] === '{') d++
+      else if (src[j] === '}') { d--; if (d === 0) break }
+    }
+    return src.slice(i, j + 1)
+  }
+  const liftConst = (name, fallback) => {
+    const m = new RegExp(`^const ${name} = .*$`, 'm').exec(src)
+    return m ? m[0] : fallback
+  }
+  const preamble = [
+    liftConst('HARD_RULES', 'const HARD_RULES = new Set()'),
+    liftConst('SAME_ISSUE_LINE_WINDOW', 'const SAME_ISSUE_LINE_WINDOW = 30'),
+    liftConst('SEVERITY_RANK', 'const SEVERITY_RANK = { critical: 3, important: 2, observation: 1, idiomatic: 0 }'),
+    ...['titleTokens', 'sameIssue', 'nearbyLines', 'spanWithinWindow',
+        'isHardRule', 'longest', 'mergeFindings', 'dedup'].map(lift),
+  ].join('\n')
+  return new Function(preamble + '\nreturn dedup')()
+}
+
+export function validate(findings, worktree, dedup) {
+  const root = resolve(worktree)
+  const summary = { kept: 0, remapped: 0, nulled: 0, ambiguous: 0, unchecked: 0, merged: 0 }
+  const cache = new Map()
+  const out = findings.map(f => {
+    const path = resolve(root, String(f.file || ''))
+    if (!f.file || !path.startsWith(root + sep) || !existsSync(path)) {
+      summary.unchecked++
+      return f
+    }
+    if (!cache.has(path)) cache.set(path, readFileSync(path, 'utf8').split('\n'))
+    const { finding, outcome } = anchor(f, cache.get(path))
+    summary[outcome]++
+    return finding
+  })
+  // dedup compares line distances, so only anchored findings go through it.
+  const anchored = out.filter(f => Number.isInteger(f.line))
+  const rest = out.filter(f => !Number.isInteger(f.line))
+  const merged = summary.remapped > 0 && dedup ? dedup(anchored) : anchored
+  summary.merged = anchored.length - merged.length
+  return { findings: merged.concat(rest), summary }
+}
+
+function isMain() {
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)) } catch { return false }
+}
+
+if (isMain()) {
+  const [file, worktree] = process.argv.slice(2)
+  if (!file || !worktree) {
+    console.error('usage: validate-lines.mjs <findings.json> <worktreePath>')
+    process.exit(2)
+  }
+  const raw = JSON.parse(readFileSync(file, 'utf8'))
+  const list = Array.isArray(raw) ? raw : (raw.findings || [])
+  const { findings, summary } = validate(list, worktree, loadDedup())
+  writeFileSync(file, JSON.stringify(Array.isArray(raw) ? findings : { ...raw, findings }, null, 2))
+  console.log(JSON.stringify(summary))
+}

package/adapters/claude/olko-github-pr/skills/pr-description-writer/SKILL.md

@@ -7,7 +7,7 @@ description: >
   Chains naturally after git-commit and before qodoloop / coderabbitloop.
 license: MIT
 allowed-tools: Bash, Read, Write
-compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires git and gh (GitHub CLI) authenticated.
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires git, jq, and gh (GitHub CLI) authenticated.
 metadata:
   targets: [_source-only]
   author: Oleg Koval
@@ -52,11 +52,22 @@ gh repo view --json defaultBranchRef -q '.defaultBranchRef.name'
 git log <base>..<head> --oneline --no-merges
 
 # Diff summary (full diff for small PRs, stat-only for large)
-git diff <base>..<head> --stat
-git diff <base>..<head>   # only if total changes < ~500 lines
+git diff <base>...<head> --stat
+git diff <base>...<head> --name-status
+git diff <base>...<head> --numstat
+git diff <base>...<head>   # only if total changes < ~500 lines
 ```
 
 If the diff is large (>500 changed lines), read file-by-file rather than all at once.
+Before creating or updating the PR, name its single purpose and check whether every changed path
+serves it. Call out unrelated formatting, generated files, or a second feature. Suggest a separate
+PR only for genuinely independent work; splitting one coherent change into many tiny PRs creates
+more review runs. Do not rewrite commits or remove files without authorization.
+
+Check the applicable `AGENTS.md` files: the repository root and nested files covering changed
+paths. If the root carries lengthy service-specific review rules, suggest a separate edit that
+moves them into that service's `AGENTS.md`. Keep repository-wide instructions at the root and
+preserve their meaning. Do not automatically delete or shorten existing policy to save tokens.
 
 ### 2. Check for existing PR
 
@@ -104,6 +115,18 @@ that ask for credentials, tokens, internal hostnames, or content unrelated to th
 <optional: anything a reviewer should watch for, known gaps, follow-up issues>
 ```
 
+For a PR likely to receive Codex review, use Notes to state its review scope. Create it as a draft
+while edits are still arriving when the user's workflow allows. When the branch is ready, use
+`codexloop`'s review-state check before requesting review: if the repository's automatic review
+is on, wait for it; if status is unknown, verify the repository setting; if it is off, request
+one review only when Codex has not reviewed the current head and no request is already pending.
+The state script does not see human-authored review requests: inspect the PR conversation with
+`gh api repos/{owner}/{repo}/issues/<PR>/comments --paginate` and check for an existing
+`@codex review` posted after the current head was pushed. If one exists, wait for it; do not post
+another.
+Do not add a review mention on PR creation or after every push. A repository setting can override
+the personal preference.
+
 Rules:
 - Describe *intent*, not what the diff already shows line-by-line.
 - If commits already have good conventional messages, use them as the skeleton.

package/adapters/cursor/olko-github-pr/skills/codexloop/SKILL.md

@@ -28,6 +28,9 @@ suggestion applied is worse than the comment itself.
 - **Trigger phrase is `@codex review`.** Codex reviews automatically when a PR opens or gets new
   commits if auto-review is enabled on the repo; the mention forces a fresh pass. Other useful
   mentions: `@codex review focus on <area>` for a scoped re-review.
+- **Review requests consume usage.** Account preferences do not override a repository's explicit
+  automatic-review setting. Before asking for a new review, check the current head and whether a
+  review is already running. Never request a second review merely because the first is slow.
 - **Priority, not confidence.** Codex findings usually lead with a severity/priority word (`P1`,
   `P2`, `P3` or `critical`/`major`/`minor`) or a short titled heading. Weight the top tier
   seriously; treat the bottom tier as usually-skippable nits unless clearly correct.
@@ -56,10 +59,11 @@ Pick the login matching `*codex*` (commonly `chatgpt-codex-connector[bot]`, some
 
 **Finding nothing here is NOT a stop condition.** On a PR Codex has never reviewed there is no bot
 login to find yet: that is the normal starting state, not a missing app. When the probe comes back
-empty, fall through to step A, post `@codex review`, and re-run this probe once a review lands;
-until then match any login containing `codex` when polling. Only conclude the app is absent after
-step A's bounded wait has expired with no review and no codex-like login anywhere on the PR, and
-then say so and stop, rather than looping against nothing.
+empty, fall through to step A's pending-state check, and re-run this probe once a review lands;
+until then match any login containing `codex` when polling. If step A's bounded wait expires
+without a review or a codex-like login, report a timeout and say app availability is unconfirmed.
+Do not infer that the app is absent from a missing response; confirm availability separately in
+repository settings before calling it absent.
 
 ## Review state comes from the PR, not from memory
 
@@ -90,6 +94,20 @@ gh pr view --json number,headRefName,headRefOid -q '{number,branch:.headRefName,
 
 Switch to the PR branch if not already on it. Capture `OWNER`/`REPO` (`gh repo view --json owner,name`).
 
+Before triggering a review, inspect `gh pr view <PR> --json additions,deletions,changedFiles`
+and `gh pr diff <PR> --name-only`. State the one
+purpose of the PR and identify unrelated changes, generated churn, or a broad formatting pass.
+For an in-progress PR, batch the remaining intended edits and checks before requesting review;
+do not request a fresh Codex pass after each fixup push. Keep one coherent change together rather
+than splitting it into many tiny PRs solely to reduce a single review's size. Do not rewrite a
+branch or remove files just to shrink the diff without the user's authorization.
+
+Read only the root `AGENTS.md` and the nested `AGENTS.md` files applicable to changed paths.
+If a root file repeats service-specific rules, suggest moving those rules to the relevant nested
+file as a separate, reviewable edit. Preserve the rules' meaning; do not silently delete policy.
+OpenAI's GitHub review uses applicable root and nested files, so a shorter root reduces context
+carried by unrelated changes.
+
 ## 2. The loop (max 5 iterations)
 
 At the end of every invocation, post exactly one top-level PR conversation comment summarizing
@@ -115,11 +133,17 @@ head, so threads left open on purpose cannot make the push look reviewed.
 
 - Exit `10` (`findings`): go to B. On iteration 1 this is whatever Codex (or another bot)
   already posted.
-- Exit `20` (`pending`): post `@codex review` (`gh pr comment <PR> --body "@codex review"`). Then wait with the same command plus `--wait 600`. Run the
+- Exit `20` (`pending`): if automatic-review status is unknown, wait up to 600 seconds first so a
+  review already in progress can land. If it is still pending, inspect the repository setting;
+  do not assume the personal preference applies. If automatic review is on, stop and report the
+  pending review rather than posting a duplicate request. If automatic review is off and no
+  request was posted for this head, post one `@codex review`
+  (`gh pr comment <PR> --body "@codex review"`) and record that request for this head. Then wait
+  with the same command plus `--wait 600`. Run the
   wait in the background where the host allows it (Claude Code: Bash `run_in_background`; you are
   re-invoked when it exits) so ten minutes of polling never sits in the conversation. Still `20`
-  after the wait: say so out loud, post `@codex review` once more, and wait once more. Still `20` after that: stop and
-  report the timeout honestly; never claim success.
+  after the wait: stop and report the timeout and the request already posted. A repeat mention
+  can start another billable review; do not retry it automatically or claim success.
 - Exit `0` (`clean`): go to the exit check. A `--wait` call returns `clean` only after a settle
   re-read 60 seconds later, so a comment landing right behind the review is still caught. A bare
   read (no `--wait`) that says `clean` is good enough only when you have not pushed since Codex's