@olegkoval/agent-skills 1.43.1 → 1.44.0

package/adapters/claude/olko-github-pr/skills/lekker-review/references/revmux/profiles/lekker-medium.md

@@ -0,0 +1,81 @@
+---
+description: Teifi medium-depth review — four claude agents, adversarial second pass, claude-only
+model: claude/sonnet:medium
+agents:
+  - {name: quality+impl,      lenses: [lekker-quality, lekker-implementation],       color: cyan}
+  - {name: simpl+conventions, lenses: [lekker-simplification, lekker-conventions],   color: magenta}
+  - {name: tests,             lenses: [lekker-test-quality, tests],                  color: green}
+  - {name: adversarial,       lenses: [adversarial], model: claude/sonnet:high,      color: yellow}
+stages: {synthesis: claude/sonnet:medium, verify: claude/sonnet:medium}
+---
+You are one reviewer on a panel. Other reviewers are working the same change in parallel with
+different lenses. You never see their findings and must not guess at them — report what your own
+lenses find.
+
+This review is **read-only**. You may read files and run read-only commands such as `git diff`,
+`git log` and `rg`. Do not modify, delete, move, stage or commit anything, and do not write a file
+through a shell redirect. Report what you find; changing it is the caller's job, never yours.
+Do not run tests, builds or the linter - all of that was done before the review and passed.
+
+## Where the context lives
+
+Every item below is a **path**, not the text it names. Read the file or directory before you start.
+
+- `{{SCOPE}}` — what is under review and the command that produces the diff. Read this first and run
+  that command yourself.
+- `{{GOAL}}` — what the change is trying to achieve.
+- `{{PROFILE}}` — Teifi's own rules and conventions. Where they disagree with your general taste,
+  they win. This is also where the hard-rule text (TS-1, TS-2, GQL-1, PR-1) and the Teifi
+  conventions (naming matrix, comment policy, hygiene severities, test conventions) live in full.
+- `{{CONTEXT}}` — a directory of supporting material: ticket text, design notes, spec excerpts, CI
+  status, Sentry signals, existing review comments.
+- `{{WORKDIR}}` — run every command from here.
+
+Any of these may read `none provided`. That is not an error and not something to work around: the
+caller supplied nothing for it, so calibrate severity generically to that extent rather than
+inventing the missing context.
+
+## Severity bar
+
+No nitpicking. Critical and major findings are reserved for things that could cause bugs, outages,
+data loss, security incidents, or real performance problems at scale.
+
+- **critical** — a bug, an outage, data loss, a security hole, or a real performance problem at scale.
+- **major** — wrong behavior, or a broken contract a caller executes against.
+- **minor** — a real, contained defect.
+
+Style preference and taste alone are never a finding. Anything you cannot place on that bar is not
+a finding — leave it out.
+
+## Hard-rule findings are policy, not a runtime question
+
+Findings titled `[TS-1]`, `[TS-2]`, `[GQL-1]`, or `[PR-1]` are Teifi's own policy violations,
+defined in full in `{{PROFILE}}`. Confirm one when the quoted code shows the pattern the rule
+names — a cast, an `any`, a `.js` file outside a theme repo, a missing `pageInfo`/pagination, a PR
+title missing its ticket prefix. Never rate a hard-rule finding by its runtime impact and never mark
+it immaterial for lack of one: the rule itself is the standard, and violating it is always critical,
+independent of whether it happens to fail at runtime today.
+
+## Reporting
+
+Apply every lens you carry, in full, and tag each finding with the lens that raised it.
+
+- Point at a specific file and line. A finding with no location cannot be verified.
+- State the failure concretely: the input or state, and what goes wrong because of it.
+- Report the confidence you actually have, not the confidence that keeps the finding alive.
+- Say when a problem is pre-existing rather than introduced by the change under review.
+- Do not report one problem twice under two lenses. Report it once and name both lenses on it.
+
+## What not to report
+
+Silence beats a finding the reader has to disprove. Do not report:
+
+- a defect on a line this change did not touch, unless the change is what makes it reachable
+- anything a linter, compiler or type checker catches. All of them ran before the review and passed
+- a lint or vet rule the code silences deliberately, with the directive visible
+- a missing test, missing doc or general-quality observation the project's own rules do not ask for
+- a nitpick a senior engineer reading this diff would not raise
+- a behaviour change that is plainly the point of the change
+
+Pre-existing problems are the one exception: report them, and say so, so the reader can weigh them
+separately from what the change introduced.

