@olegkoval/agent-skills 1.43.1 → 1.44.0

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

@@ -0,0 +1,156 @@
+#!/bin/bash
+# revmux-engine.sh -- lekker-review's revmux caller (Phase 2 of the revmux spike).
+#
+# Usage:
+#   revmux-engine.sh --task SLUG --run NAME --depth medium|deep --workdir DIR \
+#     --diff-file FILE --context-file FILE --profile-file FILE --out FILE \
+#     [--tasks-dir DIR] [--config-dir DIR]
+#
+# Builds one revmux round (scope.md, goal.md, input/context/, input/profile.md),
+# runs revmux --no-tui, writes its stdout JSON to --out, and exits with revmux's
+# own code (0 = no findings, 1 = findings, 2 = tool error). A round name that
+# already exists is revmux's own error -- this script never deletes anything to
+# work around it.
+set -euo pipefail
+
+TASK=""
+RUN=""
+DEPTH=""
+WORKDIR=""
+DIFF_FILE=""
+CONTEXT_FILE=""
+PROFILE_FILE=""
+OUT=""
+TASKS_DIR="${LEKKER_REVMUX_TASKS_DIR:-$HOME/code-reviews/revmux-tasks}"
+CONFIG_DIR="${REVMUX_CONFIG_DIR:-$HOME/.config/revmux}"
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --task) TASK="$2"; shift 2 ;;
+        --run) RUN="$2"; shift 2 ;;
+        --depth) DEPTH="$2"; shift 2 ;;
+        --workdir) WORKDIR="$2"; shift 2 ;;
+        --diff-file) DIFF_FILE="$2"; shift 2 ;;
+        --context-file) CONTEXT_FILE="$2"; shift 2 ;;
+        --profile-file) PROFILE_FILE="$2"; shift 2 ;;
+        --out) OUT="$2"; shift 2 ;;
+        --tasks-dir) TASKS_DIR="$2"; shift 2 ;;
+        --config-dir) CONFIG_DIR="$2"; shift 2 ;;
+        *) printf 'revmux-engine: unknown arg %s\n' "$1" >&2; exit 2 ;;
+    esac
+done
+
+for req in TASK RUN DEPTH WORKDIR DIFF_FILE CONTEXT_FILE PROFILE_FILE OUT; do
+    if [[ -z "${!req}" ]]; then
+        printf 'revmux-engine: missing required --%s\n' "$(printf '%s' "$req" | tr 'A-Z' 'a-z' | tr '_' '-')" >&2
+        exit 2
+    fi
+done
+
+for input in DIFF_FILE CONTEXT_FILE PROFILE_FILE; do
+    if [[ ! -r "${!input}" ]]; then
+        printf 'revmux-engine: --%s must be a readable file: %s\n' \
+            "$(printf '%s' "$input" | tr 'A-Z' 'a-z' | tr '_' '-')" "${!input}" >&2
+        exit 2
+    fi
+done
+
+WORKTREE_JSON="$(dirname "$CONTEXT_FILE")/worktree.json"
+if [[ ! -r "$WORKTREE_JSON" ]]; then
+    printf 'revmux-engine: worktree configuration must be readable: %s\n' "$WORKTREE_JSON" >&2
+    exit 2
+fi
+
+case "$DEPTH" in
+    medium|deep) ;;
+    *)
+        printf 'revmux-engine: depth "%s" is not supported by this engine (only medium|deep -- scan stays on the workflow engine, it has no worktree)\n' "$DEPTH" >&2
+        exit 2
+        ;;
+esac
+
+PROFILE_NAME="lekker-${DEPTH}"
+
+command -v revmux >/dev/null 2>&1 || { printf 'revmux-engine: revmux binary not found on PATH\n' >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || { printf 'revmux-engine: jq not found on PATH\n' >&2; exit 2; }
+
+# ---------------------------------------------------------------------------
+# Codex guard: refuse to run a profile whose resolved text names a codex/
+# runner. Company does not support the codex CLI (revmux is claude-only here).
+# ---------------------------------------------------------------------------
+PROFILE_TEXT_FILE="$CONFIG_DIR/prompts/profiles/${PROFILE_NAME}.md"
+if [[ ! -f "$PROFILE_TEXT_FILE" ]]; then
+    printf 'revmux-engine: cannot resolve profile text at %s to run the codex guard -- refusing to proceed\n' "$PROFILE_TEXT_FILE" >&2
+    exit 2
+fi
+if grep -q 'codex/' "$PROFILE_TEXT_FILE"; then
+    printf 'revmux-engine: profile %s names a codex/ runner -- codex is not supported here, refusing to run\n' "$PROFILE_TEXT_FILE" >&2
+    exit 2
+fi
+
+mkdir -p "$TASKS_DIR"
+
+NEW_JSON="$(revmux --tasks-dir "$TASKS_DIR" --config-dir "$CONFIG_DIR" new --task "$TASK" --run "$RUN")"
+
+resolve_new_path() {
+    local key="$1"
+    local value
+    if ! value="$(printf '%s' "$NEW_JSON" | jq -er --arg key "$key" \
+        '.[$key] | select(type == "string" and length > 0)')" \
+        || [[ -z "$value" || "$value" == "null" ]]; then
+        printf 'revmux-engine: revmux new returned an invalid %s path\n' "$key" >&2
+        return 2
+    fi
+    printf '%s' "$value"
+}
+
+SCOPE_FILE="$(resolve_new_path scope)"
+GOAL_FILE="$(resolve_new_path goal)"
+PROFILE_INPUT_FILE="$(resolve_new_path profile)"
+CONTEXT_DIR="$(resolve_new_path context)"
+
+mkdir -p "$CONTEXT_DIR"
+
+TARGET_LABEL="$(jq -r '.reviewTarget // "unknown target"' "$CONTEXT_FILE" 2>/dev/null || printf 'unknown target')"
+
+BASE_REF=""
+BASE_REF="$(jq -r '.mergeBase // .baseRef // empty' "$WORKTREE_JSON" 2>/dev/null || true)"
+
+{
+    printf '# Scope\n\n'
+    printf 'Under review: %s\n\n' "$TARGET_LABEL"
+    printf 'Diff file (authoritative): %s\n\n' "$DIFF_FILE"
+    if [[ -n "$BASE_REF" ]]; then
+        printf 'Reproduce inside WORKDIR with:\n\n    git -C %s diff %s...HEAD\n\n' "$WORKDIR" "$BASE_REF"
+    else
+        printf 'No base ref was recorded for this worktree; the diff file above is authoritative, do not attempt to reconstruct it from git.\n\n'
+    fi
+} > "$SCOPE_FILE"
+
+{
+    printf '# Goal\n\n'
+    printf '## PR title\n\n%s\n\n' "$(jq -r '.reviewTarget // "none provided"' "$CONTEXT_FILE" 2>/dev/null || printf 'none provided')"
+    printf '## Ticket / acceptance criteria\n\n%s\n\n' "$(jq -r '.acList // "none provided"' "$CONTEXT_FILE" 2>/dev/null || printf 'none provided')"
+    printf '## Scoping decisions\n\n%s\n\n' "$(jq -r '.scopingDecisions // "none provided"' "$CONTEXT_FILE" 2>/dev/null || printf 'none provided')"
+} > "$GOAL_FILE"
+
+cp "$CONTEXT_FILE" "$CONTEXT_DIR/context.json"
+cp "$DIFF_FILE" "$CONTEXT_DIR/pr.diff"
+cp "$WORKTREE_JSON" "$CONTEXT_DIR/worktree.json"
+cp "$PROFILE_FILE" "$PROFILE_INPUT_FILE"
+
+REVMUX_OUT="$OUT"
+set +e
+revmux --task "$TASK" --run "$RUN" --profile "$PROFILE_NAME" \
+    --workdir "$WORKDIR" --tasks-dir "$TASKS_DIR" --config-dir "$CONFIG_DIR" \
+    --no-tui > "$REVMUX_OUT"
+CODE=$?
+set -e
+
+case "$CODE" in
+    0) printf 'revmux exit 0 (no findings)\n' >&2 ;;
+    1) printf 'revmux exit 1 (findings reported)\n' >&2 ;;
+    *) printf 'revmux exit %s (tool error)\n' "$CODE" >&2 ;;
+esac
+
+exit "$CODE"

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

