@codyswann/lisa 2.239.1 → 2.241.0

package/plugins/src/base/rules/reference/claim-archaeology.md

@@ -0,0 +1,142 @@
+# 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.

package/plugins/src/base/rules/reference/project-learnings.md

@@ -20,6 +20,24 @@ Each persisted entry has seven fields:
 - `last_confirmed`
 - `confidence`
 
+## Claim-time confirmation (`last_confirmed`)
+
+`last_confirmed` is advanced at claim time by the build-intake flows (step
+3c.2 of `lisa-{jira,github,linear}-build-intake`) when an entry's rule
+**demonstrably applied** during a claim — the rule was explicitly cited or
+observably followed in the claim's plan or diff. Presence in the eagerly
+loaded context is NOT application: every entry is present in every session,
+so counting mere presence would confirm everything on every claim and defeat
+decay entirely.
+
+The bump goes only through `confirmLearningEntry` from
+`@codyswann/lisa/learnings`: a surgical, lock-protected, atomic write that
+advances only `last_confirmed` (re-validated against the
+`>= first_learned` invariant), returns a structured no-op for a missing
+entry or file instead of throwing, and is idempotent within a claim (a
+same-date repeat returns `unchanged`). A failed bump is reported and never
+blocks the build.
+
 Only entries accepted by the executable contract may influence the session. A
 missing file is expected and silent. Malformed Markdown, invalid JSONL, unsafe
 paths, non-canonical content, or over-budget documents produce one readable