package/adapters/claude/olko-github-pr/skills/lekker-review/scripts/fixtures/context.json

@@ -0,0 +1,3 @@
+{
+  "houseRulesFile": "house-rules.md"
+}

package/adapters/claude/olko-github-pr/skills/lekker-review/scripts/fixtures/house-rules.md

@@ -0,0 +1,11 @@
+# Fixture house rules
+
+### TS-1 — Type safety
+
+### TS-2 — No JavaScript files
+
+### GQL-1 — Complete pagination
+
+### PR-1 — Ticket-prefixed titles
+
+### SEC-7 — Never log session tokens

package/adapters/claude/olko-github-pr/skills/lekker-review/scripts/fixtures/revmux-report.json

@@ -0,0 +1,179 @@
+{
+  "findings": [
+    {
+      "id": "f1",
+      "file": "web/services/order-sync.ts",
+      "line": 42,
+      "end_line": 44,
+      "severity": "critical",
+      "confidence": 0.9,
+      "title": "Race between webhook retry and manual sync writes duplicate fulfillment",
+      "body": "Two concurrent writers can both pass the guard and insert a fulfillment row.",
+      "fix": "Take a row lock on the order before the check-then-insert.",
+      "sources": ["quality+impl"],
+      "lenses": ["lekker-quality"],
+      "verdict": "confirmed"
+    },
+    {
+      "id": "f2",
+      "file": "web/services/pricing.ts",
+      "line": 88,
+      "end_line": 90,
+      "severity": "major",
+      "confidence": 0.75,
+      "title": "Discount stacking ignores currency rounding",
+      "body": "Two agents independently flagged the same rounding gap on stacked discounts.",
+      "fix": "Round once at the end, not after each discount.",
+      "sources": ["quality+impl", "simpl+conventions"],
+      "lenses": ["lekker-quality", "lekker-simplification"],
+      "verdict": "refined"
+    },
+    {
+      "id": "f3",
+      "file": "web/services/logger.ts",
+      "line": 12,
+      "end_line": 12,
+      "severity": "minor",
+      "confidence": 0.6,
+      "title": "Log helper name does not follow the naming matrix",
+      "body": "getLogger performs no I/O, per teifi-conventions section 1 it should not be prefixed get.",
+      "fix": "Rename to buildLogger.",
+      "sources": ["simpl+conventions"],
+      "lenses": ["lekker-conventions"],
+      "verdict": "confirmed"
+    },
+    {
+      "id": "f4",
+      "file": "web/services/webhook.ts",
+      "line": 5,
+      "end_line": 5,
+      "severity": "minor",
+      "confidence": 0.4,
+      "title": "Unused import left over from a refactor",
+      "body": "Import of `crypto` is unused after the signature check moved.",
+      "fix": "Remove the unused import.",
+      "sources": ["adversarial"],
+      "lenses": ["adversarial"],
+      "verdict": "immaterial"
+    },
+    {
+      "id": "f5",
+      "file": "web/services/refund.ts",
+      "line": 60,
+      "end_line": 61,
+      "severity": "major",
+      "confidence": 0.5,
+      "title": "Refund total may double-count a tip",
+      "body": "Speculative -- verifier could not reproduce a path where the tip line is summed twice.",
+      "fix": "n/a",
+      "sources": ["adversarial"],
+      "lenses": ["adversarial"],
+      "verdict": "rejected"
+    },
+    {
+      "id": "f6",
+      "file": "web/services/inventory.ts",
+      "line": 21,
+      "end_line": 21,
+      "severity": "minor",
+      "confidence": 0.7,
+      "title": "[TS-1] Unsafe cast on inventory adjustment payload",
+      "body": "const qty = payload as any; -- a bare `as any` cast on external webhook input, no runtime type check follows it.",
+      "fix": "Parse payload with the zod schema and drop the cast.",
+      "sources": ["quality+impl"],
+      "lenses": ["lekker-quality"],
+      "verdict": "rejected"
+    },
+    {
+      "id": "f7",
+      "file": "web/services/inventory.ts",
+      "line": 30,
+      "end_line": 30,
+      "severity": "minor",
+      "confidence": 0.3,
+      "title": "[TS-1] Type safety concern in inventory handler",
+      "body": "This function handles any inventory update and could fail for any malformed input; consider adding validation.",
+      "fix": "Add input validation.",
+      "sources": ["quality+impl"],
+      "lenses": ["lekker-quality"],
+      "verdict": "rejected"
+    },
+    {
+      "id": "f8",
+      "file": "web/services/session.ts",
+      "line": 14,
+      "end_line": 14,
+      "severity": "minor",
+      "confidence": 0.8,
+      "title": "[SEC-7] Session token is logged",
+      "body": "The configured security rule forbids `logger.info(sessionToken)`.",
+      "fix": "Remove the token from the log payload.",
+      "sources": ["quality+impl"],
+      "lenses": ["lekker-quality"],
+      "verdict": "rejected"
+    },
+    {
+      "id": "f9",
+      "file": "web/services/session.ts",
+      "line": 20,
+      "end_line": 20,
+      "severity": "minor",
+      "confidence": 0.3,
+      "title": "[SEC-7] Possible session concern",
+      "body": "The session handling might expose sensitive data in some circumstances.",
+      "fix": "Review the session handling.",
+      "sources": ["quality+impl"],
+      "lenses": ["lekker-quality"],
+      "verdict": "rejected"
+    },
+    {
+      "id": "f10",
+      "file": "web/services/order-sync.test.ts",
+      "line": 55,
+      "end_line": 55,
+      "severity": "major",
+      "confidence": 0.85,
+      "title": "Operator-flip mutation escapes the happy-path assertion",
+      "body": "Changing the retry guard from && to || still passes the only assertion.",
+      "fix": "Add a case that exercises one false operand.",
+      "sources": ["tests"],
+      "lenses": ["lekker-test-quality"],
+      "verdict": "confirmed"
+    },
+    {
+      "id": "f11",
+      "file": "web/services/order-sync.test.ts",
+      "line": 70,
+      "end_line": 70,
+      "severity": "minor",
+      "confidence": 0.8,
+      "title": "Mock assertion freezes the client call shape",
+      "body": "The test asserts toHaveBeenCalledWith instead of the observable result.",
+      "fix": "Assert the returned synchronization state.",
+      "sources": ["tests"],
+      "lenses": ["lekker-test-quality"],
+      "verdict": "confirmed"
+    }
+  ],
+  "pre_existing": [
+    {
+      "file": "web/services/order-sync.ts",
+      "line": 200,
+      "title": "Repo-wide: no retry backoff on the fulfillment API client",
+      "body": "Pre-existing since before this diff; noted for awareness only.",
+      "lenses": ["lekker-implementation"]
+    }
+  ],
+  "open_questions": [
+    "Is the webhook retry expected to be idempotent, or does the client dedupe upstream?"
+  ],
+  "sources": {
+    "agents": [
+      { "name": "quality+impl", "executor": "claude", "actual_model": "claude-sonnet-5", "effort": "medium", "tokens": 42000, "raised": 4, "degraded": false },
+      { "name": "simpl+conventions", "executor": "claude", "actual_model": "claude-sonnet-5", "effort": "medium", "tokens": 31000, "raised": 2, "degraded": false },
+      { "name": "adversarial", "executor": "claude", "actual_model": "claude-sonnet-5", "effort": "high", "tokens": 18000, "raised": 2, "degraded": true },
+      { "name": "malformed-cost", "executor": "claude", "actual_model": "claude-sonnet-5", "effort": "medium", "tokens": "unknown", "raised": 0, "degraded": false }
+    ]
+  },
+  "stats": { "tokens": 91000 }
+}

