@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-devin/rules/reference/claim-archaeology.md

@@ -0,0 +1,184 @@
+# Claim-Time Archaeology
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## Claim-Time Archaeology (load-bearing)
+
+Lisa lifecycles are one-way — a done issue never reopens, so a residual failure comes back as a **new** issue with no visible link to the issue that shipped it. Archaeology recovers that link at claim time: the claiming agent learns it is working on round 2 of a past failure, and what specifically went wrong the first time.
+
+**One vendor-neutral contract, cited by every build-intake arm** (the `leaf-only-lifecycle` / `repo-scope-split` / `rejection-detection` precedent: one shared slug, never three divergent implementations).
+
+## When it runs
+
+In build-intake step 3b, **AFTER the rejection-detection classification and BEFORE the relabel/transition** `$READY → $CLAIMED`. Rejection detection runs first; its classification is an **input** to archaeology — a detected `rejection-reclaim` passes straight through, never re-derived.
+
+## Classify the claimed item
+
+Return exactly one of:
+
+- **`rejection-reclaim`** — taken directly from the `rejection-detection` result. Reuse it; do not re-derive.
+- **`retry-of-done-issue`** — an ancestry signal names a closed done issue whose shipped work this issue exists to fix.
+- **`fresh`** — no ancestor found, signals weak/inconclusive, budget exhausted, or the pass errored. The default and the safe degrade.
+
+## Ancestry signals (summary — full bindings in the reference body)
+
+1. **Tracker metadata** — the typed relations the read skills already parse (Blocks / Blocked by / Relates to / Duplicates / Cloned from, `closingIssuesReferences`, cross-references).
+2. **Text similarity** — tracker search primitives over recently-closed issues touching the same implicated files, ranked by title/label overlap. Lexical only; no embedding machinery exists.
+3. **Git ancestry** — deterministic `git log --follow` / `git blame` / merge-commit queries yielding a parseable `{file, sha, pr, date}` result. Never delegate this to the prose-report `git-history-analyzer` agent.
+
+## Learning-loop exclusion (scan-side)
+
+An artifact this flow produced is **never** an ancestor. Exclude anything carrying `[lisa-learning-drop]`, `[lisa-learning-pr]`, `[lisa-learning-upstream-handoff]`, `[lisa-rejection-candidate]`, or `[lisa-archaeology-candidate]` markers, or the `learning:needs-triage` label.
+
+## Cost budget — never block the claim
+
+The pass runs inside a hard budget: `.lisa.config.json` `archaeology.maxSteps` (default **8** tracker/git queries; optional `archaeology.maxSeconds`). Budget exhausted, weak signals, or an exception → classify `fresh` and proceed. Archaeology is a bonus layered on the claim; it **never blocks the claim**. Exceeding the budget degrades to `fresh` — a normal outcome, not an error.
+
+## On `retry-of-done-issue`
+
+Reconstruct what the ancestor's PR shipped (merged PR, review threads, evidence comments) and derive **ONE** candidate learning citing the **delta** between what was done and what this issue proves was needed — routed to `lisa-persist-learning` exactly like the rejection-reflection path. Fallback when that skill is absent: a comment with a visible prose line plus `<!-- [lisa-archaeology-candidate] key=<issue>::<ancestor> -->` (marker-dedupe; re-claims produce no duplicate). `fresh` → no candidate, zero comments.
+
+---
+
+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/lisa-devin/rules/reference/claim-evidence-mapping.md

