@olegkoval/agent-skills 1.69.4 → 1.71.0

package/.github/copilot-instructions.md

@@ -50,6 +50,7 @@ Available reusable prompt files:
 - agent-ops-retro: .github/prompts/agent-ops-retro.prompt.md
 - crash-course: .github/prompts/crash-course.prompt.md
 - wrap-up: .github/prompts/wrap-up.prompt.md
+- team-retrospective: .github/prompts/team-retrospective.prompt.md
 - obsidian-pr-sync: .github/prompts/obsidian-pr-sync.prompt.md
 - obsidian-task-rollover: .github/prompts/obsidian-task-rollover.prompt.md
 - morning-routine: .github/prompts/morning-routine.prompt.md

package/.github/prompts/team-retrospective.prompt.md

@@ -0,0 +1,31 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Collect each task agent’s factual retrospective and safely dismiss the team after successful work."
+---
+
+Use the olko:team-retrospective skill.
+
+# Team retrospective
+
+Run after a multi-agent task is complete and its applicable checks are green,
+before dismissing its agents. Explicit user instructions to retain agents or
+finish early take precedence. Do not spawn agents solely to run this skill.
+
+1. Identify agents, tabs, and sessions owned by this task using the environment's
+   actual inventory and recorded ownership. Preserve other tasks and sessions.
+2. Ask each reachable agent for a concise factual report: what went wrong, failed
+   approaches, tool or coordination problems, resolutions, and unresolved items.
+   Ask them to distinguish direct observation from inference. A clean report may
+   say no issues. Do not request new implementation or speculative findings.
+3. Collect each response, or label it unavailable with the reason. Preserve useful
+   findings and a concise summary in an appropriate task artifact; avoid secrets,
+   unnecessary transcripts, and public disclosure. Report recurring issues and
+   unresolved items to the user. Claims remain reports until independently verified.
+4. Confirm work and required handoffs are preserved. Dismiss the task-owned agents
+   and close only their task-owned tabs or panes when safe; verify the result.
+   Follow the environment's skill and safety rules. Never stop a shared server or
+   close another task's session. Respect explicit instructions to keep agents.
+5. If work is blocked, unfinished, or still active, preserve the agents and report
+   the blocker instead of treating the task as green. If the environment cannot
+   contact or dismiss an agent, report the limitation; never claim it was dismissed.

package/.github/prompts/wrap-up.prompt.md

@@ -30,6 +30,8 @@ Use this as a proportional end-of-task audit. Preserve pre-existing work and do
 - Check the diff and untracked files for keys, tokens, passwords, private keys, connection strings, cookies, personal data, and credentials in logs or examples. Report locations without printing values; recommend environment variables or a secret manager where relevant.
 - Decide from the actual change whether README, architecture or API docs, OpenAPI, CHANGELOG, CONTRIBUTING, `.env.example`, ADRs, or runbooks need an update. Name the exact change needed. Skip documentation for trivial internal changes unless it helps future maintenance.
 
+Before cleanup, when a completed task used a team and its applicable checks are green, invoke `olko:team-retrospective` to collect each agent’s report and safely dismiss task-owned agents. If unavailable, report the limitation; do not claim closeout ran.
+
 ## 4. Prepare safe cleanup
 
 - Propose cleanup commands only. Do not remove any file, branch, or worktree automatically, including generated or temporary files. Never propose deletion of an unknown untracked file, broad directory, or unresolved glob.

package/.kiro/steering/team-retrospective.md

@@ -0,0 +1,30 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+inclusion: manual
+description: "Collect each task agent’s factual retrospective and safely dismiss the team after successful work."
+---
+
+# Team retrospective
+
+Run after a multi-agent task is complete and its applicable checks are green,
+before dismissing its agents. Explicit user instructions to retain agents or
+finish early take precedence. Do not spawn agents solely to run this skill.
+
+1. Identify agents, tabs, and sessions owned by this task using the environment's
+   actual inventory and recorded ownership. Preserve other tasks and sessions.
+2. Ask each reachable agent for a concise factual report: what went wrong, failed
+   approaches, tool or coordination problems, resolutions, and unresolved items.
+   Ask them to distinguish direct observation from inference. A clean report may
+   say no issues. Do not request new implementation or speculative findings.
+3. Collect each response, or label it unavailable with the reason. Preserve useful
+   findings and a concise summary in an appropriate task artifact; avoid secrets,
+   unnecessary transcripts, and public disclosure. Report recurring issues and
+   unresolved items to the user. Claims remain reports until independently verified.
+4. Confirm work and required handoffs are preserved. Dismiss the task-owned agents
+   and close only their task-owned tabs or panes when safe; verify the result.
+   Follow the environment's skill and safety rules. Never stop a shared server or
+   close another task's session. Respect explicit instructions to keep agents.
+5. If work is blocked, unfinished, or still active, preserve the agents and report
+   the blocker instead of treating the task as green. If the environment cannot
+   contact or dismiss an agent, report the limitation; never claim it was dismissed.

package/.kiro/steering/wrap-up.md

