@codyswann/lisa 2.240.0 → 2.242.0

package/plugins/lisa-cursor/hooks/threshold-ratchet-families.mjs

@@ -0,0 +1,295 @@
+/**
+ * Threshold ratchet — watched file families and value extractors.
+ *
+ * Pure extraction layer: given file contents, produce comparable constraint
+ * maps. No filesystem or git access. See threshold-ratchet.mjs for the CLI
+ * and threshold-ratchet-compare.mjs for the comparison rules.
+ */
+
+/**
+ * File families the ratchet watches. `kind` selects the extractor;
+ * `direction` applies to numeric-leaf kinds ("min" values may only rise,
+ * "max" values may only fall).
+ */
+export const FAMILIES = [
+  {
+    id: "coverage",
+    match: /(^|\/)(vitest|jest)\.thresholds\.json$/,
+    kind: "json-num",
+    direction: "min",
+  },
+  {
+    id: "simplecov",
+    match: /(^|\/)simplecov\.thresholds\.json$/,
+    kind: "json-num",
+    direction: "min",
+  },
+  {
+    id: "e2e",
+    match: /(^|\/)e2e\.thresholds\.json$/,
+    kind: "json-num",
+    direction: "min",
+  },
+  {
+    id: "eslint",
+    match: /(^|\/)eslint\.thresholds\.json$/,
+    kind: "json-num",
+    direction: "max",
+  },
+  {
+    id: "rubocop",
+    match: /(^|\/)rubocop\.thresholds\.yml$/,
+    kind: "rubocop-yaml",
+    direction: "max",
+  },
+  { id: "stryker", match: /(^|\/)stryker\.conf\.json$/, kind: "stryker" },
+  {
+    id: "k6",
+    match: /(^|\/)\.github\/k6\/thresholds\/[^/]+\.json$/,
+    kind: "k6",
+  },
+  {
+    id: "audit-ignore",
+    match: /(^|\/)audit\.ignore\.(config|local)\.json$/,
+    kind: "exemption-list",
+  },
+  {
+    id: "lisa-config",
+    match: /(^|\/)\.lisa\.config\.json$/,
+    kind: "allow-list",
+  },
+];
+
+/**
+ * Find the family a repo-relative path belongs to.
+ * @param {string} relPath Repo-relative path (forward slashes)
+ * @returns {(typeof FAMILIES)[number] | undefined} The matching family, or
+ *   undefined when the path is not a watched gate file
+ */
+export function familyFor(relPath) {
+  return FAMILIES.find(f => f.match.test(relPath));
+}
+
+/**
+ * Safe JSON parse.
+ * @param {string | null | undefined} text JSON text
+ * @returns {unknown | undefined} Parsed value, or undefined on failure
+ */
+export function parseJson(text) {
+  if (typeof text !== "string") return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Walk a JSON object and collect numeric leaves as dotted-path constraints.
+ * Keys starting with "_" (e.g. `_comment`) are documentation, not thresholds.
+ * @param {unknown} node Parsed JSON value
+ * @param {"min"|"max"} direction Ratchet direction for every leaf
+ * @param {string} [prefix] Dotted path accumulated so far
+ * @returns {Map<string, { value: number, direction: "min"|"max" }>} Dotted
+ *   path → numeric constraint for every finite numeric leaf
+ */
+export function extractNumericLeaves(node, direction, prefix = "") {
+  const out = new Map();
+  if (node === null || typeof node !== "object" || Array.isArray(node)) {
+    return out;
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (key.startsWith("_")) continue;
+    const p = prefix ? `${prefix}.${key}` : key;
+    if (typeof value === "number" && Number.isFinite(value)) {
+      out.set(p, { value, direction });
+    } else if (value && typeof value === "object" && !Array.isArray(value)) {
+      for (const [cp, c] of extractNumericLeaves(value, direction, p)) {
+        out.set(cp, c);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Minimal parser for rubocop.thresholds.yml — a two-level document of
+ * `Section:` headers with indented `Key: <number>` scalars (comments and
+ * blank lines ignored). Deliberately NOT a general YAML parser: the file is
+ * Lisa-authored with this exact shape, and hand-parsing keeps the gate
+ * dependency-free with no backtracking-prone regexes.
+ * @param {string} text File contents
+ * @param {"min"|"max"} direction Ratchet direction for every scalar
+ * @returns {Map<string, { value: number, direction: "min"|"max" }>} Dotted
+ *   `Section.Key` path → numeric constraint
+ */
+export function extractRubocopThresholds(text, direction) {
+  const out = new Map();
+  const state = { section: "" };
+  for (const rawLine of text.split("\n")) {
+    const hash = rawLine.indexOf("#");
+    const line = (hash >= 0 ? rawLine.slice(0, hash) : rawLine).trimEnd();
+    if (!line.trim()) continue;
+    const indented = line.startsWith(" ") || line.startsWith("\t");
+    if (!indented && line.endsWith(":")) {
+      state.section = line.slice(0, -1).trim();
+      continue;
+    }
+    const colon = line.indexOf(":");
+    if (!indented || colon < 0 || !state.section) continue;
+    const key = line.slice(0, colon).trim();
+    const rawValue = line.slice(colon + 1).trim();
+    // Number("") is 0, so an empty value (e.g. a nested `Exclude:` list
+    // header) must be skipped, not recorded as a zero threshold.
+    const value = Number(rawValue);
+    if (key && rawValue !== "" && Number.isFinite(value)) {
+      out.set(`${state.section}.${key}`, { value, direction });
+    }
+  }
+  return out;
+}
+
+/**
+ * Extract the gating constraint from stryker.conf.json: only
+ * `thresholds.break` fails a run (`high`/`low` are reporting bands).
+ * @param {unknown} conf Parsed stryker.conf.json
+ * @returns {Map<string, { value: number, direction: "min"|"max" }>} The
+ *   `thresholds.break` constraint when present, otherwise an empty map
+ */
+export function extractStrykerConstraints(conf) {
+  const out = new Map();
+  const breakValue = conf?.thresholds?.break;
+  if (typeof breakValue === "number" && Number.isFinite(breakValue)) {
+    out.set("thresholds.break", { value: breakValue, direction: "min" });
+  }
+  return out;
+}
+
+/**
+ * Split a stryker `mutate` array into positive globs and negations.
+ * @param {unknown} conf Parsed stryker.conf.json
+ * @returns {{ positives: Set<string>, negations: Set<string> }} Globs that
+ *   include files vs. `!`-prefixed globs that exclude them
+ */
+export function extractStrykerMutate(conf) {
+  const positives = new Set();
+  const negations = new Set();
+  const mutate = Array.isArray(conf?.mutate) ? conf.mutate : [];
+  for (const glob of mutate) {
+    if (typeof glob !== "string") continue;
+    if (glob.startsWith("!")) negations.add(glob);
+    else positives.add(glob);
+  }
+  return { positives, negations };
+}
+
+/**
+ * Parse one k6 threshold expression (`p(95)<1000`, `rate>=0.99`, …) into a
+ * ratchet constraint. Upper bounds (`<`, `<=`) may only decrease; lower
+ * bounds (`>`, `>=`) may only increase. Hand-parsed — no regex.
+ * @param {string} expr Threshold expression
+ * @returns {{ value: number, direction: "min"|"max" } | undefined} The bound
+ *   as a constraint, or undefined when the expression has no numeric bound
+ */
+export function parseK6Expression(expr) {
+  for (const op of ["<=", ">=", "<", ">"]) {
+    const idx = expr.indexOf(op);
+    if (idx < 0) continue;
+    const value = Number(expr.slice(idx + op.length).trim());
+    if (!Number.isFinite(value)) return undefined;
+    return { value, direction: op.startsWith("<") ? "max" : "min" };
+  }
+  return undefined;
+}
+
+/**
+ * Extract constraints from a k6 thresholds file. Each metric contributes its
+ * expression bound(s) plus (when present) `abortOnFail` boolean constraints —
+ * turning abortOnFail off makes the gate advisory, which is a weakening.
+ * Handles every documented k6 shape: a bare expression string, a single long
+ * form `{ threshold, abortOnFail }` object, and arrays mixing both.
+ * @param {unknown} conf Parsed k6 thresholds JSON
+ * @returns {{
+ *   numeric: Map<string, { value: number, direction: "min"|"max" }>,
+ *   booleans: Map<string, boolean>,
+ * }} Numeric bounds keyed by `<metric>.threshold[i]` and abortOnFail flags
+ *   keyed by `<metric>.abortOnFail` (`[i]`-suffixed for array items)
+ */
+export function extractK6Constraints(conf) {
+  const numeric = new Map();
+  const booleans = new Map();
+  const thresholds = conf?.thresholds;
+  if (thresholds && typeof thresholds === "object") {
+    for (const [metric, spec] of Object.entries(thresholds)) {
+      const isArray = Array.isArray(spec);
+      const items = isArray ? spec : [spec];
+      items.forEach((item, i) => {
+        const expr =
+          typeof item === "string"
+            ? item
+            : item && typeof item === "object" && !Array.isArray(item)
+              ? item.threshold
+              : undefined;
+        if (typeof expr === "string") {
+          const c = parseK6Expression(expr);
+          if (c) numeric.set(`${metric}.threshold[${i}]`, c);
+        }
+        if (
+          item &&
+          typeof item === "object" &&
+          !Array.isArray(item) &&
+          typeof item.abortOnFail === "boolean"
+        ) {
+          booleans.set(
+            isArray ? `${metric}.abortOnFail[${i}]` : `${metric}.abortOnFail`,
+            item.abortOnFail
+          );
+        }
+      });
+    }
+  }
+  return { numeric, booleans };
+}
+
+/**
+ * Flatten an exemption file (audit ignore list) into a set of entry tokens.
+ * Arrays contribute their string items; objects contribute their keys.
+ * @param {unknown} conf Parsed JSON
+ * @returns {Set<string>} One token per exemption entry
+ */
+export function extractExemptionEntries(conf) {
+  const out = new Set();
+  if (Array.isArray(conf)) {
+    for (const item of conf) {
+      if (typeof item === "string") out.add(item);
+      else if (item && typeof item === "object") out.add(JSON.stringify(item));
+    }
+  } else if (conf && typeof conf === "object") {
+    for (const [key, value] of Object.entries(conf)) {
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          out.add(
+            `${key}:${typeof item === "string" ? item : JSON.stringify(item)}`
+          );
+        }
+      } else {
+        out.add(key);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Extract thresholdRatchet.allow entries from parsed .lisa.config.json.
+ * @param {unknown} config Parsed config (may be undefined)
+ * @returns {Array<{ file: string, key: string, reason?: string }>} The
+ *   well-formed allow entries; malformed entries are dropped
+ */
+export function extractAllowEntries(config) {
+  const raw = config?.thresholdRatchet?.allow;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(
+    e => e && typeof e.file === "string" && typeof e.key === "string"
+  );
+}

package/plugins/lisa-cursor/hooks/threshold-ratchet.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * Threshold ratchet gate — quality thresholds may tighten, never weaken.
+ *
+ * Deterministic comparator shared by three enforcement layers:
+ *   1. Agent-time soft block: PostToolUse hook via threshold-ratchet.sh
+ *      (`--hook`, exit 2 on weakening so the agent gets actionable feedback).
+ *   2. Pre-commit backstop: husky / lefthook (`--staged`, exit 1).
+ *   3. CI gate: reusable quality workflows (`--base <ref>`, exit 1),
+ *      comparing against the merge-base so nothing weakened lands in a PR.
+ *
+ * Tier 1 — designed tunables: vitest/jest/simplecov/e2e thresholds
+ * (minimums) and eslint/rubocop thresholds (maximums). Tier 2 — stryker's
+ * break score and k6 expression bounds. Tier 3 — exemption additions
+ * (audit-ignore entries, stryker mutate exclusions, thresholdRatchet.allow
+ * entries) which weaken a gate without touching a number.
+ *
+ * Human override: `.lisa.config.json` → `thresholdRatchet.allow` entries
+ * ({ file, key, reason }). Honored ONLY from the baseline side (HEAD /
+ * merge-base), never from the change under review — an agent cannot grant
+ * itself an exception in the same change that weakens a gate. `key: "*"`
+ * allows every key in the file.
+ *
+ * Extraction lives in threshold-ratchet-families.mjs; comparison rules in
+ * threshold-ratchet-compare.mjs. Zero dependencies.
+ */
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  extractAllowEntries,
+  familyFor,
+  parseJson,
+} from "./threshold-ratchet-families.mjs";
+import {
+  applyAllowList,
+  compareFile,
+  formatReport,
+} from "./threshold-ratchet-compare.mjs";
+
+/**
+ * Standard git locations, checked in order so the executable comes from a
+ * fixed, unwriteable directory rather than a PATH lookup. The bare "git"
+ * fallback keeps unusual layouts (e.g. Windows git-bash) working.
+ */
+const GIT_LOCATIONS = [
+  "/usr/bin/git",
+  "/usr/local/bin/git",
+  "/opt/homebrew/bin/git",
+];
+const GIT = GIT_LOCATIONS.find(candidate => fs.existsSync(candidate)) ?? "git";
+
+/** Git flag shared by every changed-file listing. */
+const NAME_ONLY = "--name-only";
+
+/**
+ * Run git, returning stdout or null on any failure.
+ * @param {string[]} args Git arguments
+ * @param {string} [cwd] Working directory
+ * @returns {string | null} Captured stdout, or null when git failed
+ */
+function git(args, cwd) {
+  try {
+    return execFileSync(GIT, args, {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve mode-specific candidate files and content readers.
+ * @param {"hook"|"staged"|"base"} mode Comparison mode
+ * @param {string} root Repo root
+ * @param {string | undefined} baseRef Base ref (base mode only)
+ * @param {string[] | undefined} onlyFiles Restrict to these repo-relative
+ *   paths (hook mode with a known edited file)
+ * @returns {{ files: string[], baselineRef: string, readCurrent: (f: string) => string | null } | null}
+ *   The comparison plan, or null when git state can't support the mode
+ */
+function resolvePlan(mode, root, baseRef, onlyFiles) {
+  if (mode === "staged") {
+    const diff = git(["diff", "--cached", NAME_ONLY], root);
+    if (diff === null) return null;
+    return {
+      files: diff.split("\n").filter(Boolean),
+      baselineRef: "HEAD",
+      readCurrent: f => git(["show", `:${f}`], root),
+    };
+  }
+  if (mode === "base") {
+    if (!baseRef) return null;
+    const mergeBase = git(["merge-base", baseRef, "HEAD"], root)?.trim();
+    if (!mergeBase) return null;
+    const diff = git(["diff", NAME_ONLY, mergeBase, "HEAD"], root);
+    if (diff === null) return null;
+    return {
+      files: diff.split("\n").filter(Boolean),
+      baselineRef: mergeBase,
+      readCurrent: f => git(["show", `HEAD:${f}`], root),
+    };
+  }
+  const diff = git(["diff", NAME_ONLY, "HEAD"], root);
+  if (diff === null) return null;
+  return {
+    files: onlyFiles ?? diff.split("\n").filter(Boolean),
+    baselineRef: "HEAD",
+    readCurrent: f => {
+      try {
+        return fs.readFileSync(path.join(root, f), "utf-8");
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/**
+ * Run the ratchet for a mode, print the report, and return the exit code.
+ * @param {"hook"|"staged"|"base"} mode Comparison mode
+ * @param {string | undefined} [baseRef] Base ref (base mode only)
+ * @param {string[] | undefined} [onlyFiles] Restrict to these paths (hook mode)
+ * @returns {number} Process exit code (2 for hook mode, 1 otherwise; 0 clean)
+ */
+function run(mode, baseRef, onlyFiles) {
+  const root = git(["rev-parse", "--show-toplevel"])?.trim();
+  if (!root) return 0;
+  const plan = resolvePlan(mode, root, baseRef, onlyFiles);
+  if (!plan) return 0;
+
+  const watched = plan.files.filter(f => familyFor(f));
+  if (watched.length === 0) return 0;
+
+  const findings = watched.flatMap(f =>
+    compareFile(
+      f,
+      git(["show", `${plan.baselineRef}:${f}`], root),
+      plan.readCurrent(f)
+    )
+  );
+  if (findings.length === 0) return 0;
+
+  const baselineConfig = parseJson(
+    git(["show", `${plan.baselineRef}:.lisa.config.json`], root)
+  );
+  const { blocked, allowed } = applyAllowList(
+    findings,
+    extractAllowEntries(baselineConfig)
+  );
+  for (const finding of allowed) {
+    process.stdout.write(
+      `threshold-ratchet: allowed by .lisa.config.json exception — ${finding.message}\n`
+    );
+  }
+  if (blocked.length === 0) return 0;
+  process.stderr.write(`${formatReport(blocked)}\n`);
+  return mode === "hook" ? 2 : 1;
+}
+
+/**
+ * Handle `--hook` mode: parse the tool-use event from stdin and scope the
+ * check to the edited file (Edit/Write/NotebookEdit) or every changed
+ * watched file (Bash).
+ * @returns {number} Process exit code
+ */
+function runHookMode() {
+  const state = { stdin: "" };
+  try {
+    state.stdin = fs.readFileSync(0, "utf-8");
+  } catch {
+    return 0;
+  }
+  const input = parseJson(state.stdin);
+  if (!input || typeof input !== "object") return 0;
+  if (input.tool_name === "Bash") return run("hook");
+  if (!["Edit", "Write", "NotebookEdit"].includes(input.tool_name)) return 0;
+  const filePath = input.tool_input?.file_path;
+  if (typeof filePath !== "string") return 0;
+  const root = git(["rev-parse", "--show-toplevel"])?.trim();
+  if (!root) return 0;
+  const rel = path
+    .relative(root, path.resolve(filePath))
+    .split(path.sep)
+    .join("/");
+  if (rel.startsWith("..") || !familyFor(rel)) return 0;
+  return run("hook", undefined, [rel]);
+}
+
+/**
+ * CLI entrypoint.
+ * @returns {number} Process exit code
+ */
+function main() {
+  const args = process.argv.slice(2);
+  if (args[0] === "--staged") return run("staged");
+  if (args[0] === "--base") return run("base", args[1]);
+  if (args[0] === "--hook") return runHookMode();
+  process.stderr.write(
+    "usage: threshold-ratchet.mjs --hook | --staged | --base <ref>\n"
+  );
+  return 0;
+}
+
+const isDirectRun =
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (isDirectRun) {
+  process.exit(main());
+}

package/plugins/lisa-cursor/hooks/threshold-ratchet.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# PostToolUse hook for Edit|Write|NotebookEdit|Bash: the threshold ratchet.
+# Quality thresholds (coverage minimums, complexity maximums, mutation break
+# score, e2e route floors, k6 bounds, audit-ignore lists) may tighten but never
+# weaken. The deterministic comparator lives in threshold-ratchet.mjs and is
+# shared with the pre-commit (husky/lefthook --staged) and CI (--base) layers,
+# so this hook is fast feedback — not the only line of defense.
+#
+# Exit 2 on weakening (soft block: the agent gets the report on stderr and can
+# fix the code or escalate to a human). Every infrastructure gap — no node, no
+# git repo, unreadable stdin — exits 0: the CI layer still guarantees the gate,
+# and a broken hook must never wedge an agent session.
+set -euo pipefail
+
+input="$(cat)"
+
+command -v node >/dev/null 2>&1 || exit 0
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+printf '%s' "$input" | node "$script_dir/threshold-ratchet.mjs" --hook

package/plugins/lisa-cursor/rules/claim-archaeology-reference.mdc

@@ -0,0 +1,147 @@
+---
+description: "Claim-Time Archaeology"
+alwaysApply: false
+---
+
+# Claim-Time Archaeology
+
+Lisa lifecycles are ONE-WAY — a done issue never reopens, so residual failures come back as NEW issues, and the causal link "issue B exists because issue A was done wrong" is invisible unless someone digs. Reopening terminal issues is out of scope, so claim-time archaeology is the only way to recover that link: at claim time, determine whether the item being claimed is round 2 of a past failure, and if so, what specifically went wrong the first time.
+
+It is a **single vendor-neutral contract** consumed by all three build-intake skills (`lisa-jira-build-intake`, `lisa-github-build-intake`, `lisa-linear-build-intake`). Each vendor arm cites this slug in its claim step rather than growing its own archaeology, exactly as the arms cite `leaf-only-lifecycle`, `repo-scope-split`, and `rejection-detection`. One slug is what keeps an ancestor found on JIRA from being missed on Linear.
+
+## Seam and sequencing — after rejection detection, before the claim transition
+
+The three build-intake skills share a uniform claim phase: `3a.0` repo-scope gate → `3a` leaf-only claim gate → `3b` Claim → `3c` run lifecycle (culminating in `lisa-implement`) → `3d` transition to done.
+
+Within `3b`, the pre-transition window runs two passes in a fixed order:
+
+1. **`rejection-detection` runs first** (top of `3b`, before the relabel — it needs the current-lane signal that the relabel destroys).
+2. **Archaeology runs second** — after the rejection classification exists, still **before the relabel/transition** `$READY → $CLAIMED`.
+
+The ordering is load-bearing: rejection-detection's classification is an **input** to archaeology's. A `rejection-reclaim` detected in pass 1 flows straight into archaeology's classification — it is reused, **not re-derived**. Archaeology never re-reads transition history to second-guess the rejection detector; forking that signal would guarantee drift between the two passes.
+
+**`lisa-implement` is NOT the seam** — it never sees the claim. Archaeology belongs to the build-intake claim phase, like the two gates before it.
+
+## Ancestry signals
+
+Three signal sources, tried in order of cheapness. Every query counts against the cost budget below.
+
+### 1. Tracker metadata (typed relations)
+
+The cheapest and most reliable signal: the relations the vendor read skills already parse. Read them from the context bundle the intake flow already fetched — do not re-fetch:
+
+- The typed relation lines — `Blocks` / `Blocked by` / `Relates to` / `Duplicates` / `Cloned from` — that `lisa-github-read-issue`, `lisa-jira-read-ticket`, and `lisa-linear-read-issue` parse into the relations table of their context bundles.
+- GitHub's native `closingIssuesReferences` (PR↔issue closure links) and timeline cross-references, surfaced by the same `lisa-github-read-issue` GraphQL read. JIRA issue links and Linear native relations (`blocks` / `blocked_by` / `relates_to` / `duplicates`) are the vendor equivalents, read through the access layers (`integration-access-layer`) — never a direct vendor API call.
+
+A relation pointing at a **closed, done** issue whose shipped work plausibly covers this issue's surface is an ancestor candidate. An "introduced by"-shaped link (this issue references the PR or issue that shipped the defect) is the strongest form.
+
+### 2. Text similarity (bounded, lexical)
+
+**The honest bound, stated plainly: no embedding machinery exists in Lisa, and none is introduced here. This signal is lexical overlap over tracker search primitives — not semantic similarity — and it will miss paraphrased descriptions.** That is acceptable: it exists to catch the common case of a new issue describing a defect in something recently shipped, using roughly the words the shipping issue used.
+
+Scope: **recently-closed** issues (closed within the recent window the budget affords, newest first) **touching the same implicated files** where file paths are named or inferable, ranked by **title/label overlap** with the issue being claimed. The primitives:
+
+- **GitHub** — `gh search issues "<key terms>" --repo <org>/<repo> --state closed --sort updated` (and `--label` narrowing where labels overlap).
+- **JIRA** — `lisa-atlassian-access operation: search-issues jql: "project = <P> AND statusCategory = Done AND resolved >= -30d AND text ~ \"<key terms>\" ORDER BY resolved DESC"`.
+- **Linear** — `lisa-linear-access operation: list-issues` filtered to completed state types, matched client-side on title/label overlap.
+
+A hit is a candidate only when the overlap is specific (shared distinctive terms, same component labels, same files named) — generic word overlap alone never promotes an ancestor.
+
+### 3. Git ancestry (deterministic, machine-readable)
+
+For the files the issue implicates (named in the body, or inferred from the similarity hits), answer "which PR last shipped this file" with **direct deterministic git commands**:
+
+```bash
+git log --follow --format='%H %aI %s' -n 5 -- <file>   # last commits touching the file
+git blame -L <range> --line-porcelain <file>            # who last shipped the implicated lines
+# The PR that shipped the file. --full-history is required: path-limited git log
+# simplifies away merge commits by default, silently dropping the merge-PR answer.
+# Two --grep patterns (OR'd) cover both merge conventions: classic merge commits
+# ("Merge pull request #<n>") and squash/rebase merges (subject ending "(#<n>)").
+# POSIX BRE only — GNU-only \+ silently matches nothing on BSD/macOS git.
+git log --full-history --grep "Merge pull request #" --grep "(#[0-9][0-9]*)" --format='%H %aI %s' -n 5 -- <file>
+```
+
+Keep the result **parseable**: a `{file, sha, pr, date}` tuple per implicated file (PR number extracted from the subject — `Merge pull request #<n>` for merge commits, the trailing `(#<n>)` for squash/rebase merges; empty when the history matches neither convention). The PR maps back to its issue via `closingIssuesReferences` / the PR body's issue reference.
+
+**Do NOT delegate this to the `git-history-analyzer` agent.** That agent can answer the question, but it returns a **prose report with no machine-readable contract** (nothing downstream can reliably parse it), it is explicitly forbidden from judging past decisions, and it reads the local repo only. For programmatic claim-time archaeology, run the deterministic query directly and keep the `{file, sha, pr, date}` result.
+
+## Learning-loop exclusion (scan-side — a learning artifact is never an ancestor)
+
+This flow produces learning PRs, candidate comments, and upstream handoffs. Those artifacts touch the same files and reference the same issues as the failures they describe — which makes them **near-perfect false-positive ancestors**. Without an explicit exclusion the flow learns from itself, recursively.
+
+Before any candidate is promoted to ancestor, exclude every artifact carrying any of these markers or labels — such an artifact is **never an ancestor**, no matter how strong its other signals:
+
+- `[lisa-learning-drop]`
+- `[lisa-learning-pr]`
+- `[lisa-learning-upstream-handoff]`
+- `[lisa-rejection-candidate]`
+- `[lisa-archaeology-candidate]` (this rule's own producer tag — archaeology's output must not seed the next claim's input)
+- the `learning:needs-triage` label
+
+This is the **scan-side** half of the no-learning-loops guard; `rejection-detection` carries the symmetric **trigger-side** half ("a learning artifact is never a rejection-reflection trigger").
+
+## Classification
+
+Exactly one of three states:
+
+| Classification | Condition |
+|---|---|
+| `rejection-reclaim` | The `rejection-detection` pass classified this claim `rejection-reclaim`. Taken directly from that result — reused, never re-derived here. Its reflection path (the `[lisa-rejection-candidate]` candidate) already covers the learning; archaeology adds nothing on top. |
+| `retry-of-done-issue` | Not a rejection-reclaim, AND an ancestry signal (§ above, post-exclusion) names a closed done issue whose shipped work this issue exists to fix. |
+| `fresh` | Everything else: no ancestor, weak/inconclusive signals, budget exhausted, or the pass errored. |
+
+Classification itself is **stateless** — a pure function of the signals read this pass, holding no cache or stored state between claims. Re-running it on the same inputs yields the same answer; idempotency of the *side effect* (the candidate) is carried by marker dedupe below.
+
+## Candidate derivation (`retry-of-done-issue` only)
+
+An ancestor alone teaches nothing — "B relates to A" is trivia. The learning lives in the **delta**: the gap between what agent A actually did and what issue B proves was actually needed.
+
+1. **Reconstruct what the ancestor shipped**, through the access layers: its merged PR (diff, description), the review threads on that PR, and the evidence comments on the ancestor issue.
+2. **Derive ONE candidate learning citing the delta** — **what was done** versus **what this issue proves was needed**. The shape is "A shipped X; B proves Y was required; the mistake was assuming X sufficed" — never "A had a bug". A **vague summary** that does not name the specific mistake is worthless and must be rejected (produce nothing rather than noise).
+3. **Route it to `lisa-persist-learning`** exactly like the rejection-reflection path: candidate fields (rule, why, provenance linking the ancestor issue + its PR + this issue, evidence links, scope hint, triggering issue) with fingerprint `sll4-sha1(rule\ntriggering_issue)[:12]`.
+
+### Graceful degrade — `lisa-persist-learning` unavailable
+
+Same fallback pattern as the rejection path, with this rule's own distinct marker. Record the candidate as a comment on the claimed item carrying a **visible prose line** plus the marker (a bare marker renders as an empty comment bubble):
+
+```text
+Recorded a candidate learning from this retry's ancestry (queued for the judgment gate): <one-line candidate rule>.
+<!-- [lisa-archaeology-candidate] key=<issue>::<ancestor> -->
+```
+
+The marker line is verbatim — the dedupe contract keys on it, not on the prose.
+
+### Idempotency — marker dedupe
+
+The key is `<issue>::<ancestor>` (the claimed item's ref, `::`, the ancestor's ref — the `::` separator keeps the key unambiguous when vendor refs themselves contain hyphens, e.g. `PROJ-123`; it is stable across re-claims of the same pair). Before producing a candidate, search for an existing `[lisa-archaeology-candidate]` comment/artifact carrying this exact key — match on the **marker, never the title** (the `lisa-github-write-prd` Phase 2 discipline). Dedupe is per **(issue, ancestor) pair**: re-claiming an issue whose archaeology already resolved the same ancestor finds the marker and short-circuits — no duplicate candidate for that pair. A re-claim that resolves a **different** ancestor is new evidence and may legitimately produce a second candidate under its own key — that is intended, not a dedupe failure.
+
+### `fresh` produces silence
+
+A `fresh` classification produces **no candidate and zero comments**. Silence is the correct output — emitting a low-value candidate on every claim is precisely the rule-pollution failure mode the learning loop names as its existential risk.
+
+## Cost budget — enforced here, configured in one place
+
+Archaeology is speculative digging on the critical path of every claim. The budget is what makes that safe.
+
+- **`archaeology.maxSteps`** — the maximum number of tracker/git queries one archaeology pass may spend, read from `.lisa.config.json`:
+
+  ```bash
+  MAX_STEPS=$(jq -r '.archaeology.maxSteps // 8' .lisa.config.json 2>/dev/null || echo 8)
+  ```
+
+  The conservative default is **8** — enough for the metadata read (free, already fetched), one or two similarity searches, and git ancestry over a handful of implicated files, and small enough that a fruitless dig on a large repo ends quickly. `lisa sync` seeds the key (registry default), and **this rule pair is the single documented place** for what the budget means — do not restate its semantics in the vendor skills.
+- **`archaeology.maxSeconds`** — optional wall-clock ceiling for the whole pass, read the same way (`jq -r '.archaeology.maxSeconds // empty'`); unset means steps alone bound the pass.
+
+**Budget exhaustion is a NORMAL outcome, not an error.** When the pass hits either ceiling with no confident ancestor, it classifies `fresh` and the claim proceeds immediately — no retry, no escalation, no blocking warning.
+
+## Never block the claim
+
+The invariant everything above hangs on: **archaeology never blocks the claim**. By construction:
+
+- Weak or inconclusive signals → degrade to `fresh`, claim proceeds.
+- Budget exhausted → degrade to `fresh`, claim proceeds.
+- The pass throws or errors (tracker outage, malformed history, missing config) → the exception is caught, classification degrades to `fresh`, and the **claim still proceeds** — a crash inside a speculative bonus feature must never strand a ready issue in the queue.
+- Unreadable ancestor evidence on a genuine retry → no candidate produced, the item is still implemented — degraded, not stopped.
+
+Headless-safe throughout: no interactive prompts, safe under intake crons.