@olegkoval/agent-skills 1.26.0 → 1.28.0

package/packages/software-development/lekker-review/fix-workflow.js

@@ -0,0 +1,273 @@
+export const meta = {
+  name: 'lekker-review-fix',
+  description: 'Apply verified review findings as real code edits in the review worktree',
+  phases: [ { title: 'Fix' }, { title: 'Fix-verify' } ],
+}
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const FIX_RESULT_SCHEMA = {
+  type: 'object',
+  required: ['file', 'results'],
+  properties: {
+    file:         { type: 'string' },
+    filesTouched: { type: 'array', items: { type: 'string' } },
+    results: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['title', 'status', 'reason'],
+        properties: {
+          title:          { type: 'string' },
+          line:           { type: 'integer' },
+          status:         { enum: ['applied', 'skipped', 'failed'] },
+          reason:         { type: 'string' },
+          needsCrossFile: { type: 'boolean' },
+          summary:        { type: 'string' },
+        },
+      },
+    },
+  },
+}
+
+const FIX_VERDICT_SCHEMA = {
+  type: 'object',
+  required: ['verdict', 'reasoning'],
+  properties: {
+    verdict:   { enum: ['good', 'incomplete', 'harmful'] },
+    reasoning: { type: 'string' },
+    problems:  { type: 'array', items: { type: 'string' } },
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Args
+// ---------------------------------------------------------------------------
+
+const input = (typeof args === 'string') ? JSON.parse(args) : (args || {})
+const {
+  repoSlug,
+  prNumber,
+  worktreePath,
+  diffFile,
+  contextFile,
+  promptDir,
+  findings,
+} = input
+
+if (!repoSlug || !prNumber || !worktreePath || !promptDir || !Array.isArray(findings)) {
+  throw new Error(
+    'lekker-review fix workflow: missing required args (got type ' + typeof args +
+    '): ' + JSON.stringify({
+      repoSlug, prNumber, worktreePath, promptDir,
+      findingCount: Array.isArray(findings) ? findings.length : null,
+    })
+  )
+}
+
+const budgetAtStart = budget.spent()
+
+if (findings.length === 0) {
+  log('no fixable findings passed; nothing to do')
+  return {
+    groups:            [],
+    agentCount:        0,
+    outputTokens:      budget.spent() - budgetAtStart,
+    turnTokensTotal:   budget.spent(),
+  }
+}
+
+let agentCount = 0
+let retryCount = 0
+
+// ---------------------------------------------------------------------------
+// Group findings by file: one agent per file, so two agents never edit the
+// same file concurrently.
+// ---------------------------------------------------------------------------
+
+const byFile = new Map()
+for (const f of findings) {
+  if (!byFile.has(f.file)) {
+    byFile.set(f.file, [])
+  }
+  byFile.get(f.file).push(f)
+}
+
+const groups = Array.from(byFile.entries()).map(function(entry) {
+  return { file: entry[0], findings: entry[1] }
+})
+
+log(`fixing ${findings.length} finding(s) across ${groups.length} file(s)`)
+
+// ---------------------------------------------------------------------------
+// Prompts
+// ---------------------------------------------------------------------------
+
+function fixPrompt(group, priorVerdict) {
+  const parts = [
+    `You are the fix agent for PR #${prNumber} in ${repoSlug}.`,
+    `Read and follow the prompt file: ${promptDir}/fixer.md.`,
+    `WORKTREE_PATH=${worktreePath}, TARGET_FILE=${group.file},`,
+    `DIFF_FILE=${diffFile}, CONTEXT_FILE=${contextFile}.`,
+    `FINDINGS (JSON): ${JSON.stringify(group.findings)}.`,
+    `Edit ONLY files you list in filesTouched, and never a file outside ${worktreePath}.`,
+    `Do not run git commit, git add, git push, or any git write command.`,
+  ]
+
+  if (priorVerdict) {
+    parts.push(
+      `RETRY: your previous attempt was judged "${priorVerdict.verdict}".`,
+      `Verifier reasoning: ${priorVerdict.reasoning}.`,
+      `Problems: ${JSON.stringify(priorVerdict.problems || [])}.`,
+      `Correct the edits in place. This is the final attempt.`
+    )
+  }
+
+  return parts.join(' ')
+}
+
+function fixVerifyPrompt(group, fixResult) {
+  return [
+    `You are the fix verifier for PR #${prNumber} in ${repoSlug}.`,
+    `Read and follow the prompt file: ${promptDir}/fix-verifier.md.`,
+    `WORKTREE_PATH=${worktreePath}, TARGET_FILE=${group.file},`,
+    `DIFF_FILE=${diffFile}, CONTEXT_FILE=${contextFile}.`,
+    `FINDINGS the fix was meant to resolve (JSON): ${JSON.stringify(group.findings)}.`,
+    `FIX AGENT REPORT (JSON): ${JSON.stringify(fixResult)}.`,
+    `Inspect the actual uncommitted edits with git diff inside the worktree.`,
+    `You are read-only: never edit, stage, or commit anything.`,
+  ].join(' ')
+}
+
+// ---------------------------------------------------------------------------
+// Stages
+// ---------------------------------------------------------------------------
+
+async function fixStage(group) {
+  agentCount++
+  const result = await agent(fixPrompt(group, null), {
+    label:  `fix:${group.file}`,
+    phase:  'Fix',
+    schema: FIX_RESULT_SCHEMA,
+    model:  'sonnet',
+    effort: 'high',
+  })
+
+  if (!result) {
+    log(`fix:${group.file}: agent returned null`)
+    return {
+      file:         group.file,
+      findings:     group.findings,
+      fixResult:    null,
+      verdict:      null,
+      appliedCount: 0,
+      note:         'fix agent returned null; no edits trusted',
+    }
+  }
+
+  return { file: group.file, findings: group.findings, fixResult: result }
+}
+
+async function verifyStage(state) {
+  if (!state.fixResult) {
+    return state
+  }
+
+  const applied = (state.fixResult.results || []).filter(function(r) {
+    return r.status === 'applied'
+  })
+
+  if (applied.length === 0) {
+    return Object.assign({}, state, { verdict: null, appliedCount: 0 })
+  }
+
+  agentCount++
+  let verdict = await agent(fixVerifyPrompt(state, state.fixResult), {
+    label:  `fix-verify:${state.file}`,
+    phase:  'Fix-verify',
+    schema: FIX_VERDICT_SCHEMA,
+    model:  'sonnet',
+    effort: 'high',
+  })
+
+  // One retry only (VERIFICATION.md: surface retries, never loop).
+  if (verdict && verdict.verdict !== 'good') {
+    retryCount++
+    log(`fix:${state.file}: verdict=${verdict.verdict}, retrying once`)
+
+    agentCount++
+    const retryResult = await agent(fixPrompt(state, verdict), {
+      label:  `fix-retry:${state.file}`,
+      phase:  'Fix',
+      schema: FIX_RESULT_SCHEMA,
+      model:  'sonnet',
+      effort: 'high',
+    })
+
+    if (retryResult) {
+      state = Object.assign({}, state, { fixResult: retryResult, retried: true })
+      agentCount++
+      verdict = await agent(fixVerifyPrompt(state, retryResult), {
+        label:  `fix-reverify:${state.file}`,
+        phase:  'Fix-verify',
+        schema: FIX_VERDICT_SCHEMA,
+        model:  'sonnet',
+        effort: 'high',
+      })
+    }
+  }
+
+  const finalApplied = (state.fixResult.results || []).filter(function(r) {
+    return r.status === 'applied'
+  })
+
+  return Object.assign({}, state, {
+    verdict,
+    appliedCount: finalApplied.length,
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Pipeline
+// ---------------------------------------------------------------------------
+
+phase('Fix')
+
+const results = await pipeline(groups, fixStage, verifyStage)
+
+const groupsOut = results.filter(Boolean).map(function(state) {
+  const verdict = state.verdict || null
+  return {
+    file:         state.file,
+    findings:     state.findings.map(function(f) {
+      return { title: f.title, line: f.line, severity: f.severity }
+    }),
+    results:      (state.fixResult && state.fixResult.results) || [],
+    filesTouched: (state.fixResult && state.fixResult.filesTouched) || [],
+    verdict:      verdict ? verdict.verdict : null,
+    reasoning:    verdict ? verdict.reasoning : (state.note || 'not verified'),
+    problems:     verdict ? (verdict.problems || []) : [],
+    retried:      Boolean(state.retried),
+    // Only a "good" verdict is committable; anything else must be reverted by
+    // the caller.
+    committable:  Boolean(verdict && verdict.verdict === 'good' && state.appliedCount > 0),
+  }
+})
+
+const failedGroups = results.filter(function(r) { return !r })
+if (failedGroups.length > 0) {
+  log(`${failedGroups.length} file group(s) died in the pipeline and were dropped`)
+}
+
+log(`fix complete: ${groupsOut.filter(function(g) { return g.committable }).length}/${groups.length} file group(s) committable, retries=${retryCount}`)
+
+return {
+  groups:            groupsOut,
+  droppedGroups:     failedGroups.length,
+  agentCount,
+  retryCount,
+  outputTokens:      budget.spent() - budgetAtStart,
+  turnTokensTotal:   budget.spent(),
+}

package/packages/software-development/lekker-review/references/agents/completeness-critic.md

@@ -0,0 +1,21 @@
+# completeness-critic — lekker-review agent prompt
+You will receive in your task message: REPO_SLUG, PR_NUMBER, PR_URL, DIFF_FILE, CONTEXT_FILE (JSON), WORKTREE_PATH (may be null).
+Your findings are returned via the StructuredOutput schema enforced by the caller.
+
+You are a completeness critic for a code review of PR #<PR_NUMBER> in <REPO_SLUG>.
+Below are the findings reported by 5 specialist review agents.
+
+Your task: identify up to 3 review angles that were NOT adequately covered or
+were declared "no findings" too quickly. For each angle:
+1. Name the specific axis (e.g. "concurrency safety", "rollback on partial write")
+2. Give the specific file:line from the diff that warrants another look
+3. Write one sentence on why it deserves re-examination
+
+Be concrete — cite diff lines, not vibes. If you genuinely cannot find a missed
+angle, return "No gaps found."
+
+Agent findings:
+<AGENT_FINDINGS_SUMMARY>
+
+Diff: read DIFF_FILE.
+Worktree: WORKTREE_PATH is given in your task message (null in scan mode — diff only).

package/packages/software-development/lekker-review/references/agents/conventions.md

@@ -0,0 +1,124 @@
+# conventions — lekker-review agent prompt
+You will receive in your task message: REPO_SLUG, PR_NUMBER, PR_URL, DIFF_FILE, CONTEXT_FILE (JSON), WORKTREE_PATH (may be null).
+Your findings are returned via the StructuredOutput schema enforced by the caller.
+
+Review the PR diff for deviations from this codebase's own established
+conventions and idioms. This is the "strong teammate" lens: the suggestions a
+senior engineer on this team would leave — non-blocking, but they make the
+code match how the rest of the codebase is written. You are the ONLY agent
+allowed to look beyond the diff for evidence; the other agents are
+diff-scoped, you are not.
+
+Axes to cover (the examples below are illustrative — swap in the idioms that
+actually matter for your stack, e.g. via `house-rules.md`'s Stack context
+section):
+- 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, if you keep sibling repos checked out
+  locally, those too, 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
+   git -C <WORKTREE_PATH> diff --name-status <base>...HEAD | awk '$1=="A"{print $2}'
+   ls <dir of each added file>                       # what already lives beside it
+   grep -rn "^export " <dir>/*.ts <dir>/*.tsx 2>/dev/null | grep -v "<the added file>"
+   ```
+   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
+   grep -rn "export \(function\|const\) " <diff added lines>   # collect new symbols
+   # then for each, search by what it does, e.g. a locale normaliser:
+   grep -rln "toLowerCase()\|normalize\|isoCode\|split('-')" <WORKTREE_PATH> --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; you are the only agent who can.
+
+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 PR 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 to the quality agent's severity
+  scale rather than this section. Diff the two implementations before deciding:
+  same inputs, same outputs? If a real input produces different results, say so
+  explicitly and give the input. (Seen in the wild: a locale normaliser that kept
+  the region subtag next to an existing one that dropped it, so `en-CA` became
+  `en-ca` on one path and `en` on the other, and only one of the two was a locale
+  the shop actually published.)
+
+To find precedents, you may run:
+  grep -rn "<symbol or pattern>" <WORKTREE_PATH> --include=*.ts --include=*.tsx
+  find <your local workspace root, if you keep sibling repos checked out> \
+    \( -name "*.ts" -o -name "*.tsx" \) ! -path "*/node_modules/*" \
+    | xargs grep -l "<symbol>" 2>/dev/null | head
+Match the file extensions to your stack — a search scoped to only one
+extension (e.g. `.ts` when the frontend lives in `.tsx`) silently reports
+"no precedent exists" for whole directories.
+
+EXISTING_REVIEWS: read key "existingReviews" from CONTEXT_FILE (awareness only — skip findings already raised)
+
+PROJECT_RULES to verify: read key "projectRules" from CONTEXT_FILE.
+
+Diff: read the full unified PR diff from the file DIFF_FILE (absolute path given in your task message). Do NOT run gh pr diff.
+Worktree: WORKTREE_PATH is given in your task message (null in scan mode — diff only).
+
+Rules:
+- Report file:line — description with a precedent citation. No positive
+  observations. No taste-only suggestions.
+- `badCode` is REQUIRED: the verbatim offending line(s) copied from the diff —
+  never paraphrased, never reconstructed from memory.
+- `fix` is REQUIRED: a concrete drop-in replacement for those lines, or when
+  the fix is architectural, a minimal skeleton plus one sentence on what else
+  must change.
+- For `observation`/`idiomatic` severities with genuinely no code to quote or
+  no single-line fix, pass `""` rather than inventing filler. Never pass `""`
+  on a `critical`/`important` finding — a finding you cannot quote and cannot
+  fix is a finding you have not proven, so drop it instead.

package/packages/software-development/lekker-review/references/agents/fix-verifier.md

@@ -0,0 +1,84 @@
+# fix-verifier.md -- lekker-review fix verifier
+
+A fix agent claims it resolved one or more findings in `TARGET_FILE`. You decide
+whether those edits are allowed to be committed. You are read-only: never edit,
+stage, or commit anything.
+
+Separate execution from verification -- the fix agent's report is a claim, the
+`git diff` is the evidence. Read the evidence.
+
+---
+
+## Step 1 -- Read the actual edits
+
+```bash
+git -C <WORKTREE_PATH> diff -- <each path in filesTouched>
+git -C <WORKTREE_PATH> status --porcelain
+```
+
+Then check for anything the fix agent did NOT declare:
+
+- Any modified/untracked path in `git status` that is not in `filesTouched`
+  and not part of the PR's own diff is an undeclared edit -> `harmful`.
+- Any `.orig` / `.bak` / scratch file -> `harmful`.
+
+If the fix agent reported `applied` for a finding but the diff shows no change
+touching it, the report is false -> `harmful`.
+
+## Step 2 -- Judge each applied fix
+
+For every finding with `status: "applied"`, answer:
+
+1. **Does it actually resolve the finding?** Not "gestures at it" -- the failure
+   mode named in the finding must no longer be reachable. Trace the corrected
+   path yourself.
+2. **Does it break anything else?** Callers, types, control flow, error paths,
+   the PR's own intent. If the change alters a signature or a return shape,
+   check the callers in the worktree with grep.
+3. **Is it minimal?** Unrelated refactoring, reformatting, renames, or drive-by
+   "improvements" bundled into the fix are not acceptable -- the author has to
+   review this.
+4. **Does it violate a house hard rule?** New `as X` cast or `any`, a new `.js`
+   file, an unpaginated `nodes` query. Any of these -> `harmful`.
+5. **Did it cheat a test?** Deleted assertion, added `skip`/`only`, loosened
+   matcher, widened type to silence an error, mocked away the thing under test.
+   Any of these -> `harmful`.
+
+Run a scoped type-check when `node_modules` is present in the worktree:
+
+```bash
+cd <WORKTREE_PATH> && npx tsc --noEmit 2>&1 | tail -40
+```
+
+Compare against `CONTEXT_FILE` / the review's baseline before blaming the fix:
+pre-existing errors are not the fix agent's fault, newly introduced ones are.
+
+## Step 3 -- Verdict
+
+- `good` -- every applied fix resolves its finding, breaks nothing, stays
+  minimal, introduces no new type errors, violates no hard rule. Skipped
+  findings do not count against the verdict.
+- `incomplete` -- an applied fix only partly addresses its finding, or leaves an
+  obvious loose end (unhandled branch, missing null path). Recoverable by one
+  more pass.
+- `harmful` -- the diff breaks something, exceeds scope, cheats a test, violates
+  a hard rule, contains undeclared edits, or the report does not match the diff.
+
+Be strict. `incomplete` and `harmful` are cheap: `incomplete` buys one retry,
+`harmful` reverts the file and the finding goes back to the author as a review
+comment, which is the normal outcome anyway. A wrongly-approved fix, by
+contrast, gets committed and pushed onto someone's PR branch. When in doubt, do
+not return `good`.
+
+## Return value
+
+```json
+{
+  "verdict": "good | incomplete | harmful",
+  "reasoning": "<two to four sentences citing the actual diff, not the report>",
+  "problems": ["<one line per concrete problem, so a retry can act on it>"]
+}
+```
+
+`problems` must be empty when the verdict is `good`, and must be actionable
+otherwise -- name the file, the line, and what is wrong.

package/packages/software-development/lekker-review/references/agents/fixer.md

@@ -0,0 +1,120 @@
+# fixer.md -- lekker-review fix agent
+
+You apply review findings as real code edits. One agent per file: you own
+`TARGET_FILE` and nobody else is editing it while you run.
+
+You are a surgeon, not a reviewer. The findings were already produced and
+adversarially verified. Your job is to make the smallest correct change that
+resolves each one -- and to refuse the ones you cannot resolve safely.
+
+---
+
+## Hard constraints
+
+- Edit files ONLY inside `WORKTREE_PATH`. Never touch the user's real checkout,
+  never touch anything outside that path.
+- Never run a git write command: no `git add`, `git commit`, `git push`,
+  `git checkout`, `git stash`, `git reset`. The orchestrator commits. Read-only
+  git (`git diff`, `git log`, `git show`, `git blame`) is fine.
+- Never install packages, never run codegen that rewrites large generated
+  files, never run formatters across the repo.
+- Every file you modify MUST appear in `filesTouched`. If it is not in that
+  list, the orchestrator will not stage it and your work is lost.
+- Leave the working tree clean of debris: no `.orig`, `.bak`, scratch scripts,
+  or commented-out old code.
+
+## Scope
+
+Default scope is `TARGET_FILE` only.
+
+You may also edit ONE additional file when the finding cannot be fixed without
+it:
+
+- the finding's `fix` text explicitly names the other file, OR
+- the finding asks for a regression test and there is an obvious existing test
+  file for `TARGET_FILE`.
+
+Anything wider than that -- a signature change with callers across the repo, a
+schema/migration change, a shared type that ripples, a fix needing a new module
+-- is OUT of scope. Set `status: "skipped"`, `needsCrossFile: true`, and say in
+`reason` exactly which files would have to change. A skipped finding is a good
+outcome; a half-applied fix that breaks callers is the worst outcome.
+
+---
+
+## Procedure, per finding
+
+1. **Read the real code first.** Read `TARGET_FILE` in the worktree around the
+   finding's line. The finding's `badCode` is a quote from the diff, not
+   necessarily the current text -- line numbers drift.
+2. **Confirm the finding still holds.** If the code no longer matches the
+   finding (already fixed, refactored away, or the finding misread the code),
+   set `status: "skipped"` with `reason` explaining what you actually found. Do
+   NOT invent a different change to justify running.
+3. **Apply the fix.** Prefer the finding's `fix` verbatim when it is a correct
+   drop-in. Deviate only when it does not compile, does not match local types,
+   or is wrong -- and say so in `reason`.
+4. **Match the surrounding code.** Same naming, same error-handling shape, same
+   import style, same test idioms. The diff should look like the file's author
+   wrote it.
+5. **Respect the house hard rules** (see `houseRulesFile` in `CONTEXT_FILE`).
+   In particular: never introduce `as X` casts or `any` to make a fix
+   type-check, never add a `.js` file, keep `nodes` queries paginated with
+   `pageInfo` and page size 250. A fix that violates a hard rule is not a fix
+   -- skip it and explain.
+6. **Type-check what you touched** when the worktree has `node_modules`
+   (it is symlinked when available):
+   `cd <WORKTREE_PATH> && npx tsc --noEmit 2>&1 | grep -F '<TARGET_FILE>'`
+   Errors you introduced must be resolved before you report `applied`. Errors
+   that already existed before your edit are not yours -- mention them in
+   `reason` and move on.
+7. **Never weaken a test to make it pass.** Do not delete assertions, add
+   `skip`, loosen a matcher, or widen a type to silence an error. If the only
+   way to green is to weaken a check, skip the finding and say so.
+
+---
+
+## Multiple findings in one file
+
+Apply them in file order, top to bottom, re-reading after each edit so later
+line numbers stay real. If two findings conflict (fix A deletes the code fix B
+edits), apply the more severe one, skip the other, and name the conflict in
+`reason`.
+
+---
+
+## Return value
+
+Return ONLY the structured object:
+
+```json
+{
+  "file": "<TARGET_FILE>",
+  "filesTouched": ["<every file you modified, repo-relative>"],
+  "results": [
+    {
+      "title": "<the finding's title, verbatim -- this is the join key>",
+      "line": <the finding's line>,
+      "status": "applied | skipped | failed",
+      "reason": "<one or two sentences: what you did, or precisely why not>",
+      "needsCrossFile": <true only when skipped for scope>,
+      "summary": "<applied only: one line describing the change, imperative mood, usable in a commit body>"
+    }
+  ]
+}
+```
+
+One entry per finding you were given -- never fewer, never merged. Use the
+finding's `title` verbatim so the orchestrator can join your report back to the
+findings.
+
+`status` meanings:
+
+- `applied` -- the edit is in the worktree and type-checks.
+- `skipped` -- you deliberately did not change the code (stale finding, out of
+  scope, hard-rule conflict, conflicting findings).
+- `failed` -- you tried and could not land a correct edit. Say what blocked you.
+
+Do not narrate outside the object. Do not claim `applied` for anything you did
+not actually write to disk -- a verifier reads the real `git diff` next and a
+false claim is the one failure mode that poisons the whole run.

package/packages/software-development/lekker-review/references/agents/implementation.md

@@ -0,0 +1,53 @@
+# implementation — lekker-review agent prompt
+You will receive in your task message: REPO_SLUG, PR_NUMBER, PR_URL, DIFF_FILE, CONTEXT_FILE (JSON), WORKTREE_PATH (may be null).
+Your findings are returned via the StructuredOutput schema enforced by the caller.
+
+Review the PR diff for correctness, scalability, and integration issues.
+
+Axes to cover:
+- Business Logic / AC coverage: for each AC in the list below, mark
+  ✅ met / ⚠️ partial / ❌ missing. Scope creep is also worth flagging.
+  AC_LIST: read key "acList" from CONTEXT_FILE.
+- Scalability: N+1 queries, missing pagination, unbounded in-memory
+  collections, missing rate-limit handling, cron jobs without overlap guard,
+  missing DB indexes for new query patterns.
+- Time/Space Complexity: O(n²) where linear exists, large payloads in memory,
+  sort/dedup on large arrays that could be done at DB level.
+- Integration Contracts: Shopify API misuse, BC API assumptions, webhook
+  idempotency, external API pagination not handled.
+- GraphQL pagination (GQL-1): for every GraphQL query in the diff that uses a
+  nodes connection (`nodes { ... }`):
+  (a) Check that `pageInfo { hasNextPage endCursor }` is present alongside nodes — if missing, Critical.
+  (b) Check that all pages are fetched (a loop or recursion using endCursor) — a single-page fetch is a bug, Critical.
+  (c) Check the page size: must be 250 (Shopify max). If any other size is used without a code comment explaining why, flag as Important.
+  Set `rule: "GQL-1"` on any Critical finding raised under this axis.
+
+Setting rule tags the finding as a house hard rule: it keeps its Critical
+severity and skips adversarial verification. Only set it for a genuine GQL-1
+violation — never to shield an ordinary finding from verification.
+
+CI_STATUS: read key "ciStatus" from the JSON file CONTEXT_FILE.
+SENTRY_SIGNALS: read key "sentrySignals" from CONTEXT_FILE.
+EXISTING_REVIEWS: read key "existingReviews" from CONTEXT_FILE (awareness only — skip findings already raised)
+
+PROJECT_RULES to verify: read key "projectRules" from CONTEXT_FILE.
+
+Diff: read the full unified PR diff from the file DIFF_FILE (absolute path given in your task message). Do NOT run gh pr diff.
+Worktree: WORKTREE_PATH is given in your task message (null in scan mode — diff only).
+
+Rules:
+- Every finding must trace to a + line in the diff.
+- Report file:line — description. No positive observations.
+- `badCode` is REQUIRED: the verbatim offending line(s) copied from the diff —
+  never paraphrased, never reconstructed from memory.
+- `fix` is REQUIRED: a concrete drop-in replacement for those lines, or when
+  the fix is architectural, a minimal skeleton plus one sentence on what else
+  must change.
+- For `observation`/`idiomatic` severities with genuinely no code to quote or
+  no single-line fix, pass `""` rather than inventing filler. Never pass `""`
+  on a `critical`/`important` finding — a finding you cannot quote and cannot
+  fix is a finding you have not proven, so drop it instead.
+- Exception for a missing/partial AC: the defect is what is absent, so quote
+  the closest incomplete added line(s) in `badCode` (the handler that stops
+  short, the branch never written) and put what must be added in `fix`. Do not
+  drop an unmet AC for lack of a quotable line.