@@ -29,6 +29,8 @@ Use this as a proportional end-of-task audit. Preserve pre-existing work and do
 - Check the diff and untracked files for keys, tokens, passwords, private keys, connection strings, cookies, personal data, and credentials in logs or examples. Report locations without printing values; recommend environment variables or a secret manager where relevant.
 - Decide from the actual change whether README, architecture or API docs, OpenAPI, CHANGELOG, CONTRIBUTING, `.env.example`, ADRs, or runbooks need an update. Name the exact change needed. Skip documentation for trivial internal changes unless it helps future maintenance.
 
+Before cleanup, when a completed task used a team and its applicable checks are green, invoke `olko:team-retrospective` to collect each agent’s report and safely dismiss task-owned agents. If unavailable, report the limitation; do not claim closeout ran.
+
 ## 4. Prepare safe cleanup
 
 - Propose cleanup commands only. Do not remove any file, branch, or worktree automatically, including generated or temporary files. Never propose deletion of an unknown untracked file, broad directory, or unresolved glob.

package/.windsurf/rules/team-retrospective.md

@@ -0,0 +1,29 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Collect each task agent’s factual retrospective and safely dismiss the team after successful work."
+---
+
+# Team retrospective
+
+Run after a multi-agent task is complete and its applicable checks are green,
+before dismissing its agents. Explicit user instructions to retain agents or
+finish early take precedence. Do not spawn agents solely to run this skill.
+
+1. Identify agents, tabs, and sessions owned by this task using the environment's
+   actual inventory and recorded ownership. Preserve other tasks and sessions.
+2. Ask each reachable agent for a concise factual report: what went wrong, failed
+   approaches, tool or coordination problems, resolutions, and unresolved items.
+   Ask them to distinguish direct observation from inference. A clean report may
+   say no issues. Do not request new implementation or speculative findings.
+3. Collect each response, or label it unavailable with the reason. Preserve useful
+   findings and a concise summary in an appropriate task artifact; avoid secrets,
+   unnecessary transcripts, and public disclosure. Report recurring issues and
+   unresolved items to the user. Claims remain reports until independently verified.
+4. Confirm work and required handoffs are preserved. Dismiss the task-owned agents
+   and close only their task-owned tabs or panes when safe; verify the result.
+   Follow the environment's skill and safety rules. Never stop a shared server or
+   close another task's session. Respect explicit instructions to keep agents.
+5. If work is blocked, unfinished, or still active, preserve the agents and report
+   the blocker instead of treating the task as green. If the environment cannot
+   contact or dismiss an agent, report the limitation; never claim it was dismissed.

package/.windsurf/rules/wrap-up.md

@@ -28,6 +28,8 @@ Use this as a proportional end-of-task audit. Preserve pre-existing work and do
 - Check the diff and untracked files for keys, tokens, passwords, private keys, connection strings, cookies, personal data, and credentials in logs or examples. Report locations without printing values; recommend environment variables or a secret manager where relevant.
 - Decide from the actual change whether README, architecture or API docs, OpenAPI, CHANGELOG, CONTRIBUTING, `.env.example`, ADRs, or runbooks need an update. Name the exact change needed. Skip documentation for trivial internal changes unless it helps future maintenance.
 
+Before cleanup, when a completed task used a team and its applicable checks are green, invoke `olko:team-retrospective` to collect each agent’s report and safely dismiss task-owned agents. If unavailable, report the limitation; do not claim closeout ran.
+
 ## 4. Prepare safe cleanup
 
 - Propose cleanup commands only. Do not remove any file, branch, or worktree automatically, including generated or temporary files. Never propose deletion of an unknown untracked file, broad directory, or unresolved glob.

package/README.md

@@ -304,6 +304,7 @@ Look back and improve: self-critique, retrospectives, performance review, rapid
 | [self-critique](plugins/olko-reflection/skills/self-critique/SKILL.md) | Adversarially critiques your own last answer: a blind critic agent re-derives and verifies every claim against live sources, the score is computed from a labelled claim ledger, you revise under a ratchet, restate the corrected answer, and turn each caught error into a durable rule with a fire counter | Checking a substantial answer before the user has to |
 | [review-past-performance](plugins/olko-reflection/skills/review-past-performance/SKILL.md) | Pulls 24h of ICM memories, git history, and skill analytics; detects repeated mistakes and slow workflows; proposes 1-3 concrete fixes | Daily self-improvement loop or codifying a repeated workflow |
 | [retro-analysis](plugins/olko-reflection/skills/retro-analysis/SKILL.md) | Produces repository, comparison, and cross-project retrospectives from delivery, code-quality, work-pattern, and trend evidence | The user asks for a retro over shipped work ("run a retrospective", "how did this quarter go", "what did we ship") or a scheduled retro job fires; for agent-operations retros use agent-ops-retro, for a single finished change use wrap-up |