@@ -183,5 +183,81 @@ if (!hasRouting) {
   }
 }
 
+console.log('\nrevmux adapter: fixture mapping')
+{
+  const { execFileSync, spawnSync } = await import('node:child_process')
+  const fixturePath = join(SKILL, 'scripts', 'fixtures', 'revmux-report.json')
+  const contextPath = join(SKILL, 'scripts', 'fixtures', 'context.json')
+  const pricingPath = join(SKILL, 'references', 'pricing.json')
+  const adapterPath = join(SKILL, 'scripts', 'revmux-adapter.mjs')
+  const adapterArgs = [adapterPath, fixturePath, '--pricing', pricingPath, '--context', contextPath]
+  const out = execFileSync('node', adapterArgs, { encoding: 'utf8' })
+  const adapted = JSON.parse(out)
+
+  check('engine tag', adapted.engine, 'revmux')
+  check('critical confirmed kept critical',
+    adapted.findings.some(f => f.title.includes('Race between webhook retry') && f.severity === 'critical'), true)
+  check('major refined -> important, agreedBy from 2 sources',
+    (() => {
+      const f = adapted.findings.find(f => f.title.includes('Discount stacking'))
+      return f && f.severity === 'important' && Array.isArray(f.agreedBy) && f.agreedBy.length === 2
+    })(), true)
+  check('minor + lekker-conventions lens -> idiomatic',
+    adapted.findings.find(f => f.title.includes('naming matrix'))?.severity, 'idiomatic')
+  check('immaterial verdict dropped, not re-promoted',
+    adapted.findings.some(f => f.title.includes('Unused import')), false)
+  check('rejected non-hard-rule dropped',
+    adapted.findings.some(f => f.title.includes('double-count a tip')), false)
+  check('TS-1 rejected but corroborated by quoted code IS re-promoted to critical',
+    (() => {
+      const f = adapted.findings.find(f => f.title.includes('Unsafe cast on inventory adjustment'))
+      return f && f.severity === 'critical' && f.rule === 'TS-1'
+    })(), true)
+  check('TS-1 rejected with no corroborating code stays dropped',
+    adapted.findings.some(f => f.title.includes('Type safety concern in inventory handler')), false)
+  check('prose without an extracted snippet leaves badCode empty',
+    adapted.findings.find(f => f.title.includes('no retry backoff'))?.badCode, '')
+  check('configured custom hard rule with quoted code is re-promoted',
+    adapted.findings.find(f => f.title.includes('Session token is logged'))?.severity, 'critical')
+  check('configured custom hard rule without quoted code stays dropped',
+    adapted.findings.some(f => f.title.includes('Possible session concern')), false)
+  check('pre_existing becomes observation with Pre-existing: prefix',
+    (() => {
+      const f = adapted.findings.find(f => f.title.includes('no retry backoff'))
+      return f && f.severity === 'observation' && f.description.startsWith('Pre-existing:')
+    })(), true)
+  check('open_questions pass through as questions',
+    adapted.questions.length, 1)
+  check('degraded agent surfaced by name',
+    adapted.degraded, ['adversarial'])
+  check('droppedCount counts four rejected or immaterial findings', adapted.droppedCount, 4)
+  check('hardRuleCount counts built-in and custom re-promotions', adapted.hardRuleCount, 2)
+  check('totalUsd computed from known pricing', typeof adapted.totalUsd === 'number' && adapted.totalUsd > 0, true)
+  check('malformed token rows do not make totalUsd NaN', Number.isFinite(adapted.totalUsd), true)
+  check('malformed token rows keep their own usd unknown',
+    adapted.agents.find(a => a.name === 'malformed-cost')?.usd, null)
+  check('no pricingMissing when all models are priced', adapted.pricingMissing, undefined)
+  check('test-quality coverage verdict is populated from attributed findings',
+    adapted.coverageVerdict.includes('Operator-flip mutation'), true)
+  check('mutation-slip summary is populated from attributed findings',
+    adapted.mutationSlip.includes('retry guard'), true)
+  check('mock smells are structured from attributed findings', adapted.mockSmells.length, 1)
+
+  const noPricingOut = execFileSync('node', [adapterPath, fixturePath, '--context', contextPath], { encoding: 'utf8' })
+  const noPricingAdapted = JSON.parse(noPricingOut)
+  check('without a pricing file every model is pricingMissing',
+    noPricingAdapted.pricingMissing?.includes('claude-sonnet-5'), true)
+  check('without a pricing file totalUsd is null', noPricingAdapted.totalUsd, null)
+
+  for (const [label, badArgs] of [
+    ['report', [adapterPath, join(SKILL, 'SKILL.md')]],
+    ['pricing', [adapterPath, fixturePath, '--pricing', join(SKILL, 'SKILL.md'), '--context', contextPath]],
+  ]) {
+    const failedRun = spawnSync('node', badArgs, { encoding: 'utf8' })
+    check(`invalid ${label} JSON exits 2`, failedRun.status, 2)
+    check(`invalid ${label} JSON has a clear error`, failedRun.stderr.includes(`${label} JSON`), true)
+  }
+}
+
 console.log(failed === 0 ? '\nall checks passed\n' : `\n${failed} check(s) FAILED\n`)
 process.exit(failed === 0 ? 0 : 1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olegkoval/agent-skills",
-  "version": "1.43.1",
+  "version": "1.44.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.43.1",
+  "version": "1.44.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.43.1",
+  "version": "1.44.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.43.1",
+  "version": "1.44.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.43.1",
+  "version": "1.44.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.43.1",
+  "version": "1.44.0",
   "author": {
     "name": "Oleg Koval"
   },

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

@@ -55,6 +55,10 @@ FAANG-grade code review. Isolated worktree checkout, full context gathering
 you have MCP tools configured for), then 5 parallel specialized review
 agents, a finding-verification pass, and one unified markdown output.
 