package/plugins/src/base/skills/lisa-attribute-failure/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: lisa-attribute-failure
+description: "Event-triggered root-cause attribution for an arbitrary failure: decide, with cited evidence, whether the defect is Lisa's fault or the project's. Accepts a failure event (defect description, implicated files, rule/skill/hook in play) and returns a verdict of lisa | project | ambiguous plus the evidence relied on. Read-only — it never files, writes, or remediates; callers (lisa-doctor findings, the learning judgment gate, rework triage) consume the verdict. Extracted from lisa-doctor's upstream Lisa change-history diagnosis (#1494) so the same attribution procedure can run on ANY failure event, not only doctor config-audit findings."
+allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep"]
+---
+
+# Attribute Failure
+
+Attribute ONE failure event to Lisa or the project, with cited evidence. Failure event: $ARGUMENTS
+
+Before a Lisa-caused failure can be routed upstream, something has to say — with evidence — "this was Lisa's fault, not the project's." A failure has two possible causes: the project drifted, or **Lisa itself changed or shipped the defect**. This skill must distinguish them instead of blaming the project by default, and equally must never blame Lisa without conclusive evidence. Wrong attribution in either direction is the failure mode; **inconclusive evidence is always `ambiguous`, and ambiguous stays local and low-confidence — never upstream.**
+
+## Input — the failure event
+
+Accept the event as JSON or `key=value` fields. This procedure is **event-triggered, not version-window-keyed**: any failure can be attributed, not only a doctor config-audit finding.
+
+- `defect` — what went wrong, in plain language (required)
+- `implicated_files` — the file paths where the defect lives or manifests (required when known)
+- `surface_in_play` — the Lisa rule / skill / hook / template / workflow involved, if any
+- `installed_version` / `latest_version` — the Lisa version window, when the caller knows it; otherwise resolve it as signal 3 describes
+- `failure_class` — a short slug naming the class of failure (used by downstream filing for the root-cause key)
+
+## Output — the verdict
+
+Return exactly one verdict — `lisa` | `project` | `ambiguous` — plus the evidence it relied on:
+
+```text
+## Attribution: [lisa | project | ambiguous]
+
+**Signal:** [managed-surface | shipped-artifact-behavior | upstream-history | none-conclusive]
+**Lisa surface at fault:** [path or rule/skill/hook name | n/a]
+**Cited evidence:**
+- [each item names the signal it came from and the concrete citation: file path + ownership proof, shipped artifact text, or commit sha/subject/version]
+**Confidence note:** [why the evidence is conclusive, or exactly what was inconclusive]
+```
+
+Verdict rules:
+
+- **`lisa`** — at least one signal conclusively pins the defect on a Lisa-shipped surface or upstream change, and the evidence names that surface. Never emit `lisa` from degraded, truncated, or unverified history.
+- **`project`** — the implicated files are project-owned, no shipped Lisa artifact drove the behavior, and the upstream-history window shows no relevant Lisa change. Cite the absence explicitly (which paths were checked, which window showed no relevant change).
+- **`ambiguous`** — anything else: unresolvable version window, unreachable history, partial ownership, conflicting signals. Ambiguous is treated as local and low-confidence; nothing is escalated upstream from it.
+
+## The three signals (evaluate in order)
+
+### Signal 1 — the defect lives in a Lisa-managed surface
+
+Resolve ownership of each implicated file the way doctor's config audit does:
+
+- **Copy-overwrite / managed**: the path is populated by `lisa apply` from a stack template (`typescript/`, `expo/`, `nestjs/`, `cdk/`, `harper-fabric/`, `rails/` copy-overwrite trees), is a plugin-distributed rule/skill/hook/agent/command surface, carries Lisa governance markers or a Lisa version stamp, or is governed by `package.lisa.json` `force` keys. A defect in the shipped content of such a surface is **Lisa's fault** — any local edit would be overwritten on the next `lisa apply`.
+- **Create-only**: the local copy is project-owned after scaffolding, but if the defect is faithful to the template as shipped, the template is still Lisa's fault (every newly scaffolded repo inherits it). Cite the template origin, and note the local copy will not be overwritten.
+- **Project-owned**: not from a Lisa template and not Lisa-managed — signal 1 is negative; continue.
+
+If the project locally modified a managed surface and the defect lives in the local modification, that is project drift, not a Lisa defect — signal 1 is negative for `lisa` and positive evidence for `project`.
+
+### Signal 2 — a shipped Lisa rule/skill/hook drove the wrong behavior
+
+Read the shipped artifact named in `surface_in_play` (the plugin-distributed rule, skill, hook, agent, or CI workflow as Lisa ships it — not a local fork). If following its instructions or configuration as shipped produces the observed defect, the verdict is `lisa`: cite the artifact path and the specific shipped text or configuration that drove the behavior. If the artifact is shipped correct and was misapplied locally, that is evidence for `project`.
+
+### Signal 3 — the upstream-history window shows Lisa changed the relevant contract
+
+This is the #1494 doctor procedure, unchanged in behavior — here it is the third signal, not the trigger. Whenever signals 1-2 are not conclusive on their own — and always before a definitive `project` verdict — pull Lisa's own git history for the version window and read what actually changed:
+
+1. **Resolve the version window.** Use the caller-supplied `installed_version`/`latest_version` when present; otherwise determine the project's installed Lisa version (the `@codyswann/lisa` entry in `package.json`/lockfile, or the plugin version stamp on the active runtime) and the latest published version (`npm view @codyswann/lisa version`, or the update check's cached result). An unresolvable window makes this signal inconclusive — it can support `ambiguous`, never `lisa`.
+2. **Pull the upstream history for that window** (read-only; no clone required when `gh` is available):
+
+   ```bash
+   gh api "repos/CodySwannGT/lisa/compare/v<installed>...v<latest>" \
+     --paginate --slurp |
+     jq '{total_commits: .[0].total_commits, files: [.[0].files[]?.filename], commits: [.[].commits[]? | {sha, subject: (.commit.message | split("\n")[0]), api_url: .url, html_url, parents: [.parents[]?.sha]}]}'
+   ```
+
+   `--paginate` fetches every page of commits, and `--slurp` gathers those pages into a single
+   array before the external `jq` projection runs. GitHub CLI does not permit its built-in `--jq`
+   flag together with `--slurp`, so keep the pipe as shown; without `--slurp`, paginated responses
+   are not one merged input. `total_commits` and `files` only need the first page
+   (files are capped at 300 and not repeated on later pages); `commits` flattens across all pages
+   while retaining each commit SHA and URLs needed for accurate follow-up.
+
+   After path-scoping identifies a candidate commit, fetch its targeted file-level diff context by
+   the retained SHA rather than attributing from the subject alone:
+
+   ```bash
+   gh api "repos/CodySwannGT/lisa/commits/<sha>" \
+     --jq '{sha, files: [.files[]? | select(.filename == "<relevant-path>" or (.filename | startswith("<relevant-prefix>/"))) | {filename, status, additions, deletions, changes, patch}]}'
+   ```
+
+   Preserve the returned filename, status, counts, and available patch with the SHA in the
+   upstream-history projection. A missing or truncated `patch` is not proof of no relevant change;
+   use the compare diff fallback below or downgrade the attribution to `ambiguous` when
+   commit-level context cannot be established.
+
+   The compare endpoint paginates commits (250 without `--paginate`) and only lists changed files
+   on the first page, capped at 300 total — a large version window can silently drop commits or
+   files. If `total_commits` or the file count looks truncated, re-run with the
+   `application/vnd.github.diff` accept header (`gh api ... -H "Accept: application/vnd.github.diff"`)
+   to pull the full patch text, or fall back to the bounded-fetch `git log` below. When completeness
+   still can't be established, say so in the evidence and return `ambiguous` rather than attributing
+   with unverified confidence.
+
+   Fallbacks, in order: `gh api repos/CodySwannGT/lisa/commits?path=<template-path>` for a
+   path-scoped view — note this endpoint has no way to bound results to the `v<installed>..v<latest>`
+   window, so treat its output as best-effort context only, not authoritative attribution; a
+   finite-depth, explicit-tag fetch, which is bounded to the two version refs and should be preferred
+   for definitive attribution; or the local marketplace/plugin cache checkout when the runtime has
+   one. For the fetch fallback, use a temporary directory and a fixed history ceiling:
+
+   ```bash
+   lisa_history_dir="$(mktemp -d)"
+   git init "$lisa_history_dir"
+   git -C "$lisa_history_dir" remote add origin https://github.com/CodySwannGT/lisa.git
+   git -C "$lisa_history_dir" fetch --no-tags --filter=blob:none --depth=256 origin \
+     refs/tags/v<installed>:refs/tags/v<installed> \
+     refs/tags/v<latest>:refs/tags/v<latest>
+   git -C "$lisa_history_dir" merge-base --is-ancestor v<installed> v<latest>
+   git -C "$lisa_history_dir" log --format='%H%x09%s' v<installed>..v<latest> -- <paths>
+   git -C "$lisa_history_dir" show --format=fuller --stat --patch <relevant-sha> -- <paths>
+   ```
+
+   The explicit tag refspecs, `--no-tags`, and finite `--depth=256` make this fetch bounded. Do not
+   silently deepen beyond that ceiling. If `merge-base --is-ancestor` fails, the shallow window is
+   incomplete (or the tags are not on one ancestry line): do not make definitive attribution from
+   it. If none of the bounded sources are reachable, or only the unbounded path-scoped fallback is
+   reachable, report the gap in the evidence and return `ambiguous` — never fail the caller's flow
+   because history was unavailable or incomplete, and never let a degraded history produce `lisa`.
+3. **Scope the reading to what the failure touches.** Filter the commit list to the paths that
+   generate the failing surface: the detected stacks' template dirs (`typescript/`, `expo/`, …),
+   `plugins/src/base/` for skills/hooks/rules, `scripts/` for governance scripts, and the shipped
+   config factories (`src/configs/`). A failure about a lint rule reads the lint-config commits,
+   not the whole log.
+4. **Attribute.** When the upstream history shows Lisa changed the relevant contract (a tightened
+   lint rule, a renamed check context, a new required config key), the verdict is `lisa` — cite the
+   commit subject/version. When history shows no relevant upstream change and signals 1-2 are also
+   negative, the project drifted — the verdict is `project`, citing the absence of a relevant
+   upstream change as the evidence.
+
+## Rules
+
+- **Read-only.** This skill reads the project and Lisa's repository; it never writes to either, never files issues, and never remediates. Filing the upstream ticket on a `lisa` verdict is the caller's flow (`lisa-persist-learning`, `handoff-upstream` disposition); doctor maps verdicts into its findings; remediation stays with whoever called.
+- **Never block.** Attribution failure, missing tooling (`gh` unavailable), or degraded history degrades to `ambiguous` with the gap named in the evidence — it never raises an error that stops the caller's build or audit.
+- **Every verdict cites its evidence.** An attribution without a named signal and concrete citation is invalid — return `ambiguous` instead. Evidence destined for upstream surfaces quotes ONLY Lisa-owned surface text (never host env values, tokens/credentials, PII, or proprietary host code — link the host issue instead of quoting it); the binding redaction procedure lives in `lisa-persist-learning`'s `handoff-upstream` step.
+- **Ambiguous never escalates.** `ambiguous` is a terminal local verdict: low-confidence, no upstream filing, no durable local rule derived from it.
+- **Headless-safe and idempotent**: no prompts, no side effects, same event in → same verdict out.