+| [team-retrospective](plugins/olko-reflection/skills/team-retrospective/SKILL.md) | Collects agent reports and safely dismisses a completed team | During wrap-up of a green multi-agent task |
 | [agent-ops-retro](plugins/olko-reflection/skills/agent-ops-retro/SKILL.md) | Retrospective on how the agents themselves are being operated: mines local transcripts and reads the reports other jobs already produce to surface what the human keeps repeating, what the guardrails caught, and where delivery leaked, carrying unactioned findings forward | Checking agent usage, delegation cost, or repeating corrections across sessions rather than shipped code |
 | [crash-course](plugins/olko-reflection/skills/crash-course/SKILL.md) | Expert tutor for rapid, source-grounded learning of any topic: a timed 4-hour sprint plus cheat-sheet, learning-ladder, quiz-me, Feynman, and resource-curation modes | Ramping up on an unfamiliar codebase, project, or concept under time pressure |
 | [wrap-up](plugins/olko-reflection/skills/wrap-up/SKILL.md) | Verifies work against its original objective, checks applicable gates, audits task-owned artifacts, and proposes safe cleanup | A change is believed done and the user says "wrap up", "we are done here", or "clean up after this", or before handing work off; for a retro over repository history use retro-analysis |

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

@@ -470,12 +470,13 @@ Fire both tracks in the same turn.
 At scan depth, collect review guidance without creating a worktree:
 
 ```bash
-LEKKER_RULES_ONLY=1 ${SKILL_ROOT}/scripts/setup-worktree.sh \
+LEKKER_RULES_ONLY=1 LEKKER_BASE_REF=origin/<BASE_BRANCH> \
+  ${SKILL_ROOT}/scripts/setup-worktree.sh \
   <REPO_SLUG> <PR_BRANCH> <scratchpad>/rules.json
 ```
 
 Read `projectRules` from `rules.json` into `context.json`. This archive-only
-mode reads the PR tree and does not run static checks.
+mode fetches the PR base for `baseProjectRules` and does not run static checks.
 
 Run via Bash with `run_in_background`:
 
@@ -687,6 +688,7 @@ Write `<scratchpad>/context.json` with keys:
 {
   "acList":          "<numbered ACs from your issue tracker, or empty>",
   "projectRules":    "<worktree.json or rules.json projectRules + any recalled review patterns appended under '## Recalled patterns'>",
+  "baseProjectRules": "<worktree.json or rules.json baseProjectRules, copied unchanged (no recalled patterns); null when absent>",
   "changedPaths":    "<PR files[].path list, or an exact matching worktree.json changedFiles list>",
   "sentrySignals":   "<monitoring issue summaries, or null>",
   "ciStatus":        "<passing | failing: <names> | pending | N/A>",
@@ -915,6 +917,13 @@ value first). `REVIEW.md` ignore rules never suppress findings in changed paths.
 applies exclusions to agent and lint findings using `changedPaths`; if paths are
 unavailable, keep findings. It never switches off a hard rule from `CLAUDE.md` or the house rules.
 
+**Project rules are hard rules.** A prohibition or obligation in `projectRules`
+(NEVER, MUST, ALWAYS, DO NOT or plain-English equivalent) that a changed line
+violates is raised as Critical with `rule: "PROJECT:<slug>"` and a verbatim
+`ruleQuote`. The verifier runs `scripts/project-rule-findings.mjs`, which drops
+a finding whose quote is not found in `projectRules`; otherwise it takes the
+hard-rule path (anchor and applicability, no runtime challenges).
+
 **Approval standard.** The verdict answers "does this definitely improve the
 codebase's health", not "is this how I would have written it". Perfect code does
 not exist. `✅ LGTM - ship it` is the right call for a change that improves

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/conventions.md

@@ -127,6 +127,9 @@ Use it as a prior, not as a checklist:
 EXISTING_REVIEWS: read key "existingReviews" from CONTEXT_FILE (awareness only, skip findings already raised)
 
 PROJECT_RULES to verify: read key "projectRules" from CONTEXT_FILE.
+A changed line that violates a prohibition or obligation in PROJECT_RULES is a Critical
+finding tagged `rule: "PROJECT:<slug>"` with `ruleQuote` set to the exact rule sentence
+(see PROJECT RULES AS HARD RULES in the task message).
 
 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).

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/implementation.md

@@ -105,6 +105,9 @@ 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.
+A changed line that violates a prohibition or obligation in PROJECT_RULES is a Critical
+finding tagged `rule: "PROJECT:<slug>"` with `ruleQuote` set to the exact rule sentence
+(see PROJECT RULES AS HARD RULES in the task message).
 
 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).

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/quality.md

@@ -72,6 +72,9 @@ Note: awareness only. Do not anchor on prior reviews. Skip findings already
 raised at the same file:line by another reviewer.
 
 PROJECT_RULES to verify: read key "projectRules" from CONTEXT_FILE.
+A changed line that violates a prohibition or obligation in PROJECT_RULES is a Critical
+finding tagged `rule: "PROJECT:<slug>"` with `ruleQuote` set to the exact rule sentence
+(see PROJECT RULES AS HARD RULES in the task message).
 
 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).

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/simplification.md

@@ -56,6 +56,9 @@ actionable: name the move or drop the finding.
 EXISTING_REVIEWS: read key "existingReviews" from CONTEXT_FILE (awareness only, skip findings already raised)
 
 PROJECT_RULES to verify: read key "projectRules" from CONTEXT_FILE.