@@ -0,0 +1,362 @@
+# Claim → Evidence Mapping Contract
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## Claim → Evidence Mapping Contract (load-bearing)
+
+**Every claim about the software declares a boundary, and a claim is established only by evidence of
+a kind that reaches that boundary.** Unit tests are a quality prerequisite, not a claim discharger:
+a passing unit `test-run-log` reaches only the **code-unit** boundary. Citing evidence whose *kind*
+does not reach a claim's *boundary* — a unit log offered as proof that a button works in the browser
+— is a contract violation, and a review-rejectable defect.
+
+## The claim-boundary taxonomy (closed set)
+
+Every claim binds to exactly one boundary, and each boundary is discharged only by evidence of the
+kind(s) that reach it. The boundaries and their establishing evidence kinds are seeded verbatim from
+the `verification` rule's artifact-type taxonomy — no new vocabulary is invented here:
+
+- **`code-unit`** — pure-logic behavior in isolation → unit `test-run-log`. Reaches no boundary
+  below it.
+- **`browser`** — user-visible UI behavior → `screenshot`, `recording`. **Never** a unit
+  `test-run-log`.
+- **`http-api`** — request/response contract → `http-transcript`. **Never** a unit `test-run-log`.
+- **`cli`** — command behavior → `cli-output`.
+- **`data`** — persisted state → `db-query-output`, `state-dump`.
+- **`deploy-health`** — a healthy running deployment → `deploy-log`. **Never** any pre-deploy
+  artifact.
+- **`performance`** — latency/throughput/frame timing → `perf-trace` (with methodology).
+- **`standards-compat`** — conformance to an external standard → `cli-output` / `test-run-log` from
+  the compat runner.
+
+## The core inequality
+
+**unit tests ≠ browser behavior ≠ healthy deployment ≠ standards compatibility.** Each is a distinct
+boundary; evidence at one never discharges a claim at another. "Verified" must name the boundary its
+evidence actually reaches, so a report read at the gate states its own limits (`factory-model`
+rule 5).
+
+## Field names (fixed here, made executable later)
+
+A claim carries three fields — `claim_id`, `boundary`, and `required_evidence_kinds` — named here so
+every downstream surface uses one spelling. This ticket only writes the contract down; the schema and
+gate that make these fields executable ship with **BCE-2 (#1836)** — do not assume that surface is
+present in this branch.
+
+## Security buckets (conservative by default)
+
+A security finding is **proven** only with both a reproducer of a reaching kind and a bounded
+impact/exploitability statement; missing either, it renders **unproven** with its reason and **stays
+in the security section** — never auto-demoted to maintenance. The label is one policy point,
+`security.review.unprovenBucket` (default `security-unproven`); the procedure lives in the
+`lisa-security-review` skill.
+
+## Artifact identity (pinned, never assumed)
+
+A claim applies only to the artifact its evidence was collected against. Every verdict pins
+`artifact.head_sha` — the commit the run observed — and every evidence entry pins the
+`artifact_head_sha` in force when it was captured, its `sha256` content digest, and `captured_at`.
+Evidence collected on a pre-merge head is valid for the merge commit **only** when that head is a
+parent of the merge, per the ancestry + deploy-run definition of "what shipped" that
+`lisa-drive-pr-to-merge` already owns — cite it, never write a second one. A mismatched SHA or a
+recomputed digest that disagrees fails loudly, naming both SHAs / the evidence id, and verification
+re-runs against the merged head before completion is declared. Full definition: the reference body.
+
+## Not established (required, never omitted)
+
+A claim with no reaching evidence is **Not established**, and every report says so out loud. Each
+evidence comment and verdict carries a `Not established` section listing what was *not* proved —
+boundaries not exercised, environments not tested, behavior consciously out of scope. It is never
+omitted and never blank: with nothing outstanding it still renders `None outstanding — reviewed`, and
+`not_established_reviewed` attests the list was reviewed even when the list itself is empty. This
+generalizes the required, never-empty `Known limits` field of `lisa-improve-harness`. Full definition
+and operator-voice exemplars: the reference body.
+
+## No behavior change; degrade, never block
+
+This rule is documentation, not a gate: it changes no schema, no skill, and no check. Where a later
+surface it names is not yet installed, cite the boundary a claim reaches and continue — never block
+on the absent surface. Read the contract to someone who has never seen Lisa and they should be able
+to say why a unit-test log does not prove a button works in the browser.
+
+---
+
+Lisa's verification machinery already proves outcomes empirically, but nothing states *which kind of
+evidence establishes which kind of claim*. So a claim about browser-visible behavior, supported only
+by a unit-test log, currently reads as "verified" — the report never names the boundary its evidence
+actually reaches. This contract writes the mapping down once, as the single spine every evidence
+surface cites: **every claim declares a boundary, and a claim is established only by evidence of a
+kind that reaches that boundary.**
+
+It is a **single vendor-neutral contract**. The later tickets of this PRD instantiate it rather than
+redefine it: the `verification-status.json` schema and gate that make the claim fields executable
+(**BCE-2, #1836**), the *Not-established* section and evidence templates (**BCE-3, #1837**), artifact
+identity (**BCE-4, #1838**), and security buckets (**BCE-5, #1839**) each cite this slug. This ticket
+adds no schema, no gate, and no skill edit — exactly as the `automation-runbook-contract` rule
+preceded the skills that made it executable.
+
+## Consumers
+
+Every surface that asserts a claim is proved cites this contract for what "proved" means at that
+claim's boundary: the verification flow and its `verification-specialist`, the evidence-posting and
+completion gates, the QA and Verify factories' reports, and any report a human reads at a gate. None
+of them redefines the mapping; each binds its claim to a boundary and cites evidence of a reaching
+kind.
+
+## The claim-boundary taxonomy
+
+Every claim binds to exactly one **boundary**. The table binds each boundary to the evidence kind(s)
+that establish it and at least one kind that cannot. The **establishing evidence kind(s)** column is
+drawn verbatim from the `verification` rule's artifact-type taxonomy (its fixed set:
+`screenshot`, `recording`, `http-transcript`, `cli-output`, `log-snippet`, `db-query-output`,
+`perf-trace`, `test-run-log`, `deploy-log`, `state-dump`) — this contract invents no new evidence
+types; it only says which reach which boundary.
+
+| Claim boundary | What it asserts | Establishing evidence kind(s) | Cannot be established by |
+|---|---|---|---|
+| `code-unit` | pure-logic behavior in isolation | `test-run-log` (unit) | — (but never satisfies any boundary below) |
+| `browser` | user-visible UI behavior | `screenshot`, `recording` | unit `test-run-log` |
+| `http-api` | request/response contract | `http-transcript` | unit `test-run-log` |
+| `cli` | command behavior | `cli-output` | prose |
+| `data` | persisted state | `db-query-output`, `state-dump` | unit `test-run-log` |
+| `deploy-health` | a healthy running deployment | `deploy-log` | any pre-deploy artifact |
+| `performance` | latency/throughput/frame timing | `perf-trace` (with methodology) | screenshot |
+| `standards-compat` | conformance to an external standard | `cli-output` / `test-run-log` from the compat runner | assertion prose |
+
+Reciprocal cross-link: the `verification` rule's artifact-type taxonomy is the source of the
+establishing-evidence column above; that rule's reference body should point back here for the
+boundary each type reaches. Cite these slugs, do not restate them: `verification` (the artifact-type
+taxonomy), `factory-model` (operator-readable writing — rule 5), and `empirical-inquiry` (observe the
+real result before claiming).
+
+## The core inequality
+
+The whole contract reduces to one inequality, stated explicitly so no surface can blur it:
+
+**unit tests ≠ browser behavior ≠ healthy deployment ≠ standards compatibility.**
+
+A passing unit `test-run-log` establishes only `code-unit` behavior. It can **never** establish a
+`browser`, `http-api`, `deploy-health`, or `standards-compat` claim — those live at boundaries a
+unit test does not reach. Unit tests are a *quality prerequisite* (they gate the commit); they are
+not a *claim discharger* for any boundary above `code-unit`. Symmetrically, a green `deploy-log`
+proves a healthy deployment but says nothing about whether the UI renders correctly, and a
+`screenshot` proves the pixels but not the latency. Each boundary stands on its own evidence.
+
+## The review-rejection rule
+
+Citing evidence whose *kind* does not reach a claim's *boundary* is a **review-rejectable defect** —
+a machine-checkable one once BCE-2's gate ships, and a review-rejectable one in prose review today.
+"It passed unit tests" is not an answer to "does the button work in the browser." A reviewer rejects
+the claim, names the boundary, and asks for evidence of a reaching kind.
+
+## The claim fields
+
+A claim is three fields, named here so BCE-2's schema reuses one spelling — this contract only
+defines the names; it stores nothing:
+
+| Field | Meaning |
+|---|---|
+| `claim_id` | stable identifier for the claim being made |
+| `boundary` | exactly one value from the claim-boundary taxonomy above |
+| `required_evidence_kinds` | the evidence kind(s) that reach that boundary, from the `verification` artifact-type set |
+
+A claim whose `required_evidence_kinds` has no captured, reaching artifact is **Not established** —
+defined in full, with its evidence templates, in the section below. Artifact identity — what makes
+two captured artifacts the same or different — is defined in the *Artifact identity* section below
+(shipped by BCE-4, #1838). The bucket a security-sensitive claim lands in is defined in the *Security
+buckets* section below (shipped by BCE-5, #1839). Where such a sibling surface is not installed in a
+given branch, name what you can and continue.
+
+### Worked example
+
+```text
+Claim: "The checkout button submits the order and shows a confirmation."
+
+  boundary                 browser
+  required_evidence_kinds  screenshot | recording
+
+  Reaching evidence   A screenshot of the confirmation state after a real click, or a
+                      recording of the click-through. EITHER establishes the browser claim.
+
+  Non-reaching        A passing unit test-run-log for the submit handler. It establishes the
+                      code-unit boundary only — the handler's logic in isolation — and can
+                      NEVER establish this browser claim. Offered as proof here, it is a
+                      review-rejectable defect; the claim stays Not established until a
+                      screenshot or recording is captured.
+
+Claim: "The service is deployed and healthy."
+
+  boundary                 deploy-health
+  required_evidence_kinds  deploy-log
+
+  Non-reaching        Any pre-deploy artifact — a green CI test-run-log, a local screenshot.
+                      A healthy deployment is established only by a deploy-log / health-check
+                      response from the target environment.
+```
+
+## Artifact identity — what the evidence was collected against
+
+A claim reaches only as far as its evidence's *kind*; it applies only to the *artifact* that evidence
+was collected against. **Artifact identity is what makes two captured artifacts the same or
+different**: one repository, at one commit, in one environment, at one moment. Evidence that does not
+say which artifact it observed is not evidence about anything in particular — it silently transfers
+to whatever ships next, which is exactly how an auto-merge race ships code no verification ever
+touched.
+
+Identity is carried in two places, and they must agree:
+
+| Where | Field | What it pins |
+|---|---|---|
+| `artifact` (once per verdict) | `repository` | the `owner/repo` the run observed |
+| | `base_sha` | the base the change was measured against |
+| | `head_sha` | **the commit the verification actually observed** — required for a v2 pass |
+| | `build_id` | the build/run the evidence came from, where one exists |
+| | `environment` | where it ran (local, preview, staging, production) |
+| | `observed_at` | when the run observed it (ISO-8601 UTC) |
+| `evidence[]` (per artifact) | `artifact_head_sha` | the `head_sha` in force **when that artifact was captured** |
+| | `sha256` | content digest of the committed evidence file |
+| | `captured_at` | when that artifact was captured (ISO-8601 UTC) |
+
+`head_sha` pins the *build*; `sha256` pins the *bytes*. Together they answer both identity questions:
+"which artifact was this collected against" and "is this still the artifact that was collected". The
+`sha256` + commit-ref discipline is the same one Lisa's upstream-evidence manifest already uses — it
+is cited as prior art here, not reinvented.
+
+### Two identity failures, both loud
+
+- **`artifact_mismatch`** — an `evidence[]` entry whose `artifact_head_sha` differs from the verdict's
+  `artifact.head_sha`. The evidence describes a different build than the one the verdict claims. The
+  identity check fails **loudly, naming both SHAs** (the evidence's and the verdict's) so an operator
+  can see which build each half is talking about.
+- **`evidence_digest_mismatch`** — on read, recompute the `sha256` of each committed evidence file. If
+  the bytes no longer match the recorded digest, the artifact has changed since it was recorded: the
+  check fails, it names the evidence id, and blocks completion. A digest that cannot be recomputed
+  (file absent) is the same failure.
+
+Neither failure is ever summarized as "verification failed". Name the field, the ids, and both SHAs —
+a person who does not code reads this at the gate (`factory-model` rule 5). Both checks are
+**advisory-first**: reported to the operator but non-blocking until
+`verification.gate.enforceBoundaries` is `true` in `.lisa.config.json` — the same ratchet flag the
+boundary checks and the Stop-hook gate ride.
+
+### The merge race — one definition, two guards
+
+"The artifact that shipped" is already defined once, in `lisa-drive-pr-to-merge`: the **ancestry**
+check (is the verified commit an ancestor of the merged base branch, and is the merge commit's parent
+that verified head rather than a stale one) **plus** the **deploy-run** check (a deploy/release run
+actually fired for the merge SHA or an including descendant). Cite that definition; never write a
+second one. Identity reconciliation is the same definition read from the evidence side:
+
+- Evidence collected on a **pre-merge head** is valid for the merge commit **only when that head is a
+  parent of the merge** — i.e. it satisfies that skill's ancestry check against the merged head. If a
+  late commit raced past the merge, the merged head is not the verified one and the evidence does not
+  transfer.
+- Ancestry alone is never enough. That skill's rule stands unchanged here: **never report shipped on
+  ancestry alone** — the deploy-run check must also pass before completion is declared.
+- On mismatch (`artifact.head_sha` ≠ the reconciled merge SHA), completion is not declared. Flag the
+  mismatch naming both SHAs and **re-run verification against the merged head**; the re-run's verdict
+  is what may declare completion.
+
+Two guards, one definition — so they cannot disagree about what shipped.
+
+## Security buckets — the impact-or-exploitability bar
+
+A security-shaped claim is a claim like any other: it reaches only as far as its evidence. Applied to
+security findings (shipped by BCE-5, #1839), that yields two buckets and one bar:
+
+- **Security (proven)** — the finding carries **both** a `reproducer` (an evidence ref of a kind that
+  reaches the claim's boundary, per the taxonomy above — e.g. an `http-transcript` for an injection
+  claim at `http-api`) **and** a bounded `impact`/exploitability statement.
+- **Security (unproven)** — **missing either**. It keeps a one-line `reason` and **stays in the
+  security section**: a reproducer-less finding is **never auto-demoted** to a `maintenance` bucket,
+  because under-reporting a real vulnerability is the worse failure.
+
+The unproven bucket's label is the single configurable policy point —
+`security.review.unprovenBucket` in `.lisa.config.json`, default `security-unproven`. An owner who
+prefers true demotion flips that one value; no other classification logic changes. Like the boundary
+checks, bucketing is **advisory** — it shapes the report, not the merge — until
+`verification.gate.enforceBoundaries` is `true`.
+
+The full procedure — per-finding fields, report shape, ZAP alignment — lives in the
+`lisa-security-review` skill (with `lisa-security-zap-scan` citing it); dependency-CVE remediation
+keeps its separate ladder in `security-audit-handling`. Cite those slugs; do not restate them here.
+
+## The "Not established" section — required, never omitted
+
+Every report that asserts something was verified also states, in the same breath, **what it did not
+establish**. This is one section, it is **required**, and it is **never omitted and never blank** —
+on the evidence comment, in the committed `evidence/<ticket>/verdict.json`, and in the
+`verification-status.json` verdict BCE-2's gate reads.
+
+**Where it appears and what it says**
+
+| Surface | Shape |
+|---|---|
+| Evidence comment (tracker + PR `## Evidence` section) | a `## Not established` heading, one plain-language bullet per item |
+| `evidence/<ticket>/verdict.json` | `not_established: []` plus `not_established_reviewed: true` |
+| `.lisa/verification-status.json` (schema v2) | per-claim `not_established[]` plus the top-level `not_established_reviewed` flag |
+
+**The empty case is not the omitted case.** A verification that genuinely left nothing unproved still
+renders the heading, with the single line:
+
+```text
+## Not established
+
+None outstanding — reviewed
+```
+
+An absent heading, or a heading with nothing under it, is a defect — it is indistinguishable from
+never having asked the question. The list may be empty; the section may not be blank.
+
+**Machine-readable semantics (as shipped by BCE-2, #1836).** `not_established` is the list — it may
+be empty. `not_established_reviewed` is the boolean attestation that the list was actually
+reviewed — **the flag may never be omitted**. That asymmetry is the whole mechanism: an empty list
+plus a present flag means "we looked and found nothing outstanding"; an absent flag means nobody
+looked. The Stop-hook gate treats an absent flag as a v2 contract violation, reported to stderr and
+**advisory** until `verification.gate.enforceBoundaries` is `true` in `.lisa.config.json` (the same
+ratchet flag the boundary checks ride); evidence surfaces refuse the post on the same terms.
+
+**What belongs under the heading** — written in operator voice (`factory-model` rule 5: a person who
+does not code reads this at the gate), not in engineering shorthand:
+
+- **Boundaries not exercised** — a claim's boundary that no captured artifact reached. *"The checkout
+  button was proved in the browser; the order's persisted row was never queried, so the `data`
+  boundary is not established."*
+- **Environments not tested** — where it was and was not run. *"Checked on production Chrome at
+  1440×900 only. Not checked on mobile Safari, and not checked against the staging database."*
+- **Claims consciously out of scope** — deliberately excluded behavior, named so nobody infers it.
+  *"Refunds were not touched or tested; this change covers new orders only."*
+- **Anything a green quality check might be mistaken for proving.** *"Unit tests pass for the submit
+  handler. That establishes the code-unit boundary only — it is not evidence the button works."*
+
+Each item names the thing, not a category: "not tested on mobile Safari" is usable at a gate; "some
+environments untested" is not.
+
+### Philosophical precedent for this section
+
+This generalizes `lisa-improve-harness`'s **`Known limits`** field — a required, never-empty line on
+every result record. That skill says it plainly:
+*"A record with nothing in it is invalid on its face"* — because a single-trajectory loop always has
+limits. The same is true of any verification:
+it ran somewhere, on something, once. `Known limits` (one record) and `not_established` (every claim
+in the factory) are the same discipline with the same never-empty rule; read either and you should
+recognize the other.
+
+## Philosophical precedent
+
+This generalizes the **bounded-claim discipline** of `lisa-improve-harness`: one trajectory supports
+one trajectory's claim, and a result record may claim only what its cited evidence reaches. Here the
+same discipline is applied to every claim in the factory — a claim reaches exactly as far as the
+*kind* of evidence behind it, and no further. The *Not established* half of that discipline is a
+first-class report state — see the required, never-omitted section above.
+
+## No behavior change; degrade, never block
+
+This rule ships as documentation that later tickets make executable. It changes no schema, no gate,
+and no skill. Where a surface it names (BCE-2's gate, BCE-3's templates) is not yet installed in a
+given branch, name the boundary a claim reaches and continue — the contract never blocks on an absent
+sibling surface. Every claim written under it must be operator-readable (`factory-model` rule 5): a
+person who does not code should be able to read the boundary and see why the evidence does or does
+not reach it.