package/adapters/claude/olko-github-pr/skills/lekker-review/scripts/install-revmux-prompts.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Installs lekker's revmux lenses + profiles into ~/.config/revmux (layer 2),
+# idempotently. --check verifies without writing.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+SRC_LENSES="$REPO_ROOT/references/revmux/lenses"
+SRC_PROFILES="$REPO_ROOT/references/revmux/profiles"
+
+CONFIG_DIR="${REVMUX_CONFIG_DIR:-$HOME/.config/revmux}"
+DST_LENSES="$CONFIG_DIR/lenses"
+DST_PROFILES="$CONFIG_DIR/prompts/profiles"
+
+CHECK_MODE=0
+if [ "${1:-}" = "--check" ]; then
+  CHECK_MODE=1
+fi
+
+if grep -rln 'codex' "$SRC_LENSES" "$SRC_PROFILES" >/dev/null 2>&1; then
+  echo "refusing to install: codex reference found under references/revmux/" >&2
+  exit 1
+fi
+
+FAIL=0
+
+sync_one() {
+  local src="$1" dst="$2"
+  local name
+  name="$(basename "$src")"
+
+  if [ "$CHECK_MODE" -eq 1 ]; then
+    if [ ! -f "$dst" ]; then
+      echo "missing: $name"
+      FAIL=1
+    elif ! diff -q "$src" "$dst" >/dev/null 2>&1; then
+      echo "differs: $name"
+      FAIL=1
+    fi
+    return
+  fi
+
+  mkdir -p "$(dirname "$dst")"
+  if [ ! -f "$dst" ]; then
+    cp "$src" "$dst"
+    echo "installed: $name"
+  elif diff -q "$src" "$dst" >/dev/null 2>&1; then
+    echo "unchanged: $name"
+  else
+    echo "updated: $name"
+    diff -u "$dst" "$src" || true
+    cp "$src" "$dst"
+  fi
+}
+
+for f in "$SRC_LENSES"/*.md; do
+  sync_one "$f" "$DST_LENSES/$(basename "$f")"
+done
+
+for f in "$SRC_PROFILES"/*.md; do
+  sync_one "$f" "$DST_PROFILES/$(basename "$f")"
+done
+
+if [ "$CHECK_MODE" -eq 1 ]; then
+  exit "$FAIL"
+fi

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

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+// revmux-adapter.mjs -- turns a revmux report into lekker's findings JSON.
+//
+// Usage: node scripts/revmux-adapter.mjs <revmux.json> [--pricing FILE] [--context FILE] > findings.json
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const args = process.argv.slice(2)
+const reportPath = args[0]
+if (!reportPath) {
+  console.error('usage: revmux-adapter.mjs <revmux.json> [--pricing FILE] [--context FILE]')
+  process.exit(2)
+}
+function flagValue(name) {
+  const i = args.indexOf(name)
+  if (i === -1) return null
+  const value = args[i + 1]
+  if (!value || value.startsWith('--')) {
+    console.error(`revmux-adapter: ${name} requires a file path`)
+    process.exit(2)
+  }
+  return value
+}
+const pricingPath = flagValue('--pricing')
+const contextPath = flagValue('--context')
+
+function loadJson(label, path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch (error) {
+    console.error(`revmux-adapter: cannot read or parse ${label} JSON at ${path}: ${error.message}`)
+    process.exit(2)
+  }
+}
+
+const report = loadJson('report', reportPath)
+const pricing = pricingPath ? loadJson('pricing', pricingPath) : {}
+const contextJson = contextPath ? loadJson('context', contextPath) : null
+
+function configuredHardRules() {
+  const defaultPath = fileURLToPath(new URL('../references/house-rules.md', import.meta.url))
+  const configuredPath = (contextJson && typeof contextJson.houseRulesFile === 'string')
+    ? contextJson.houseRulesFile
+    : defaultPath
+  const houseRulesPath = contextPath && !configuredPath.startsWith('/')
+    ? resolve(dirname(contextPath), configuredPath)
+    : configuredPath
+
+  let text
+  try {
+    text = readFileSync(houseRulesPath, 'utf8')
+  } catch (error) {
+    console.error(`revmux-adapter: cannot read configured house rules at ${houseRulesPath}: ${error.message}`)
+    process.exit(2)
+  }
+
+  const tags = new Set()
+  for (const match of text.matchAll(/^#{2,6}\s+([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+)\b/gm)) {
+    if (!match[1].startsWith('EXAMPLE-')) tags.add(match[1])
+  }
+  return tags
+}
+
+const HARD_RULES = configuredHardRules()
+
+function hardRuleCorroborated(finding) {
+  const evidence = [finding.badCode, finding.description, finding.title]
+    .map(function(x) { return String(x || '') }).join('\n')
+  const file = String(finding.file || '')
+  const code = String(finding.badCode || '')
+
+  switch (finding.rule) {
+    case 'TS-1':
+      return /\bas\s+(?:[A-Z_$][\w$]*|string|number|boolean|bigint|symbol|object|unknown|never|any|const)\b/.test(code)
+        || /:\s*any\b|<\s*any[\s,>]|\bany\[\]/.test(code)
+    case 'TS-2':
+      return /\.js$/.test(file)
+    case 'GQL-1':
+      return /\bnodes\b|\bpageInfo\b|\bedges\b/.test(evidence)
+    case 'PR-1':
+      return /pr\s*(title|description)/i.test(file + '\n' + evidence)
+    default:
+      return code.trim().length > 0
+  }
+}
+
+function isHardRule(finding) {
+  if (typeof finding.rule !== 'string' || !HARD_RULES.has(finding.rule)) {
+    return false
+  }
+  return hardRuleCorroborated(finding)
+}
+
+function extractRule(title) {
+  const m = /^\[([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+)\]/.exec(String(title || ''))
+  return m && HARD_RULES.has(m[1]) ? m[1] : undefined
+}
+
+function mapSeverity(f) {
+  if (f.severity === 'critical') return 'critical'
+  if (f.severity === 'major') return 'important'
+  if (f.severity === 'minor') {
+    return (f.lenses || []).includes('lekker-conventions') ? 'idiomatic' : 'observation'
+  }
+  return 'observation'
+}
+
+// Pull an inline code snippet out of the body so hardRuleCorroborated has
+// something to check against; revmux findings carry no separate badCode field.
+function extractBadCode(body) {
+  const text = String(body || '')
+  const backtick = /`([^`]+)`/.exec(text)
+  if (backtick) return backtick[1]
+  const dashCode = /--\s*(.+)$/.exec(text.split('\n')[0])
+  return dashCode ? dashCode[1] : ''
+}
+
+const findings = []
+let droppedCount = 0
+let hardRuleCount = 0
+
+for (const f of report.findings || []) {
+  const rule = extractRule(f.title)
+  const badCode = extractBadCode(f.body)
+  const base = {
+    file: f.file,
+    line: f.line,
+    severity: mapSeverity(f),
+    title: f.title,
+    description: f.body,
+    badCode,
+    fix: f.fix,
+    confidence: f.confidence,
+    rule,
+    dimension: f.lenses || [],
+  }
+  if ((f.sources || []).length >= 2) {
+    base.agreedBy = f.sources
+  }
+
+  const rejectedOrImmaterial = f.verdict === 'rejected' || f.verdict === 'immaterial'
+
+  if (!rejectedOrImmaterial) {
+    base.verifierReasoning = `revmux verify: ${f.verdict}`
+    findings.push(base)
+    continue
+  }
+
+  // A hard-rule tag whose own quoted code corroborates it is Critical
+  // regardless of revmux's verdict.
+  if (isHardRule({ rule, badCode, description: f.body, title: f.title, file: f.file })) {
+    hardRuleCount++
+    base.severity = 'critical'
+    base.verifierReasoning = `hard rule ${rule}: corroborated by quoted code, re-promoted despite revmux verdict "${f.verdict}"`
+    findings.push(base)
+    continue
+  }
+
+  droppedCount++
+}
+
+const reportFindings = findings.slice()
+
+for (const pe of report.pre_existing || []) {
+  findings.push({
+    file: pe.file,
+    line: pe.line,
+    severity: 'observation',
+    title: pe.title,
+    description: `Pre-existing: ${pe.body}`,
+    badCode: extractBadCode(pe.body),
+    fix: '',
+    dimension: pe.lenses || [],
+  })
+}
+
+const questions = report.open_questions || []
+
+const implementationFindings = reportFindings.filter(function(f) {
+  return f.dimension.includes('lekker-implementation')
+})
+const testQualityFindings = reportFindings.filter(function(f) {
+  return f.dimension.includes('lekker-test-quality')
+})
+const mutationFindings = testQualityFindings.filter(function(f) {
+  return /mutation|operator flip|off-by-one/i.test(`${f.title}\n${f.description}`)
+})
+const mockFindings = testQualityFindings.filter(function(f) {
+  return /\bmock(?:ing|ed|s)?\b|\bspy(?:ing)?\b|toHaveBeenCalled/i.test(`${f.title}\n${f.description}`)
+})
+
+const acCoverage = implementationFindings.length > 0
+  ? implementationFindings.map(function(f) { return `${f.title}: ${f.description}` }).join('\n')
+  : 'No acceptance-criteria gaps were reported by the revmux implementation lens.'
+const coverageVerdict = testQualityFindings.length > 0
+  ? `${testQualityFindings.length} test-quality finding(s): ${testQualityFindings.map(function(f) { return f.title }).join('; ')}`
+  : 'No test-quality gaps were reported by the revmux test-quality lens.'
+const mutationSlip = mutationFindings.length > 0
+  ? mutationFindings.map(function(f) { return f.description }).join('\n')
+  : 'No mutation-slip gap was reported by the revmux test-quality lens.'
+const mockSmells = mockFindings.map(function(f) {
+  return { file: f.file, line: f.line, description: f.description, fix: f.fix }
+})
+
+const agentsIn = (report.sources && report.sources.agents) || []
+const pricingMissing = []
+let totalUsd = 0
+let anyUsdKnown = false
+
+const agents = agentsIn.map(function(a) {
+  const priceEntry = pricing[a.actual_model]
+  let usd = null
+  if (priceEntry) {
+    const rate = (typeof priceEntry.output === 'number') ? priceEntry.output : priceEntry.blended
+    if (typeof a.tokens === 'number' && Number.isFinite(a.tokens) && typeof rate === 'number' && Number.isFinite(rate)) {
+      usd = (a.tokens / 1e6) * rate
+      anyUsdKnown = true
+      totalUsd += usd
+    }
+  } else {
+    pricingMissing.push(a.actual_model)
+  }
+  return {
+    name: a.name,
+    model: a.actual_model,
+    effort: a.effort,
+    tokens: a.tokens,
+    usd,
+    raised: a.raised,
+    degraded: Boolean(a.degraded),
+  }
+})
+
+const degraded = agents.filter(function(a) { return a.degraded }).map(function(a) { return a.name })
+const totalTokens = (report.stats && report.stats.tokens) || agentsIn.reduce(function(s, a) { return s + (a.tokens || 0) }, 0)
+
+const output = {
+  engine: 'revmux',
+  findings,
+  questions,
+  droppedCount,
+  downgradedCount: 0,
+  hardRuleCount,
+  agentCount: agentsIn.length,
+  degraded,
+  agents,
+  totalTokens,
+  totalUsd: anyUsdKnown ? totalUsd : null,
+  acCoverage,
+  coverageVerdict,
+  mutationSlip,
+  mockSmells,
+  stats: { durationMs: (report.stats && report.stats.durationMs) || null },
+}
+
+if (pricingMissing.length > 0) {
+  output.pricingMissing = Array.from(new Set(pricingMissing))
+}
+
+process.stdout.write(JSON.stringify(output, null, 2) + '\n')