+A changed line that violates a prohibition or obligation in PROJECT_RULES is a Critical
+finding tagged `rule: "PROJECT:<slug>"` with `ruleQuote` set to the exact rule sentence
+(see PROJECT RULES AS HARD RULES in the task message).
 
 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).

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/test-quality.md

@@ -169,6 +169,9 @@ Return the review summary through these structured fields in addition to
 EXISTING_REVIEWS: read key "existingReviews" from CONTEXT_FILE (awareness only, skip findings already raised)
 
 PROJECT_RULES to verify: read key "projectRules" from CONTEXT_FILE.
+A changed line that violates a prohibition or obligation in PROJECT_RULES is a Critical
+finding tagged `rule: "PROJECT:<slug>"` with `ruleQuote` set to the exact rule sentence
+(see PROJECT RULES AS HARD RULES in the task message).
 Diff: read DIFF_FILE. List every test file/spec
 Worktree: WORKTREE_PATH is given in your task message (null in scan mode, diff only).
 

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/verifier.md

@@ -28,14 +28,28 @@ unless Step 0 validates it through the house hard-rule path.
 
 ## Step 0 -- Hard-rule validation (check this FIRST)
 
-If the FINDING JSON has any non-empty `rule` field, including built-in tags
-such as `TS-1`, `TS-2`, `GQL-1`, or `PR-1`, do NOT run the five adversarial
+If the FINDING JSON has any non-empty `rule` field, do NOT run the five adversarial
 challenges below. They ask
 runtime-failure questions that a standards violation can never answer, and
 answering them honestly would drop a finding that house-rules policy declares
 Critical on standards grounds rather than on runtime behaviour.
 