+An optional `--engine revmux` flag can replace the Step 2 Workflow-tool pipeline
+with revmux (profiles and lenses under `references/revmux/`); default stays
+`workflow`, and both engines feed the same Step 3 synthesis.
+
 Two modes, same review engine:
 
 | Mode       | Target                              | Entry                                  |
@@ -232,6 +236,12 @@ in Step 4. Use it for a read-only pre-push look.
 **`--no-artifact` flag:** parse and store as `ARTIFACT=false` (default true).
 Skips Step 3.5 (living review artifact) silently.
 
+**`--engine revmux|workflow` flag:** parse and store as `ENGINE`, default
+`workflow`. `revmux` is allowed only at depth `medium` or `deep` - revmux's
+scripts reject `scan` (see Depth gate). If depth resolves to `scan` (explicit
+or auto), force `ENGINE=workflow` regardless of the flag and note `engine
+forced to workflow - revmux needs medium/deep` in the review header.
+
 **Re-review detection:** run
 `ls ~/code-reviews/*-<TARGET_SLUG>-<repo-short-name>.md 2>/dev/null | sort | tail -1`
 (`TARGET_SLUG` = `pr-<PR_NUMBER>` in pr mode, `branch-<LOCAL_BRANCH sanitized to
@@ -420,7 +430,9 @@ their prompts wholesale - the workflow script delivers it by path.
 
 ---
 
-## Step 2 - Workflow (review + verify + critic)
+## Step 2 - Review engine (review + verify + critic)
+
+### ENGINE=workflow (default)
 
 Invoke the Workflow tool:
 
@@ -499,12 +511,61 @@ provers on `sonnet`, housekeeping on `haiku`. Only the synthesis in Step 3 runs
 on the session model.
 
 Return value from the workflow:
-`{findings, droppedCount, downgradedCount, hardRuleCount, proveAttemptCount, provenCount, acCoverage, coverageVerdict, mutationSlip, mockSmells, agentCount, outputTokens, turnTokensTotal}`
+`{engine, findings, droppedCount, downgradedCount, hardRuleCount, proveAttemptCount, provenCount, acCoverage, coverageVerdict, mutationSlip, mockSmells, agentCount, outputTokens, turnTokensTotal}`
 `outputTokens` is this workflow's own output spend; `turnTokensTotal` is the
 whole turn's shared pool (main loop included).
 
 Wait for the workflow to complete before proceeding to Step 3.
 
+### ENGINE=revmux
+
+revmux replaces Review, Dedup, Verify, and Critic with its own multi-agent
+round; Prove still runs inside `workflow.js`. Steps:
+
+1. `TASK_SLUG` = `<repo-short-name>-<TARGET_SLUG>`, `RUN` = `01-review`.
+2. Run the engine:
+
+   ```bash
+   ${CLAUDE_PLUGIN_ROOT}/scripts/revmux-engine.sh \
+     --task <TASK_SLUG> --run <RUN> --depth <depth> \
+     --workdir <worktreePath> \
+     --diff-file <scratchpad>/pr.diff \
+     --context-file <scratchpad>/context.json \
+     --profile-file ${CLAUDE_PLUGIN_ROOT}/references/revmux/profile.md \
+     --config-dir ~/.config/revmux \
+     --out <scratchpad>/revmux.json
+   ```
+
+3. Adapt the report:
+
+   ```bash
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/revmux-adapter.mjs \
+     <scratchpad>/revmux.json --pricing \
+     ${CLAUDE_PLUGIN_ROOT}/references/pricing.json \
+     --context <scratchpad>/context.json \
+     > <scratchpad>/findings.json
+   ```
+
+4. Invoke Workflow(`workflow.js`) with the same args as the `ENGINE=workflow`
+   path above, plus `engine: "revmux"` and
+   `findingsFile: "<scratchpad>/findings.json"`. It skips Review/Dedup/
+   Verify/Critic, runs Prove only, and its return adds `engine, questions,
+   agents, degraded, totalTokens, totalUsd` on top of the usual keys.
+5. **Fallback to `ENGINE=workflow` for this run** when either holds: the
+   engine script exits `2` (tool error - also raised for a missing profile
+   file, the codex guard, or an unsupported depth), or every row in the
+   adapter's `agents` array has `degraded: true`. State the fallback in the
+   review header (`**Note:** revmux unavailable - fell back to workflow
+   engine`) and re-run the `ENGINE=workflow` path from the top of Step 2.
+
+**Trust boundary:** always pass `--config-dir ~/.config/revmux` explicitly.
+Without it revmux also reads the reviewed repo's checked-in `.revmux/`, which
+is executed as prompts. `~/.config/revmux` is where
+`scripts/install-revmux-prompts.sh` puts the lekker profiles and lenses; run it
+with `--check` when the engine exits 2 complaining about a missing profile. The task archive lives under the tasks dir
+(`LEKKER_REVMUX_TASKS_DIR`, default `~/code-reviews/revmux-tasks`) and is not
+committed anywhere.
+
 ---
 
 ## Step 3 - Synthesize and output
@@ -600,6 +661,17 @@ requirements:
   cost. Input tokens are estimated (diff tokens x agent passes + context
   + prompt files). Use the pricing table in `references/output-format.md`.
   Real numbers only - no `<N>` placeholders.
+  When `ENGINE=revmux`: build the rows from the adapter's `agents` array
+  (`name`, `model`, `tokens`, `usd` per row) and report `totalUsd` as the
+  total. Read `pricingMissing`; when it is non-empty, explicitly mark `totalUsd`
+  as incomplete and name the unpriced models. State plainly that the USD figures are an API list-price estimate
+  computed from `references/pricing.json`'s placeholder prices
+  (`verified: false`) until that file is verified against real invoices.
+  Prove-phase tokens still come from the workflow return's `outputTokens`,
+  same as the workflow engine. When `questions` (from the adapter) is
+  non-empty, render them under a `## Questions for the author` section. When
+  `degraded` is non-empty, add one banner line in the review header naming
+  the degraded agents, e.g. `⚠️ degraded: implementation, test-quality`.
 
 **Save the review:**
 
@@ -857,6 +929,17 @@ do verification inline per `references/agents/verifier.md`, and state this
 fallback in the review output under a
 `**Note:** Workflow tool unavailable - ran agents directly` line in the header.
 
+- `ENGINE=revmux` specific: on an exit-2 from `revmux-engine.sh`, or an
+  adapter report where every agent came back `degraded`, fall back to
+  `ENGINE=workflow` for that run (Step 2) rather than retrying revmux - this
+  is a fallback, not a retry loop, so it does not count against the
+  two-identical-failures rule above.
+- Never delete or rename anything under the revmux tasks dir
+  (`LEKKER_REVMUX_TASKS_DIR`, default `~/code-reviews/revmux-tasks`). A
+  duplicate run name (same `TASK_SLUG`/`RUN` pair) is revmux's own hard
+  error, by design - pick the next `NN-...` name (e.g. `03-...`) rather than
+  clearing the old one.
+
 Fix-mode specific:
 - Never claim a fix landed without a `git log` / `git status` receipt from the
   worktree. The review's proposed `fix` text is not an applied fix.

package/plugins/olko-github-pr/skills/lekker-review/references/pricing.json

@@ -0,0 +1,9 @@
+{
+  "note": "USD per million tokens, keyed by revmux's actual_model. revmux runs `claude --print` under subscription (Max plan) auth, so nothing here is a real API bill; this is an API-list-price ESTIMATE for the cost block only. Where a model exposes separate input/output prices, usd = tokens/1e6 * output price (output-only, not blended), because revmux reports a single combined `tokens` figure per agent with no input/output split to weight a blend. verified:false entries are not confirmed against a current price sheet (no local claude-api pricing doc found on this machine as of 2026-09-09) and must be checked before this cost block is trusted for a real decision.",
+  "claude-opus-5":   { "input": 15,  "output": 75,  "blended": 45,  "verified": false },
+  "claude-sonnet-5": { "input": 3,   "output": 15,  "blended": 9,   "verified": false },
+  "claude-haiku-4-5-20251001": { "input": 1, "output": 5, "blended": 3, "verified": false },
+  "opus":   { "input": 15, "output": 75, "blended": 45, "verified": false },
+  "sonnet": { "input": 3,  "output": 15, "blended": 9,  "verified": false },
+  "haiku":  { "input": 1,  "output": 5,  "blended": 3,  "verified": false }
+}

package/plugins/olko-github-pr/skills/lekker-review/references/revmux/lenses/lekker-conventions.md

@@ -0,0 +1,158 @@
+---
+description: deviations from Teifi's own codebase conventions — the "strong teammate" non-blocking lens
+---
+## Lens: lekker-conventions
+
+Review the change for deviations from Teifi's established codebase
+conventions and idioms. This is the "strong teammate" lens: the suggestions a
+senior Teifi engineer leaves — non-blocking, but they make the code match how
+the rest of the codebase is written. Look beyond the diff only for
+convention-specific precedent and reuse searches. Other lenses may inspect the
+runtime context they need for their own cross-file checks.
+
+Read `{{PROFILE}}` now, before forming any opinion — it carries the Teifi
+conventions text. Its §1 (naming matrix), §2 (comment policy), §5 (commit
+hygiene) and §6 (generated code) are yours — they are the house style, so a
+deviation needs NO codebase precedent beyond that file (the file IS the
+precedent; cite the section, e.g. "teifi-conventions §1 verbs").
+Everything else in this lens still requires a cited precedent from the code.
+
+Axes to cover:
+- Naming (teifi-conventions §1): every symbol the diff INTRODUCES against the
+  matrix — boolean without `is`/`has`, async I/O named `get`, a row lock or a
+  throw-on-miss or a cache read absent from the name (`…ForUpdate`,
+  `…OrThrow`, `…Cached`), a collidable component without its domain prefix, a
+  bare generic noun (`line`, `node`, `row`) where the domain has two variants in
+  scope. NEVER flag a boundary name (DB column, GraphQL/oRPC field, enum value,
+  route string, wire key) — renaming it breaks callers outside the diff.
+- Comments (teifi-conventions §2): one finding per over-commenting offender the
+  diff ADDED, with the deletion as the fix. Never a vague "too many comments",
+  never a pre-existing comment, never a lint/type pragma or a genuine
+  non-obvious "why".
+- Generated code (teifi-conventions §6): a changed `.sql` / `.graphql` /
+  `.json` schema / `prisma/schema.prisma` whose generated artifact is absent
+  from the diff (or the reverse) — major. Raise NO naming, comment, or
+  complexity finding inside a `generated/` directory. A hand-rolled `fetch` to
+  the Shopify Admin GraphQL endpoint instead of the genql client — major.
+- Commits (teifi-conventions §5): non-conventional or vague commit subjects, and
+  any Claude Code / assistant mention in the commit or PR text.
+- Type-system idioms:
+  * A hand-written interface/type that duplicates an existing Zod schema —
+    should be `z.infer<typeof zSchema>` so the schema stays the single source
+    of truth. (Grep for a matching z-schema in the same feature folder.)
+  * Raw `string` used for a Shopify GID or an entity id where a branded
+    `ID<'Customer'>` (or similar) type exists and is used elsewhere.
+  * A union typed as `as readonly string[]` / a hand-rolled `is...` guard where
+    a `z.enum([...])` + `z.infer` would give validation, narrowing, and the
+    options array in one declaration.
+  * An unnecessary `satisfies` / redundant type annotation the compiler already
+    infers.
+  * A GID validated/parsed inline where a shared helper exists (e.g.
+    `zNamespacedGid`). Grep the shared libs and the repo before asserting.
+- Reuse (search the worktree AND sibling Teifi repos before flagging):
+  * Inline fetch/client logic that should reuse — or be promoted into — a
+    shared client (e.g. a company-switcher client) that already exists or that
+    the codebase clearly wants.
+  * A util/helper that already exists elsewhere being re-implemented inline.
+  * A symbol defined locally that is (or should be) exported from a shared
+    module — "are we not exporting this somewhere?"
+- Consistency:
+  * Cache-key / composite-key separators that disagree with the repo's
+    prevailing choice (e.g. `:` vs `::`). Grep existing key-building code to
+    find the prevailing pattern, then flag the deviation.
+  * Ad-hoc error throwing where the repo has an idiom (e.g. `throw new
+    HttpError('...', 403)` instead of a bare string / generic Error).
+  * Naming/casing that breaks the convention used by sibling files.
+
+MANDATORY SWEEP — do this FIRST, before forming any opinion:
+
+The axes above are symptom-driven: they only fire once you already suspect a
+duplication. That is how a re-implemented helper slips through — nobody thinks to
+look. So run these enumerations mechanically, whether or not anything looks wrong.
+
+1. **Sibling sweep for every file the diff ADDS.** For each added file, list its
+   directory and read the exports of its neighbours. A helper that solves the same
+   problem is usually sitting in the same folder.
+
+   ```bash
+   REVIEW_CONFIG="{{CONTEXT}}/worktree.json"
+   WORKTREE="$(jq -er '.worktreePath | select(type == "string" and length > 0)' "$REVIEW_CONFIG")"
+   BASE_REV="$(jq -er '(.mergeBase // .baseRef) | select(type == "string" and length > 0)' "$REVIEW_CONFIG")"
+   REPO_ROOT="$(jq -er '.repoRoot | select(type == "string" and length > 0)' "$REVIEW_CONFIG")"
+   SIBLING_ROOT="$(dirname "$REPO_ROOT")"
+
+   git -C "$WORKTREE" diff --name-status "$BASE_REV"...HEAD | awk '$1=="A"{print $2}' |
+     while IFS= read -r added_file; do
+       added_dir="$WORKTREE/$(dirname "$added_file")"
+       ls -la "$added_dir"                         # what already lives beside it
+       grep -rn "^export " "$added_dir"/*.ts "$added_dir"/*.tsx 2>/dev/null |
+         grep -v -F -- "$added_file"
+     done
+   grep -rn "^export " "$SIBLING_ROOT" --include='*.ts' --include='*.tsx' \
+     --exclude-dir=node_modules 2>/dev/null
+   ```
+
+   A new `foo/bar-thing.ts` next to an existing `foo/thing.ts` is a finding waiting
+   to happen. Read the neighbour, do not just note its name.
+
+2. **New-symbol sweep.** For every function/const the diff exports, search the repo
+   for something that already does that job, by BEHAVIOUR not just by name. Names
+   rarely match; behaviour does.
+
+   ```bash
+   git -C "$WORKTREE" diff --unified=0 "$BASE_REV"...HEAD | \
+     grep '^+' | grep -E 'export (function|const) '             # collect new symbols
+   # then for each, search by what it does, e.g. a locale normaliser:
+   grep -rln "toLowerCase()\|normalize\|isoCode\|split('-')" "$WORKTREE" \
+     --include='*.ts' --include='*.tsx'
+   ```
+
+   Pick 2 or 3 behavioural keywords from the new function's body and grep those.
+   Reviewing the diff alone cannot catch this.
+
+3. **State what you swept.** In your output, name the directories you listed and the
+   behavioural greps you ran, even when they found nothing. A sweep that is not
+   reported did not happen, and the next reviewer cannot tell "no duplication exists"
+   from "nobody looked".
+
+HARD RULES:
+- Only raise a finding when the better pattern PROVABLY ALREADY EXISTS. Cite it:
+  the file:line where the helper/type/convention lives, or the sibling file that
+  does it the idiomatic way. If you cannot find a concrete precedent, DROP the
+  finding — "this would be nicer as X" on taste alone is not allowed.
+- Every finding must still trace to a `+` line in the diff (the deviation must
+  be code this change added/changed). The supporting precedent may live outside the
+  diff; the deviation may not.
+- These are suggestions, not blockers. Do not inflate severity. Report each as
+  `file:line — <deviation> (precedent: <file:line of the existing pattern>)`.
+- ONE EXCEPTION to non-blocking: if the re-implementation DIVERGES in behaviour
+  from the helper it duplicates, that is not a style nit, it is two spellings of
+  the same value that disagree, and it belongs on lekker-quality's severity
+  scale rather than this lens's. Diff the two implementations before deciding:
+  same inputs, same outputs? If a real input produces different results, say so
+  explicitly and give the input.
+
+To find precedents, you may run:
+
+```bash
+grep -rn "<symbol or pattern>" "$WORKTREE" --include='*.ts' --include='*.tsx'
+find "$SIBLING_ROOT" \( -name "*.ts" -o -name "*.tsx" \) ! -path "*/node_modules/*" \
+  | xargs grep -l "<symbol>" 2>/dev/null | head
+```
+
+Always include *.tsx. Extension and frontend code lives in .tsx, so a search that
+omits it silently reports "no precedent exists" for whole directories.
+
+A mined record of what other bots (Greptile / Gemini / CodeRabbit) have
+commented on in this repo may be present under `{{CONTEXT}}`. Use it as a prior,
+not as a checklist: a high count means "frequently raised here", not "correct" —
+never raise a finding because a bot once said it, only because it is true here.
+
+Rules:
+- Report file:line — description with a precedent citation. No positive
+  observations. No taste-only suggestions.
+- Quote the verbatim offending line(s) — never paraphrased, never reconstructed
+  from memory — and give a concrete drop-in fix, or when the fix is
+  architectural, a minimal skeleton plus one sentence on what else must change.
+- A finding you cannot quote and cannot fix is a finding you have not proven —
+  drop it instead.