@olegkoval/agent-skills 1.69.4 → 1.71.0

package/plugins/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/plugins/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)

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

@@ -134,6 +134,20 @@ collect_project_rules() {
         -not -path '*/node_modules/*' 2>/dev/null | sort)
 }
 
+# Hard rules must come from a tree the PR author does not control: a PR that
+# deletes a rule and then breaks it would otherwise leave nothing to enforce.
+collect_project_rules_at_ref() {
+    local repo="$1" ref="$2" dir status=0
+    dir="$(mktemp -d "/tmp/lekker-base-rules-XXXXXX")"
+    if git -C "$repo" archive "$ref" 2>/dev/null | tar -x -C "$dir" 2>/dev/null; then
+        collect_project_rules "$dir"
+    else
+        status=1
+    fi
+    rm -rf "$dir"
+    return "$status"
+}
+
 # Scan depth needs PR-authored review guidance but skips expensive worktree
 # setup. Read the PR tree from an archive so no Git worktree or checkout is made.
 if [[ "${LEKKER_RULES_ONLY:-}" == "1" ]]; then
@@ -149,14 +163,40 @@ if [[ "${LEKKER_RULES_ONLY:-}" == "1" ]]; then
             exit 1
         fi
     fi
+    if [[ -n "${LEKKER_BASE_REF:-}" ]]; then
+        if [[ -z "$LOCAL_REPO" && "$LEKKER_BASE_REF" == origin/* ]]; then
+            BASE_BRANCH="${LEKKER_BASE_REF#origin/}"
+            if ! git -C "$REPO_ROOT" fetch origin \
+                "+refs/heads/${BASE_BRANCH}:refs/remotes/origin/${BASE_BRANCH}" 2>/dev/null; then
+                printf 'ERROR: could not fetch base ref %s for rules-only scan\n' "$LEKKER_BASE_REF" >&2
+                exit 1
+            fi
+        fi
+        if ! git -C "$REPO_ROOT" rev-parse --verify -q "${LEKKER_BASE_REF}^{commit}" >/dev/null; then
+            printf 'ERROR: base ref %s does not resolve for rules-only scan\n' "$LEKKER_BASE_REF" >&2
+            exit 1
+        fi
+    fi
     RULES_SOURCE="/tmp/lekker-rules-source-$$"
     mkdir -p "$RULES_SOURCE"
     git -C "$REPO_ROOT" archive "$RULES_REF" | tar -x -C "$RULES_SOURCE"
     PROJECT_RULES="$(collect_project_rules "$RULES_SOURCE")"
-    python3 - "$OUT_JSON" "$PROJECT_RULES" <<'PYEOF'
+    BASE_PROJECT_RULES=""
+    HAVE_BASE_RULES=0
+    if [[ -n "${LEKKER_BASE_REF:-}" ]]; then
+        if BASE_PROJECT_RULES="$(collect_project_rules_at_ref "$REPO_ROOT" "$LEKKER_BASE_REF")"; then
+            HAVE_BASE_RULES=1
+        else
+            BASE_PROJECT_RULES=""
+            NOTES="${NOTES}base-rules-unavailable;"
+        fi
+    fi
+    python3 - "$OUT_JSON" "$PROJECT_RULES" "$BASE_PROJECT_RULES" "$HAVE_BASE_RULES" <<'PYEOF'
 import json, sys
+out = {"projectRules": sys.argv[2]}
+out["baseProjectRules"] = sys.argv[3] if sys.argv[4] == "1" else None
 with open(sys.argv[1], "w") as f:
-    json.dump({"projectRules": sys.argv[2]}, f, indent=2)
+    json.dump(out, f, indent=2)
 PYEOF
     rm -rf "$RULES_SOURCE"
     printf 'OK %s\n' "$OUT_JSON"
@@ -475,6 +515,20 @@ PROJECT_RULES_FILE="/tmp/lekker-rules-$$.txt"
 printf '' > "$PROJECT_RULES_FILE"
 collect_project_rules "$WORKTREE_PATH" > "$PROJECT_RULES_FILE"
 
+BASE_RULES_FILE="/tmp/lekker-base-rules-$$.txt"
+BASE_RULES_STATE="absent"
+printf '' > "$BASE_RULES_FILE"
+if [[ -n "$MERGE_BASE_NOTE" && "$MERGE_BASE_NOTE" != "unknown" ]] \
+    && git -C "$REPO_ROOT" rev-parse --verify -q "${MERGE_BASE_NOTE}^{commit}" >/dev/null; then
+    if collect_project_rules_at_ref "$REPO_ROOT" "$MERGE_BASE_NOTE" > "$BASE_RULES_FILE"; then
+        BASE_RULES_STATE="present"
+    else
+        NOTES="${NOTES}base-rules-unavailable;"
+    fi
+else
+    NOTES="${NOTES}base-rules-unavailable;"
+fi
+
 # ---------------------------------------------------------------------------
 # 6. HEAD SHA
 # ---------------------------------------------------------------------------
@@ -518,14 +572,17 @@ python3 - \
     "$DEPS_INSTALL_FILE" \
     "$ESLINT_JSON_FILE" \
     "$TEST_RUNNER_JSON" \
-    "$OUT_JSON" <<'PYEOF'
+    "$OUT_JSON" \
+    "$BASE_RULES_FILE" \
+    "$BASE_RULES_STATE" <<'PYEOF'
 import json, sys, os
 
 (worktree_path, repo_root, head_sha, head_sha_short,
  tsc_file, eslint_file, rules_file, delta_file, notes,
  changed_files_file, base_ref_val, eslint_scope_file,
  tsc_changed_file, tsc_count_file, merge_base_val,
- deps_install_file, eslint_json_file, test_runner_json, out_json) = sys.argv[1:20]
+ deps_install_file, eslint_json_file, test_runner_json, out_json,
+ base_rules_file, base_rules_state) = sys.argv[1:22]
 
 def parse_runner(raw):
     try:
@@ -581,6 +638,7 @@ data = {
     "tscTail":        read_file(tsc_file),
     "eslintTail":     read_file(eslint_file),
     "projectRules":   read_file(rules_file),
+    "baseProjectRules": read_file(base_rules_file) if base_rules_state == "present" else None,
     "deltaFile":      None if delta_file == "null" else delta_file,
     "notes":          notes,
     "changedFiles":   changed_files,
@@ -598,7 +656,7 @@ data = {
     "eslintJson":     eslint_json_file if file_has_content(eslint_json_file) else None,
 }
 
-for p in (tsc_file, eslint_file, rules_file, changed_files_file,
+for p in (tsc_file, eslint_file, rules_file, base_rules_file, changed_files_file,
           eslint_scope_file, tsc_changed_file, tsc_count_file,
           deps_install_file):
     try:

package/plugins/olko-github-pr/skills/lekker-review/workflow.js

@@ -33,6 +33,7 @@ const FINDINGS_ARRAY_SCHEMA = {
     anyOf: [
       { properties: { severity: { enum: ['observation', 'idiomatic'] } } },
       { required: ['boundary'] },
+      { required: ['rule'], properties: { rule: { pattern: '^(PROJECT:[a-z0-9]+(-[a-z0-9]+)*|weakens-project-rule)$' } } },
     ],
     properties: {
       file:        { type: 'string' },
@@ -44,6 +45,8 @@ const FINDINGS_ARRAY_SCHEMA = {
       fix:         { type: 'string' },
       precedent:   { type: 'string' },
       rule:        { type: 'string', minLength: 1, pattern: '\\S' },
+      // Verbatim project rule a PROJECT:<slug> finding enforces.
+      ruleQuote:   { type: 'string' },
       boundary:    BOUNDARY_SCHEMA,
       // Short kebab-case slug naming the class of bug ("missing-null-check").
       bugClass:    { type: 'string', minLength: 1, pattern: '^[a-z0-9]+(-[a-z0-9]+)*$' },
@@ -107,6 +110,8 @@ const VERDICT_SCHEMA = {
     verdict:     { enum: ['confirmed', 'downgraded', 'dropped'] },
     newSeverity: { enum: ['important', 'observation'] },
     reasoning:   { type: 'string' },
+    // True when the PROJECT-rule validator could not run (exit other than 0 or 1).
+    validatorUnavailable: { type: 'boolean' },
   },
 }
 
@@ -162,6 +167,23 @@ function titleTokens(title) {
 }
 
 function sameIssue(a, b) {
+  // Lens-generated slugs can differ even when they identify the same project rule.
+  const sameProjectQuote = typeof a.rule === 'string' && a.rule.startsWith('PROJECT:')
+    && typeof b.rule === 'string' && b.rule.startsWith('PROJECT:')
+    && typeof a.ruleQuote === 'string' && a.ruleQuote.trim() !== ''
+    && a.ruleQuote === b.ruleQuote
+  if (typeof a.rule === 'string' && typeof b.rule === 'string' && a.rule !== b.rule
+      && (a.rule.startsWith('PROJECT:') || b.rule.startsWith('PROJECT:'))
+      && !sameProjectQuote) {
+    return false
+  }
+  // Two quotes of one PROJECT rule that differ are two different rule passages, not one issue.
+  if (typeof a.rule === 'string' && a.rule === b.rule && a.rule.startsWith('PROJECT:')
+      && typeof a.ruleQuote === 'string' && a.ruleQuote.trim() !== ''
+      && typeof b.ruleQuote === 'string' && b.ruleQuote.trim() !== ''
+      && a.ruleQuote !== b.ruleQuote) {
+    return false
+  }
   // Merging two classes would send one class's instances to the other's fix.
   if (a.bugClass && b.bugClass && a.bugClass !== b.bugClass) {
     return false
@@ -182,6 +204,22 @@ const BUG_CLASS_INSTRUCTION = `BUG CLASS: give every finding a "bugClass" (short
   + ` hit, search the whole diff for the same pattern and list every other place as`
   + ` "file:line" (empty array when there is none). Report the class, not just the first hit.`
 
+const PROJECT_RULE_DIMENSIONS = ['quality', 'implementation', 'simplification', 'conventions', 'test-quality',
+  'triage-quality', 'triage-logic']
+
+const PROJECT_RULE_INSTRUCTION = `PROJECT RULES AS HARD RULES: read "projectRules" from CONTEXT_FILE.`
+  + ` When a changed line violates a project rule written as a prohibition or an obligation`
+  + ` (NEVER, MUST, MUST NOT, ALWAYS, DO NOT, or a plain-English equivalent), raise a Critical`
+  + ` finding with "rule" set to "PROJECT:<short-kebab-slug>", "ruleQuote" set to the exact`
+  + ` sentence from the rules (use "baseProjectRules" when it is a string: it is the base`
+  + ` branch's copy, which the PR author cannot edit; otherwise "projectRules"), and file:line`
+  + ` on the violating line. When the diff deletes or weakens a rule line that is in`
+  + ` baseProjectRules, raise an Important finding with rule "weakens-project-rule" quoting`
+  + ` the removed line. One finding per rule,`
+  + ` with every other violating site in "otherInstances". Never quote a rule that is not in`
+  + ` the authoritative source ("baseProjectRules" when it is a string, otherwise "projectRules"). Preferences and suggestions are not hard rules: report them as ordinary`
+  + ` findings. A REVIEW.md ignore entry narrows where you look, it never disables a rule.`
+
 const BUG_CLASS_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/
 const INSTANCE_PATTERN = new RegExp(INSTANCE_PATTERN_SOURCE)
 
@@ -234,6 +272,14 @@ function mergeFindings(a, b) {
 
   if (!merged.rule && b.rule) {
     merged.rule = b.rule
+    if (Object.prototype.hasOwnProperty.call(b, 'ruleQuote')) {
+      merged.ruleQuote = b.ruleQuote
+    } else {
+      delete merged.ruleQuote
+    }
+  } else if (merged.rule && merged.rule === b.rule && !merged.ruleQuote
+      && typeof b.ruleQuote === 'string' && b.ruleQuote.trim()) {
+    merged.ruleQuote = b.ruleQuote
   }
 
   const agreedBy = []
@@ -547,7 +593,7 @@ if (Number(cycle) >= RETHINK_CYCLE) {
     recurringClasses: Array.isArray(recurringClasses) ? recurringClasses : [],
     findings: [],
     preExisting: [],
-    droppedCount: 0, downgradedCount: 0, hardRuleCount: 0, agentCount: 0,
+    droppedCount: 0, downgradedCount: 0, hardRuleCount: 0, validatorUnavailableCount: 0, agentCount: 0,
     proveAttemptCount: 0, provenCount: 0, suppressedCount: 0,
     outputTokens: 0, turnTokensTotal: budget.spent(),
     engine: ENGINE,
@@ -562,6 +608,7 @@ const budgetAtStart = budget.spent()
   let droppedCount = 0
   let downgradedCount = 0
   let hardRuleCount = 0
+  let validatorUnavailableCount = 0
   let provenCount = 0
   let suppressedCount = 0
   let proveAttemptCount = 0
@@ -613,6 +660,10 @@ const budgetAtStart = budget.spent()
 
     prompt += ' ' + BUG_CLASS_INSTRUCTION
 
+    if (PROJECT_RULE_DIMENSIONS.includes(dim.key)) {
+      prompt += ' ' + PROJECT_RULE_INSTRUCTION
+    }
+
     // The deterministic lint pre-flight has already collected every rule the
     // repo's own eslint config fires on this diff, and those are exactly the
     // comments the bot reviewers bill for. An agent re-reporting them costs a
@@ -650,7 +701,7 @@ const budgetAtStart = budget.spent()
       `FINDING (JSON): ${JSON.stringify(finding)}.`,
       `DIFF_FILE=${diffFile}, CONTEXT_FILE=${contextFile}, WORKTREE_PATH=${wtDisplay}.`,
       `HOUSE_RULES_FILE: read key "houseRulesFile" from CONTEXT_FILE, then read that exact path before validating a hard rule.`,
-      `Default to dropping when uncertain.`,
+      `Default to dropping when uncertain, except when the PROJECT-rule validator was unavailable: then check by hand that the exact quote appears in baseProjectRules when it is a string, otherwise projectRules (drop if it does not), keep the finding only if it does, set validatorUnavailable true, and judge applicability.`,
     ].join(' ')
   }
 
@@ -708,6 +759,9 @@ const budgetAtStart = budget.spent()
   // A model verdict cannot replace the required production boundary map.
   function enforceBoundary(finding) {
     if (!shouldVerify(finding, depth)) return finding
+    // A project rule or a weakened project rule is violated by the line itself; it needs no production entry point.
+    if (typeof finding.rule === 'string'
+        && (finding.rule.startsWith('PROJECT:') || finding.rule === 'weakens-project-rule')) return finding
     const boundary = finding.boundary
     const hasText = function(value) {
       return typeof value === 'string' && value.trim().length > 0
@@ -764,6 +818,11 @@ const budgetAtStart = budget.spent()
           return kept
         }
 
+        if (verdict.validatorUnavailable === true) {
+          validatorUnavailableCount++
+          log(`PROJECT-rule validator unavailable for ${finding.file}:${finding.line}; ${verdict.verdict === 'dropped' ? 'finding dropped' : 'finding kept'}`)
+        }
+
         if (verdict.verdict === 'dropped') {
           droppedCount++
           return null
@@ -1087,6 +1146,7 @@ const budgetAtStart = budget.spent()
     droppedCount,
     downgradedCount,
     hardRuleCount,
+    validatorUnavailableCount,
     agentCount,
     proveAttemptCount,
     provenCount,

package/plugins/olko-obsidian/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-obsidian",
   "description": "Keep an Obsidian vault in sync with work: PR sync, task rollover, morning routine.",
-  "version": "1.69.4",
+  "version": "1.71.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-product/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-product",
   "description": "Take a product idea to a shippable build: MVP passes, full-stack scaffolds, UX/UI quality loops, launch plans.",
-  "version": "1.69.4",
+  "version": "1.71.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-reflection/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-reflection",
   "description": "Look back and improve: self-critique, retrospectives, performance review, rapid learning.",
-  "version": "1.69.4",
+  "version": "1.71.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-reflection/skills/team-retrospective/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: team-retrospective
+description: Collect a factual retrospective from each task-owned agent and safely dismiss the team after successful work. Use during wrap-up of a completed, green multi-agent task or when explicitly requested.
+license: MIT
+compatibility: Codex, Claude Code, and other agent environments with delegation controls.
+metadata:
+  author: Oleg Koval
+  tags:
+    - agents
+    - retrospective
+    - delegation
+    - cleanup
+---
+
+# 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/plugins/olko-reflection/skills/wrap-up/SKILL.md

@@ -42,6 +42,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/plugins/olko-release/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-release",
   "description": "Ship a release: semantic-release setup, changelogs, store listing copy, release-day routine.",
-  "version": "1.69.4",
+  "version": "1.71.0",
   "author": {
     "name": "Oleg Koval"
   },