-Instead run exactly two checks:
+For `rule: "weakens-project-rule"`, use this dedicated path:
+
+1. **Removed-line anchor**: confirm the quoted rule appears on a `-` line in
+   `DIFF_FILE` for the finding's file. Ignore `---` file headers. This anchor is
+   valid for both a deletion and a replacement; do not require a matching `+`
+   line or downgrade the finding because it has no production-code `+` line.
+2. **Base-rule validation**: write the FINDING JSON to a unique temp file and run
+   `node <this prompt's directory>/../../scripts/project-rule-findings.mjs <finding.json> <CONTEXT_FILE>`.
+   The validator requires the exact quote to exist in `baseProjectRules`; a
+   missing base copy or rejected quote fails this check. Do not validate against
+   `projectRules`, which may already reflect the PR's weakened rules.
+
+Both checks pass -> `confirmed` at the finding's Important severity. Either
+check fails -> `dropped`. Do not downgrade a confirmed weakening.
+
+For all other non-empty `rule` tags, run exactly two checks:
 
 1. **Anchor**: the flagged code genuinely appears on a `+` line of
    `DIFF_FILE` (for PR-1, the PR title genuinely lacks a ticket present in
@@ -55,6 +69,17 @@ the rule and quoting the violating snippet. Either check fails -> `dropped`,
 with `reasoning` naming which check failed. There is no `downgraded` outcome
 for a hard rule: it either violates the rule or it does not.
 
+For a `rule` starting with `PROJECT:`, the rule text lives in `baseProjectRules` of
+`CONTEXT_FILE` when that key is a string (the base branch's copy, which the PR cannot
+edit), otherwise in `projectRules`, not in `HOUSE_RULES_FILE`. Write the FINDING JSON to a unique temp file
+(create it with `mktemp`, never a fixed name, because verifiers run in parallel) and run `node <this prompt's directory>/../../scripts/project-rule-findings.mjs <finding.json> <CONTEXT_FILE>`.
+Exit 1 means the quoted rule is not in `projectRules` (or the tag is malformed):
+`dropped`, with that output as `reasoning`. Any other non-zero exit means the validator
+could not run: read that same key yourself and confirm the exact quoted sentence is in it.
+If it is not, `dropped`. If it is, keep the finding at its severity, say in `reasoning` that
+the validator was unavailable, set `validatorUnavailable: true`, and judge applicability as below. On exit 0, judge applicability
+against the quoted rule as the second check.
+
 Then **stop** -- do not continue to Step 1 or the five challenges.
 
 ---

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

@@ -0,0 +1,4 @@
+# Fixture rules
+
+- NEVER call console.log in src/.
+- NEVER mutate function arguments.

package/adapters/claude/olko-github-pr/skills/lekker-review/scripts/fixtures/project-rules/planted.diff

@@ -0,0 +1,9 @@
+diff --git a/src/total.js b/src/total.js
+--- a/src/total.js
++++ b/src/total.js
+@@ -1,3 +1,6 @@
++export function addItem(list, item) {
++  console.log('adding', item)
++  list.push(item)
++  return list
++}

package/adapters/claude/olko-github-pr/skills/lekker-review/scripts/project-rule-findings.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// Validates findings tagged `rule: "PROJECT:<slug>"`.
+//
+// A project's own prohibitions and obligations (CLAUDE.md, AGENTS.md, REVIEW.md)
+// are collected into `projectRules`. A lens that raises one as a hard rule must
+// quote the rule it enforces. A quote that is not in `projectRules` means the
+// model invented the rule, so the finding is rejected instead of being allowed
+// to ride the hard-rule path past the runtime challenges.
+//
+//   node project-rule-findings.mjs <finding.json> <context.json>
+//
+// Exit 0 when valid or when the finding is not a PROJECT rule, 1 when rejected,
+// 2 when the validator itself could not run (usage error, unreadable or malformed input).
+import { readFileSync, realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const TAG_PATTERN = /^PROJECT:[a-z0-9]+(-[a-z0-9]+)*$/
+const MIN_QUOTE_LENGTH = 12
+
+export function isProjectRuleTag(tag) {
+  return typeof tag === 'string' && TAG_PATTERN.test(tag)
+}
+
+// Case, runs of whitespace and markdown emphasis or list markers vary between a
+// rules file and a model's copy of it; the words must not.
+export function normalizeQuote(text) {
+  return String(text ?? '')
+    .replace(/(^|\n)\s{0,3}#{1,6}\s+/g, '$1')
+    .replace(/(^|\n)\s{0,3}>\s?/g, '$1')
+    .replace(/`([^`\n]+)`/g, '$1')
+    .replace(/(^|[\s([{])(\*{1,2}|_{1,2})(\S(?:.*?\S)?)\2(?=$|[\s.,;:!?)}\]])/g, '$1$3')
+    .replace(/^\s*[-+]\s+/gm, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase()
+}
+
+const RECALLED_PATTERNS_HEADING = /^\s{0,3}#{1,6}\s+recalled patterns\s*$/gim
+
+// Recalled patterns are memory, not the project's rules, so nothing below the last such heading is a valid quote source.
+// SKILL.md appends that heading at the end; an earlier one inside a rules file must not drop the rules after it.
+export function stripRecalledPatterns(text) {
+  const source = String(text ?? '')
+  let cut = -1
+  for (const match of source.matchAll(RECALLED_PATTERNS_HEADING)) cut = match.index
+  return cut === -1 ? source : source.slice(0, cut)
+}
+
+export function quoteAppearsIn(quote, projectRules) {
+  const needle = normalizeQuote(quote)
+  if (!needle) return false
+  const rules = stripRecalledPatterns(projectRules)
+  if (needle.length >= MIN_QUOTE_LENGTH && normalizeQuote(rules).includes(needle)) return true
+  return rules.split(/\r?\n/).some(line => normalizeQuote(line) === needle)
+}
+
+export function validateProjectRuleFinding(finding, projectRules) {
+  const tag = finding?.rule
+  if (typeof tag !== 'string' || !tag.startsWith('PROJECT:')) {
+    return { ok: true, reason: 'not a PROJECT rule' }
+  }
+  if (!isProjectRuleTag(tag)) {
+    return { ok: false, reason: `malformed tag "${tag}": expected PROJECT:<kebab-case-slug>` }
+  }
+  if (typeof finding.ruleQuote !== 'string' || finding.ruleQuote.trim() === '') {
+    return { ok: false, reason: 'missing ruleQuote: quote the project rule verbatim' }
+  }
+  if (!quoteAppearsIn(finding.ruleQuote, projectRules)) {
+    return { ok: false, reason: 'ruleQuote not found in projectRules' }
+  }
+  return { ok: true, reason: 'quote found in projectRules' }
+}
+
+export function validateWeakenedProjectRuleFinding(finding, baseProjectRules) {
+  if (finding?.rule !== 'weakens-project-rule') {
+    return { ok: true, reason: 'not a weakened project rule' }
+  }
+  if (typeof baseProjectRules !== 'string') {
+    return { ok: false, reason: 'baseProjectRules unavailable' }
+  }
+  if (typeof finding.ruleQuote !== 'string' || finding.ruleQuote.trim() === '') {
+    return { ok: false, reason: 'missing ruleQuote: quote the removed project rule' }
+  }
+  if (!quoteAppearsIn(finding.ruleQuote, baseProjectRules)) {
+    return { ok: false, reason: 'ruleQuote not found in baseProjectRules' }
+  }
+  return { ok: true, reason: 'quote found in baseProjectRules' }
+}
+
+function main(argv) {
+  const [findingPath, contextPath] = argv
+  if (!findingPath || !contextPath) {
+    console.error('usage: project-rule-findings.mjs <finding.json> <context.json>')
+    return 2
+  }
+  try {
+    const finding = JSON.parse(readFileSync(findingPath, 'utf8'))
+    const context = JSON.parse(readFileSync(contextPath, 'utf8'))
+    if (finding?.rule === 'weakens-project-rule') {
+      const result = validateWeakenedProjectRuleFinding(finding, context.baseProjectRules)
+      console.log(JSON.stringify(result))
+      return result.ok ? 0 : 1
+    }
+    // Base-branch rules are authoritative; PR-tree rules only when no base was resolved.
+    const authoritative = typeof context.baseProjectRules === 'string' ? context.baseProjectRules : context.projectRules
+    const result = validateProjectRuleFinding(finding, authoritative)
+    console.log(JSON.stringify(result))
+    return result.ok ? 0 : 1
+  } catch (error) {
+    // Exit 1 is reserved for "rejected"; a tooling failure must not read as one.
+    console.error(`project-rule-findings: unavailable: ${error.message}`)
+    return 2
+  }
+}
+
+function isMain() {
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)) } catch { return false }
+}
+
+if (isMain()) {
+  process.exit(main(process.argv.slice(2)))
+}

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

@@ -696,5 +696,165 @@ check('ledger: proven prover adds one', countProveAttempt(2, { attempted: true,
 const bareWrites = src.split('\n').filter(l => /proveAttemptCount\s*(\+\+|\+=|=[^=])/.test(l) && !/countProveAttempt\(|let proveAttemptCount/.test(l))
 check('the attempt count is written only through countProveAttempt', bareWrites, [])
 
+console.log('\nproject rules: PROJECT:<slug> findings must quote a rule that exists')
+const { spawnSync: spawnPr } = await import('node:child_process')
+const { mkdtempSync: mkPr, cpSync: cpPr, readFileSync: rdPr, rmSync: rmPr, symlinkSync: syPr, writeFileSync: wfPr } = await import('node:fs')
+const { tmpdir: tmpPr } = await import('node:os')
+const { validateProjectRuleFinding, validateWeakenedProjectRuleFinding, isProjectRuleTag } =
+  await import('./project-rule-findings.mjs')
+
+const fixtureDir = join(SKILL, 'scripts', 'fixtures', 'project-rules')
+const prRepo = mkPr(join(tmpPr(), 'lekker-pr-'))
+cpPr(join(fixtureDir, 'CLAUDE.md'), join(prRepo, 'CLAUDE.md'))
+const prGit = (...a) => spawnPr('git', ['-C', prRepo, '-c', 'user.name=t', '-c', 'user.email=t@t', ...a], { encoding: 'utf8' })
+prGit('init', '-q', '-b', 'main'); prGit('add', '.'); prGit('commit', '-qm', 'rules')
+const prOut = join(prRepo, 'rules.json')
+const collected = spawnPr('bash', [join(SKILL, 'scripts', 'setup-worktree.sh'), 'o/r', 'main', prOut], {
+  encoding: 'utf8', env: { ...process.env, LEKKER_RULES_ONLY: '1', LEKKER_LOCAL_REPO: prRepo },
+})
+const planted = collected.status === 0 ? JSON.parse(rdPr(prOut, 'utf8')).projectRules : ''
+check('rules collection exits 0 on the planted fixture', collected.status, 0)
+check('projectRules carries both planted rules',
+  [planted.includes('NEVER call console.log in src/.'), planted.includes('NEVER mutate function arguments.')], [true, true])
+rmPr(prRepo, { recursive: true, force: true })
+
+const prFinding = (rule, ruleQuote) => ({ rule, ruleQuote, file: 'src/total.js', line: 2, title: 't' })
+check('accepts PROJECT:no-console-log with a matching quote',
+  validateProjectRuleFinding(prFinding('PROJECT:no-console-log', 'NEVER call console.log in src/.'), planted).ok, true)
+check('accepts a quote that differs only in case and spacing',
+  validateProjectRuleFinding(prFinding('PROJECT:no-mutation', 'never  mutate   function arguments'), planted).ok, true)
+check('accepts exact short project rules',
+  validateProjectRuleFinding(prFinding('PROJECT:no-eval', 'NEVER eval.'), '- NEVER eval.').ok, true)
+check('rejects altered identifiers in project rule quotes',
+  validateProjectRuleFinding(prFinding('PROJECT:no-unsafe', 'NEVER call unsafe().'), 'NEVER call `_unsafe()`.').ok, false)
+check('rejects altered operators in project rule quotes',
+  validateProjectRuleFinding(prFinding('PROJECT:nonnegative', 'MUST validate n = 0.'), 'MUST validate n >= 0.').ok, false)
+check('rejects a quote that is absent from projectRules',
+  validateProjectRuleFinding(prFinding('PROJECT:no-eval', 'NEVER call eval anywhere in the codebase'), planted).ok, false)
+check('rejects a PROJECT tag with no quote',
+  validateProjectRuleFinding({ rule: 'PROJECT:no-console-log' }, planted).ok, false)
+const weakenedFinding = prFinding('weakens-project-rule', 'NEVER call console.log in src/.')
+check('accepts a weakened rule quoted from baseProjectRules',
+  validateWeakenedProjectRuleFinding(weakenedFinding, planted).ok, true)
+check('rejects a weakened rule quote absent from baseProjectRules',
+  validateWeakenedProjectRuleFinding(weakenedFinding, 'NEVER call eval.').ok, false)
+check('rejects a weakened rule when baseProjectRules is unavailable',
+  validateWeakenedProjectRuleFinding(weakenedFinding, undefined).ok, false)
+check('rejects a weakened rule with no quote',
+  validateWeakenedProjectRuleFinding({ rule: 'weakens-project-rule' }, planted).ok, false)
+const verifierInstructions = rdPr(join(SKILL, 'references', 'agents', 'verifier.md'), 'utf8')
+check('verifier has a dedicated weakened-project-rule path',
+  verifierInstructions.includes('For `rule: "weakens-project-rule"`, use this dedicated path:'), true)
+check('verifier accepts deleted and replacement-line anchors',
+  verifierInstructions.includes('valid for both a deletion and a replacement'), true)
+check('verifier confirms valid weakened rules at Important severity',
+  verifierInstructions.includes("`confirmed` at the finding's Important severity"), true)
+check('rejects a malformed slug', validateProjectRuleFinding(prFinding('PROJECT:No Console', 'NEVER call console.log in src/.'), planted).ok, false)
+check('a built-in tag is left to the house-rule path', validateProjectRuleFinding({ rule: 'TS-1' }, planted).ok, true)
+const withRecalled = 'NEVER eval anywhere in src.\n## Recalled patterns\nNEVER call console.log in tests.'
+check('accepts a quote above the recalled patterns heading',
+  validateProjectRuleFinding(prFinding('PROJECT:no-eval', 'NEVER eval anywhere in src.'), withRecalled).ok, true)
+check('rejects a quote that appears only under recalled patterns',
+  validateProjectRuleFinding(prFinding('PROJECT:no-console-log', 'NEVER call console.log in tests.'), withRecalled).ok, false)
+const twoRecalled = 'NEVER eval anywhere in src.\n## Recalled patterns\nNEVER use var in src.\n## Recalled patterns\nNEVER call console.log in tests.'
+check('accepts a quote between two recalled patterns headings',
+  validateProjectRuleFinding(prFinding('PROJECT:no-var', 'NEVER use var in src.'), twoRecalled).ok, true)
+check('rejects a quote after the last recalled patterns heading when the heading appears twice',
+  validateProjectRuleFinding(prFinding('PROJECT:no-console-log', 'NEVER call console.log in tests.'), twoRecalled).ok, false)
+console.log('\nworkflow: a house-rule finding and a PROJECT finding on one line are never one issue')
+const houseF = { file: 'src/total.js', line: 2, title: 'Missing null check on total', rule: 'TS-1' }
+const projectF = { file: 'src/total.js', line: 2, title: 'Missing null check on total', rule: 'PROJECT:no-null-total', ruleQuote: 'NEVER skip the null check on total.' }
+check('a house-rule finding and a PROJECT finding with similar titles are not sameIssue', sameIssue(houseF, projectF), false)
+check('isProjectRuleTag accepts a kebab slug and rejects an empty one',
+  [isProjectRuleTag('PROJECT:a-b'), isProjectRuleTag('PROJECT:')], [true, false])
+check('a PROJECT tag is a hard rule', isHardRule({ rule: 'PROJECT:no-console-log' }), true)
+const quoteA = { file: 'src/total.js', line: 2, title: 'Missing null check on total', rule: 'PROJECT:no-null-total', ruleQuote: 'NEVER skip the null check on total.' }
+const quoteB = { ...quoteA, ruleQuote: 'ALWAYS validate total before use.' }
+check('two different quotes of one PROJECT rule are not sameIssue', sameIssue(quoteA, quoteB), false)
+check('the same quote of one PROJECT rule is still sameIssue', sameIssue(quoteA, { ...quoteA }), true)
+
+// Prompt guard: every lens that reads projectRules is told to raise the tag.
+const lensFiles = ['quality', 'implementation', 'simplification', 'conventions', 'test-quality']
+check('every lens file that reads projectRules carries the PROJECT instruction',
+  lensFiles.filter(n => {
+    const t = rdPr(join(SKILL, 'references', 'agents', `${n}.md`), 'utf8')
+    return t.includes('"projectRules"') && !t.includes('PROJECT:<slug>')
+  }), [])
+// Behavioural: lift the real reviewPrompt and build prompts with it. Removing the
+// append in reviewPrompt makes the listed-lens check fail.
+function liftBlock(name) {
+  const m = new RegExp(`^const ${name} = [\\s\\S]*?\\n\\n`, 'm').exec(src)
+  if (!m) throw new Error(`selftest: const ${name} not found in workflow.js`)
+  return m[0]
+}
+const buildPrompt = new Function(
+  'dim', 'SUPPRESSED', 'prevSha',
+  [liftBlock('PROJECT_RULE_DIMENSIONS'), liftBlock('PROJECT_RULE_INSTRUCTION'), liftConst('BUG_CLASS_INSTRUCTION'),
+    `const targetMetadata = '{}', promptDir = 'p', repoSlug = 'o/r', prNumber = 1, prUrl = 'u',
+       diffFile = 'd', contextFile = 'c', wtDisplay = 'w'`,
+    lift('reviewPrompt'), 'return reviewPrompt(dim)'].join('\n'),
+)
+const promptFor = key => buildPrompt({ key, file: `${key}.md` }, [], null)
+check('a listed lens prompt carries the PROJECT instruction',
+  lensFiles.map(n => promptFor(n).includes('"PROJECT:<short-kebab-slug>"')), lensFiles.map(() => true))
+check('an unlisted lens prompt does not', promptFor('deps').includes('PROJECT:<short-kebab-slug>'), false)
+
+console.log('\nproject rules: dedup keeps the tag and its quote together')
+const { dedup: dedupPr } = new Function(preamble + '\nreturn { dedup }')()
+const plainF = { file: 'src/a.js', line: 2, severity: 'important', title: 'console.log left in src', bugClass: 'console-log', description: 'x', badCode: 'console.log(1)', fix: 'f', otherInstances: [] }
+const taggedF = { ...plainF, severity: 'critical', rule: 'PROJECT:no-console-log', ruleQuote: 'NEVER call console.log in src/.' }
+const taggedWithoutQuote = { ...taggedF }
+delete taggedWithoutQuote.ruleQuote
+for (const [label, pair] of [['plain first', [plainF, taggedF]], ['tagged first', [taggedF, plainF]]]) {
+  const [m] = dedupPr(pair)
+  check(`merge keeps rule and ruleQuote (${label})`, [m.rule, m.ruleQuote], ['PROJECT:no-console-log', 'NEVER call console.log in src/.'])
+}
+const [mergedQuote] = dedupPr([taggedWithoutQuote, taggedF])
+check('merge fills missing quote for the same project rule',
+  [mergedQuote.rule, mergedQuote.ruleQuote], ['PROJECT:no-console-log', 'NEVER call console.log in src/.'])
+
+const strayQuote = { ...plainF, ruleQuote: 'stale quote that belongs to no rule' }
+const [mergedStray] = dedupPr([strayQuote, taggedF])
+check('a stray quote on an untagged side does not survive the merge',
+  [mergedStray.rule, mergedStray.ruleQuote], ['PROJECT:no-console-log', 'NEVER call console.log in src/.'])
+const [mergedLate] = dedupPr([{ ...plainF, rule: 'PROJECT:no-console-log' }, taggedF])
+check('a quote from a later finding fills a quote-less same rule', mergedLate.ruleQuote, 'NEVER call console.log in src/.')
+const otherRule = { ...taggedF, rule: 'PROJECT:no-mutation', ruleQuote: 'NEVER mutate function arguments.' }
+check('two different PROJECT rules stay separate through dedup', dedupPr([taggedF, otherRule]).length, 2)
+const [mergedNoQuote] = dedupPr([strayQuote, { ...taggedF, ruleQuote: undefined }])
+check('a tagged side without a quote leaves no stray quote behind', mergedNoQuote.ruleQuote, undefined)
+
+console.log('\nproject rules: validator crash is exit 2, rejection is exit 1')
+const crashDir = mkPr(join(tmpPr(), 'lekker-crash-'))
+const okCtx = join(crashDir, 'ctx.json'), badJson = join(crashDir, 'bad.json'), fnd = join(crashDir, 'f.json')
+wfPr(okCtx, JSON.stringify({ projectRules: 'NEVER call console.log in src/.' }))
+wfPr(badJson, '{not json')
+wfPr(fnd, JSON.stringify({ rule: 'PROJECT:no-console-log', ruleQuote: 'NEVER call console.log in src/.' }))
+const runV = (f, c) => spawnPr('node', [join(SKILL, 'scripts', 'project-rule-findings.mjs'), f, c], { encoding: 'utf8' }).status
+check('exit 0 on a valid finding', runV(fnd, okCtx), 0)
+// A PR that deletes the rule must not make its own violation pass: base rules win.
+const spoofCtx = join(crashDir, 'spoof.json')
+wfPr(spoofCtx, JSON.stringify({ projectRules: 'nothing here', baseProjectRules: 'NEVER call console.log in src/.' }))
+check('quote found in base rules is accepted even when the PR tree dropped it', runV(fnd, spoofCtx), 0)
+const addedCtx = join(crashDir, 'added.json')
+wfPr(addedCtx, JSON.stringify({ projectRules: 'NEVER call console.log in src/.', baseProjectRules: '' }))
+check('a rule only the PR tree contains is rejected when base rules exist', runV(fnd, addedCtx), 1)
+const weakenedFile = join(crashDir, 'weakened.json')
+wfPr(weakenedFile, JSON.stringify(weakenedFinding))
+check('validator accepts a weakened-rule quote found in baseProjectRules',
+  runV(weakenedFile, spoofCtx), 0)
+check('validator rejects a weakened-rule quote found only in projectRules',
+  runV(weakenedFile, addedCtx), 1)
+wfPr(join(crashDir, 'rej.json'), JSON.stringify({ rule: 'PROJECT:no-eval', ruleQuote: 'NEVER call eval anywhere in code' }))
+check('exit 1 on a rejected finding', runV(join(crashDir, 'rej.json'), okCtx), 1)
+const symlinkValidator = join(crashDir, 'project-rule-findings.mjs')
+syPr(join(SKILL, 'scripts', 'project-rule-findings.mjs'), symlinkValidator)
+check('exit 1 on a rejected finding through a symlink',
+  spawnPr('node', [symlinkValidator, join(crashDir, 'rej.json'), okCtx], { encoding: 'utf8' }).status, 1)
+check('exit 2 on a missing context file', runV(fnd, join(crashDir, 'nope.json')), 2)
+check('exit 2 on a malformed context file', runV(fnd, badJson), 2)
+check('exit 2 on a malformed finding file', runV(badJson, okCtx), 2)
+rmPr(crashDir, { recursive: true, force: true })
+
 console.log(failed === 0 ? '\nall checks passed\n' : `\n${failed} check(s) FAILED\n`)
 process.exit(failed === 0 ? 0 : 1)