package/plugins/src/base/skills/lisa-doctor/SKILL.md

@@ -296,88 +296,39 @@ without turning the base doctor into a second `lisa-wiki-doctor`.
 A failing or warning check has two possible causes: the project drifted, or **Lisa itself changed
 upstream** since this project last updated. Doctor must distinguish them instead of blaming the
 project by default. Whenever findings need explanation — and always before proposing repairs —
-pull Lisa's own git history and read what actually changed:
+attribute the finding with real evidence.
+
+The attribution procedure itself is shared: it lives in the `lisa-attribute-failure` skill
+(extracted from this section so any failure event can be attributed, not only doctor findings).
+Doctor invokes it per finding:
 
 1. **Resolve the version window.** Determine the project's installed Lisa version (the
    `@codyswann/lisa` entry in `package.json`/lockfile, or the plugin version stamp on the active
    runtime) and the latest published version (`npm view @codyswann/lisa version`, or the update
    check's cached result).
-2. **Pull the upstream history for that window** (read-only; no clone required when `gh` is
-   available):
-
-   ```bash
-   gh api "repos/CodySwannGT/lisa/compare/v<installed>...v<latest>" \
-     --paginate --slurp |
-     jq '{total_commits: .[0].total_commits, files: [.[0].files[]?.filename], commits: [.[].commits[]? | {sha, subject: (.commit.message | split("\n")[0]), api_url: .url, html_url, parents: [.parents[]?.sha]}]}'
-   ```
-
-   `--paginate` fetches every page of commits, and `--slurp` gathers those pages into a single
-   array before the external `jq` projection runs. GitHub CLI does not permit its built-in `--jq`
-   flag together with `--slurp`, so keep the pipe as shown; without `--slurp`, paginated responses
-   are not one merged input. `total_commits` and `files` only need the first page
-   (files are capped at 300 and not repeated on later pages); `commits` flattens across all pages
-   while retaining each commit SHA and URLs needed for accurate follow-up.
-
-   After path-scoping identifies a candidate commit, fetch its targeted file-level diff context by
-   the retained SHA rather than attributing from the subject alone:
-
-   ```bash
-   gh api "repos/CodySwannGT/lisa/commits/<sha>" \
-     --jq '{sha, files: [.files[]? | select(.filename == "<relevant-path>" or (.filename | startswith("<relevant-prefix>/"))) | {filename, status, additions, deletions, changes, patch}]}'
-   ```
-
-   Preserve the returned filename, status, counts, and available patch with the SHA in the
-   upstream-history projection. A missing or truncated `patch` is not proof of no relevant change;
-   use the compare diff fallback below or downgrade attribution to `WARN` when commit-level context
-   cannot be established.
-
-   The compare endpoint paginates commits (250 without `--paginate`) and only lists changed files
-   on the first page, capped at 300 total — a large version window can silently drop commits or
-   files. If `total_commits` or the file count looks truncated, re-run with the
-   `application/vnd.github.diff` accept header (`gh api ... -H "Accept: application/vnd.github.diff"`)
-   to pull the full patch text, or fall back to the bounded-fetch `git log` below. When completeness
-   still can't be established, say so in the finding and mark it `WARN` rather than attributing
-   drift with unverified confidence.
-
-   Fallbacks, in order: `gh api repos/CodySwannGT/lisa/commits?path=<template-path>` for a
-   path-scoped view — note this endpoint has no way to bound results to the `v<installed>..v<latest>`
-   window, so treat its output as best-effort context only, not authoritative attribution; a
-   finite-depth, explicit-tag fetch, which is bounded to the two version refs and should be preferred
-   for definitive attribution; or the local marketplace/plugin cache checkout when the runtime has
-   one. For the fetch fallback, use a temporary directory and a fixed history ceiling:
-
-   ```bash
-   lisa_history_dir="$(mktemp -d)"
-   git init "$lisa_history_dir"
-   git -C "$lisa_history_dir" remote add origin https://github.com/CodySwannGT/lisa.git
-   git -C "$lisa_history_dir" fetch --no-tags --filter=blob:none --depth=256 origin \
-     refs/tags/v<installed>:refs/tags/v<installed> \
-     refs/tags/v<latest>:refs/tags/v<latest>
-   git -C "$lisa_history_dir" merge-base --is-ancestor v<installed> v<latest>
-   git -C "$lisa_history_dir" log --format='%H%x09%s' v<installed>..v<latest> -- <paths>
-   git -C "$lisa_history_dir" show --format=fuller --stat --patch <relevant-sha> -- <paths>
-   ```
-
-   The explicit tag refspecs, `--no-tags`, and finite `--depth=256` make this fetch bounded. Do not
-   silently deepen beyond that ceiling. If `merge-base --is-ancestor` fails, the shallow window is
-   incomplete (or the tags are not on one ancestry line): do not make definitive attribution from
-   it. If none of the bounded sources are reachable, or only the unbounded path-scoped fallback is
-   reachable, report the gap as a `WARN`-level observability note — never fail the audit because
-   history was unavailable or incomplete.
-3. **Scope the reading to what the finding touches.** Filter the commit list to the paths that
-   generate the failing surface: the detected stacks' template dirs (`typescript/`, `expo/`, …),
-   `plugins/src/base/` for skills/hooks/rules, `scripts/` for governance scripts, and the shipped
-   config factories (`src/configs/`). A finding about a lint rule failure reads the lint-config
-   commits, not the whole log.
-4. **Attribute the finding.** When the upstream history shows Lisa changed the contract (a
-   tightened lint rule, a renamed check context, a new required config key), say so in `Observed:`
-   with the commit subject/version, and let `Remediation:` point at the sanctioned adoption path
-   (e.g. `lisa update` + re-apply, a documented config opt-out) rather than hand-editing managed
-   files. When history shows no relevant upstream change, the project drifted — remediate on the
-   project side.
-
-This history pull is part of doctor's read-only contract: it reads Lisa's repository, never writes
-to it, and repair suggestions stay suggestions.
+2. **Invoke `lisa-attribute-failure`** with the finding as the failure event: the defect
+   description, the implicated template/config paths, the rule/skill/hook in play, and the
+   resolved version window. The skill evaluates its three ordered signals — Lisa-managed surface
+   ownership, shipped rule/skill/hook behavior, and the upstream change-history window (the
+   version-window compare procedure formerly documented inline here, preserved verbatim in that
+   skill: pagination/`--slurp` handling, targeted per-SHA diff context, truncation caveats, and
+   the bounded explicit-tag fetch fallback) — and returns `lisa` | `project` | `ambiguous` plus
+   the cited evidence.
+3. **Map the verdict into the finding.**
+   - `lisa` — Lisa changed the contract (a tightened lint rule, a renamed check context, a new
+     required config key) or shipped the defective surface. Say so in `Observed:` with the cited
+     evidence (commit subject/version or managed-surface proof), and let `Remediation:` point at
+     the sanctioned adoption path (e.g. `lisa update` + re-apply, a documented config opt-out)
+     rather than hand-editing managed files.
+   - `project` — history shows no relevant upstream change and the surface is project-owned: the
+     project drifted, so remediate on the project side.
+   - `ambiguous` — history was unavailable, truncated, or otherwise inconclusive: report the gap
+     as a `WARN`-level observability note with the evidence gap named — never fail the audit
+     because history was unavailable or incomplete, and never attribute drift with unverified
+     confidence.
+
+This diagnosis remains part of doctor's read-only contract: the attribution skill reads Lisa's
+repository, never writes to it, and repair suggestions stay suggestions.
 
 ## Output contract
 

package/plugins/src/base/skills/lisa-github-build-intake/SKILL.md

@@ -256,6 +256,8 @@ A blocker is active if it is open and has no cleared status label. Treat `status
 
 **On `rejection-reclaim`, reflect before re-implementing** (per `rejection-detection`): read the rejection evidence through the access layer — the issue comments posted after the backward transition (the QA rejection comment) and the review threads on the rejected PR via `lisa-github-read-issue` — assemble ONE candidate learning (rule, why, provenance linking the rejection comment + rejected PR, evidence links, scope hint, triggering issue, fingerprint `sll4-sha1(rule\ntriggering_issue)[:12]`), and route it to the `lisa-persist-learning` skill. If that skill is absent, record the candidate as a comment carrying a **visible prose line plus** the marker (a bare marker renders as an empty bubble) — `Recorded a candidate learning from this rejection (queued for the judgment gate): <one-line candidate rule>.` then `<!-- [lisa-rejection-candidate] key=<issue>-<transition-ts> -->` — and proceed. Dedupe on `<issue>-<backward-transition-timestamp>` — a second re-claim produces no duplicate. Unreadable/absent evidence → no candidate, still implement.
 
+**Claim-time archaeology runs second — after rejection detection, still before the relabel below.** Classify this item per the vendor-neutral `claim-archaeology` rule, with the rejection classification above as its input. All shared semantics — ancestry signals, classification, learning-loop exclusion, cost budget, candidate derivation, marker dedupe, and the never-block degrade — live in that one slug; change them there, never here. GitHub wiring only: the typed relations and `closingIssuesReferences` are already in the read bundle; text-similarity searches use `gh search issues` over recently-closed issues; the fallback candidate comment is posted with `gh issue comment`.
+
 ```bash
 gh issue edit <number> --repo <org>/<repo> --remove-label "$READY" --add-label "$CLAIMED"
 # Assign to the authenticated user ONLY when the issue is currently unassigned (attributable claim;
@@ -325,6 +327,22 @@ If the canonical fix is merged but not yet present on the production branch, app
 
 This path is distinct from `BLOCKED`: ambiguity, open blockers, and duplicate-of-open findings remain held for human action and must not be auto-closed.
 
+#### 3c.2 Confirm applied learnings (last_confirmed bump)
+
+Run this at the end of 3c, after the lifecycle outcome is recorded and before 3d. It keeps the decay pass safe: a genuinely useful learning that keeps applying stays fresh, while dead weight ages out.
+
+1. **Identify which learnings demonstrably applied.** Resolve the learnings surface with `resolveProjectLearningsFile` and parse it with `parseLearningsFile` from `@codyswann/lisa/learnings` (never hardcode the path; a missing file skips this step silently). An entry counts as applied ONLY when its rule was explicitly cited or observably followed in this claim's plan, diff, or review responses — the plan quotes the rule or its id, or the diff does specifically what the rule mandates where the default behavior would have differed. **Presence in context is NOT application**: the ledger is loaded eagerly into every session, so counting "it was loaded" would confirm every entry on every claim and defeat decay entirely. A run that produced no plan or diff has nothing to confirm.
+2. **Bump each applied entry exactly once** via the surgical writer:
+
+   ```bash
+   node -e 'import("@codyswann/lisa/learnings").then(async m => { const r = await m.confirmLearningEntry(process.cwd(), process.argv[1], new Date().toISOString().slice(0, 10)); console.log(JSON.stringify(r)); }).catch(error => { console.log(JSON.stringify({ status: "error", id: process.argv[1], message: String(error) })); })' <entry-id> || true
+   ```
+
+   The invocation is failure-safe by construction: a rejected import or write resolves to a structured `error` result instead of a crash, and the trailing `|| true` absorbs any remaining non-zero exit (missing `node`, unresolvable package). Record an `error` or non-zero outcome in the cycle summary and continue — the bump must never abort the lifecycle.
+
+   `confirmLearningEntry` advances ONLY `last_confirmed` — rule text, why, provenance, `first_learned`, and confidence are untouched — and is idempotent within a claim: a repeat same-date bump returns `unchanged`, so an entry that applied repeatedly during one claim is bumped once, not once per application.
+3. **Never block on it.** A failed bump, an unwritable file, or a `not-found` result (the entry was pruned) is recorded under the cycle summary and the claim proceeds — shipping the issue always outranks confirming a learning about it.
+
 #### 3d. Transition to $DONE (only after the PR is merged)
 
 A `done` env state (`status:on-dev`, `status:on-stg`, or the terminal value) asserts that the code has actually reached that environment. Never set it for a PR that is merely open: auto-merge can be blocked indefinitely (a required rebase / `BEHIND` branch, failing checks, an unaddressed review), and the change may never land. Relabeling an issue `status:on-stg` on an open PR makes it *claim* a deploy that never happened. Transition only after confirming the PR merged.

package/plugins/src/base/skills/lisa-jira-build-intake/SKILL.md

@@ -200,6 +200,8 @@ This gate never blocks a legitimate flat Task/Bug: those have no open children a
 
 **On `rejection-reclaim`, reflect before re-implementing** (per `rejection-detection`): read the rejection evidence through the access layer — the ticket comments posted after the backward transition (the QA rejection comment) via `lisa-atlassian-access operation: read-ticket` / `comment` reads and the review threads on the rejected PR — assemble ONE candidate learning (rule, why, provenance linking the rejection comment + rejected PR, evidence links, scope hint, triggering issue, fingerprint `sll4-sha1(rule\ntriggering_issue)[:12]`), and route it to the `lisa-persist-learning` skill. If that skill is absent, record the candidate via `lisa-atlassian-access operation: comment` as a comment carrying a **visible prose line plus** the marker (a bare marker renders as an empty bubble) — `Recorded a candidate learning from this rejection (queued for the judgment gate): <one-line candidate rule>.` then `<!-- [lisa-rejection-candidate] key=<issue>-<transition-ts> -->` — and proceed. Dedupe on `<issue>-<backward-transition-timestamp>` — a second re-claim produces no duplicate. Unreadable/absent evidence → no candidate, still implement.
 
+**Claim-time archaeology runs second — after rejection detection, still before the transition below.** Classify this ticket per the vendor-neutral `claim-archaeology` rule, with the rejection classification above as its input. All shared semantics — ancestry signals, classification, learning-loop exclusion, cost budget, candidate derivation, marker dedupe, and the never-block degrade — live in that one slug; change them there, never here. JIRA wiring only: the typed relations are already in the read bundle; text-similarity searches run through `lisa-atlassian-access operation: search-issues jql:` over recently-closed tickets; the fallback candidate comment is posted via `lisa-atlassian-access operation: comment`.
+
 Transition the ticket from `$READY` to `$CLAIMED` by invoking `lisa-atlassian-access` `operation: transition key: <TICKET> to: "$CLAIMED"`.
 - **Assign to the authenticated user when the ticket is unassigned.** A claim must be attributable. If the ticket has no assignee, assign it to the authenticated account — prefer acli `--assignee @me` (resolves server-side to the authenticated user, which avoids the federated-`accountId` mis-assignment), or `write-ticket` with the `accountId` from the `/rest/api/3/myself` identity probe the access skill already documents. Leave an already-assigned ticket's assignee untouched — never reassign work that already has an owner.
 - Post a `[claude-build-intake]` comment via `lisa-atlassian-access` `operation: comment key: <TICKET> body: "Claimed by Claude. Starting build."`
@@ -257,6 +259,22 @@ If the canonical fix is merged but not yet present on the production branch, app
 
 This path is distinct from `BLOCKED`: ambiguity, open blockers, and duplicate-of-open findings remain held for human action and must not be auto-closed.
 
+#### 3c.2 Confirm applied learnings (last_confirmed bump)
+
+Run this at the end of 3c, after the lifecycle outcome is recorded and before 3d. It keeps the decay pass safe: a genuinely useful learning that keeps applying stays fresh, while dead weight ages out.
+
+1. **Identify which learnings demonstrably applied.** Resolve the learnings surface with `resolveProjectLearningsFile` and parse it with `parseLearningsFile` from `@codyswann/lisa/learnings` (never hardcode the path; a missing file skips this step silently). An entry counts as applied ONLY when its rule was explicitly cited or observably followed in this claim's plan, diff, or review responses — the plan quotes the rule or its id, or the diff does specifically what the rule mandates where the default behavior would have differed. **Presence in context is NOT application**: the ledger is loaded eagerly into every session, so counting "it was loaded" would confirm every entry on every claim and defeat decay entirely. A run that produced no plan or diff has nothing to confirm.
+2. **Bump each applied entry exactly once** via the surgical writer:
+
+   ```bash
+   node -e 'import("@codyswann/lisa/learnings").then(async m => { const r = await m.confirmLearningEntry(process.cwd(), process.argv[1], new Date().toISOString().slice(0, 10)); console.log(JSON.stringify(r)); }).catch(error => { console.log(JSON.stringify({ status: "error", id: process.argv[1], message: String(error) })); })' <entry-id> || true
+   ```
+
+   The invocation is failure-safe by construction: a rejected import or write resolves to a structured `error` result instead of a crash, and the trailing `|| true` absorbs any remaining non-zero exit (missing `node`, unresolvable package). Record an `error` or non-zero outcome in the cycle summary and continue — the bump must never abort the lifecycle.
+
+   `confirmLearningEntry` advances ONLY `last_confirmed` — rule text, why, provenance, `first_learned`, and confidence are untouched — and is idempotent within a claim: a repeat same-date bump returns `unchanged`, so an entry that applied repeatedly during one claim is bumped once, not once per application.
+3. **Never block on it.** A failed bump, an unwritable file, or a `not-found` result (the entry was pruned) is recorded under the cycle summary and the claim proceeds — shipping the ticket always outranks confirming a learning about it.
+
 #### 3d. Transition to $DONE (only after the PR is merged)
 
 A `done` env status (`On Dev`, `On Stg`, or the terminal value) asserts that the code has actually reached that environment. Never set it for a PR that is merely open: auto-merge can be blocked indefinitely (a required rebase / `BEHIND` branch, failing checks, an unaddressed review), and the change may never land. Setting `On Stg` on an open PR makes a ticket *claim* a deploy that never happened. Transition only after confirming the PR merged.

package/plugins/src/base/skills/lisa-linear-build-intake/SKILL.md

@@ -190,6 +190,8 @@ This gate never blocks a legitimate flat Task/Bug: those have no open children a
 
 **On `rejection-reclaim`, reflect before re-implementing** (per `rejection-detection`): read the rejection evidence through the access layer — the Issue comments posted after the backward transition (the QA rejection comment) via `lisa-linear-access operation: list-comments` and the review threads on the rejected PR — assemble ONE candidate learning (rule, why, provenance linking the rejection comment + rejected PR, evidence links, scope hint, triggering issue, fingerprint `sll4-sha1(rule\ntriggering_issue)[:12]`), and route it to the `lisa-persist-learning` skill. If that skill is absent, record the candidate via `lisa-linear-access operation: save-comment` as a comment carrying a **visible prose line plus** the marker (a bare marker renders as an empty bubble) — `Recorded a candidate learning from this rejection (queued for the judgment gate): <one-line candidate rule>.` then `<!-- [lisa-rejection-candidate] key=<issue>-<transition-ts> -->` — and proceed. Dedupe on `<issue>-<backward-transition-timestamp>` — a second re-claim produces no duplicate. Unreadable/absent evidence → no candidate, still implement.
 
+**Claim-time archaeology runs second — after rejection detection, still before the relabel below.** Classify this Issue per the vendor-neutral `claim-archaeology` rule, with the rejection classification above as its input. All shared semantics — ancestry signals, classification, learning-loop exclusion, cost budget, candidate derivation, marker dedupe, and the never-block degrade — live in that one slug; change them there, never here. Linear wiring only: the native relations are already in the read bundle; text-similarity searches run through `lisa-linear-access operation: list-issues` filtered to recently-closed Issues; the fallback candidate comment is posted via `lisa-linear-access operation: save-comment`.
+
 Update labels via `lisa-linear-access operation: save-issue`: remove `$READY`, add `$CLAIMED`. Resolve label IDs via `list_issue_labels` (create `$CLAIMED` if missing).
 
 **Assign to the authenticated user when the Issue is unassigned.** A claim must be attributable. If the Issue has no assignee, set its `assigneeId` to the authenticated viewer (resolve the viewer's id via the Linear MCP identity — e.g. `get_user` for the current actor) through `lisa-linear-access operation: save-issue`. Leave an already-assigned Issue's assignee untouched — never reassign work that already has an owner.
@@ -250,6 +252,22 @@ If the canonical fix is merged but not yet present on the production branch, app
 
 This path is distinct from `BLOCKED`: ambiguity, open blockers, and duplicate-of-open findings remain held for human action and must not be auto-closed.
 
+#### 3c.2 Confirm applied learnings (last_confirmed bump)
+
+Run this at the end of 3c, after the lifecycle outcome is recorded and before 3d. It keeps the decay pass safe: a genuinely useful learning that keeps applying stays fresh, while dead weight ages out.
+
+1. **Identify which learnings demonstrably applied.** Resolve the learnings surface with `resolveProjectLearningsFile` and parse it with `parseLearningsFile` from `@codyswann/lisa/learnings` (never hardcode the path; a missing file skips this step silently). An entry counts as applied ONLY when its rule was explicitly cited or observably followed in this claim's plan, diff, or review responses — the plan quotes the rule or its id, or the diff does specifically what the rule mandates where the default behavior would have differed. **Presence in context is NOT application**: the ledger is loaded eagerly into every session, so counting "it was loaded" would confirm every entry on every claim and defeat decay entirely. A run that produced no plan or diff has nothing to confirm.
+2. **Bump each applied entry exactly once** via the surgical writer:
+
+   ```bash
+   node -e 'import("@codyswann/lisa/learnings").then(async m => { const r = await m.confirmLearningEntry(process.cwd(), process.argv[1], new Date().toISOString().slice(0, 10)); console.log(JSON.stringify(r)); }).catch(error => { console.log(JSON.stringify({ status: "error", id: process.argv[1], message: String(error) })); })' <entry-id> || true
+   ```
+
+   The invocation is failure-safe by construction: a rejected import or write resolves to a structured `error` result instead of a crash, and the trailing `|| true` absorbs any remaining non-zero exit (missing `node`, unresolvable package). Record an `error` or non-zero outcome in the cycle summary and continue — the bump must never abort the lifecycle.
+
+   `confirmLearningEntry` advances ONLY `last_confirmed` — rule text, why, provenance, `first_learned`, and confidence are untouched — and is idempotent within a claim: a repeat same-date bump returns `unchanged`, so an entry that applied repeatedly during one claim is bumped once, not once per application.
+3. **Never block on it.** A failed bump, an unwritable file, or a `not-found` result (the entry was pruned) is recorded under the cycle summary and the claim proceeds — shipping the Issue always outranks confirming a learning about it.
+
 #### 3d. Relabel to $DONE (only after the PR is merged)
 
 A `done` env state (`status:on-dev`, `status:on-stg`, or the terminal value) asserts that the code has actually reached that environment. Never set it for a PR that is merely open: auto-merge can be blocked indefinitely (a required rebase / `BEHIND` branch, failing checks, an unaddressed review), and the change may never land. Relabeling an Issue `status:on-stg` on an open PR makes it *claim* a deploy that never happened. Transition only after confirming the PR merged.